minor doc touchup

include/hcc_detail/hip_runtime.h

@@ -21,7 +21,7 @@ THE SOFTWARE.
 */
 /**
  *  @file  hcc_detail/hip_runtime.h
- *
+ *  @brief Contains definitions of APIs for HIP runtime.
  */
 
 #pragma once

include/hcc_detail/hip_runtime_api.h

@@ -21,6 +21,10 @@ THE SOFTWARE.
 */
 #pragma once
 
+/**
+ *  @file  hcc_detail/hip_runtime_api.h
+ *  @brief Contains C function APIs for HIP runtime. This file does not use any HCC builtin or special language extensions (-hc mode) ; those functions in hip_runtime.h.
+ */
 
 #include <stdint.h>
 #include <stddef.h>
@@ -31,12 +35,6 @@ THE SOFTWARE.
 #error("This version of HIP requires a newer version of HCC.");
 #endif
 
-
-// hip_api_hcc.h
-// Contains C function APIs for HIP runtime.
-// This file does not use any HCC builtins or special language extensions (-hc mode) ; those functions in hip_hcc.h.
-
-
 // Structure definitions:
 #ifdef __cplusplus
 extern "C" {
@@ -59,7 +57,7 @@ extern "C" {
 
 
 /**
- * @warning On AMD devices and recent NVIDIA devices, these hints and controls are ignored.
+ * @warning On AMD devices and recent Nvidia devices, these hints and controls are ignored.
  */
 typedef enum hipFuncCache {
     hipFuncCachePreferNone, ///< no preference for shared memory or L1 (default)
@@ -70,7 +68,7 @@ typedef enum hipFuncCache {
 
 
 /**
- * @warning On AMD devices and recent NVIDIA devices, these hints and controls are ignored.
+ * @warning On AMD devices and recent Nvidia devices, these hints and controls are ignored.
  */
 typedef enum hipSharedMemConfig {
     hipSharedMemBankSizeDefault,   ///< The compiler selects a device-specific value for the banking.
@@ -257,7 +255,7 @@ hipError_t hipDeviceGetProperties(hipDeviceProp_t* prop, int device);
 /**
  * @brief Set L1/Shared cache partition.
  *
- * Note: AMD devices and recent NVIDIA GPUS do not support reconfigurable cache.  This hint is ignored on those architectures.
+ * Note: AMD devices and recent Nvidia GPUS do not support reconfigurable cache.  This hint is ignored on those architectures.
  *
  */
 hipError_t hipDeviceSetCacheConfig ( hipFuncCache cacheConfig );
@@ -266,7 +264,7 @@ hipError_t hipDeviceSetCacheConfig ( hipFuncCache cacheConfig );
 /**
  * @brief Set Cache configuration for a specific function
  *
- * Note: AMD devices and recent NVIDIA GPUS do not support reconfigurable cache.  This hint is ignored on those architectures.
+ * Note: AMD devices and recent Nvidia GPUS do not support reconfigurable cache.  This hint is ignored on those architectures.
  *
  */
 hipError_t hipDeviceGetCacheConfig ( hipFuncCache *cacheConfig );
@@ -275,7 +273,7 @@ hipError_t hipDeviceGetCacheConfig ( hipFuncCache *cacheConfig );
 /**
  * @brief Set Cache configuration for a specific function
  *
- * Note: AMD devices and recent NVIDIA GPUS do not support reconfigurable cache.  This hint is ignored on those architectures.
+ * Note: AMD devices and recent Nvidia GPUS do not support reconfigurable cache.  This hint is ignored on those architectures.
  *
  */
 hipError_t hipFuncSetCacheConfig ( hipFuncCache config );
@@ -286,7 +284,7 @@ hipError_t hipFuncSetCacheConfig ( hipFuncCache config );
 /**
  * @brief Get Shared memory bank configuration.
  *
- * Note: AMD devices and recent NVIDIA GPUS do not support shared cache banking, and the hint is ignored on those architectures.
+ * Note: AMD devices and recent Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.
  *
  */
 hipError_t hipDeviceGetSharedMemConfig ( hipSharedMemConfig * pConfig );
@@ -295,7 +293,7 @@ hipError_t hipDeviceGetSharedMemConfig ( hipSharedMemConfig * pConfig );
 /**
  * @brief Set Shared memory bank configuration.
  *
- * Note: AMD devices and recent NVIDIA GPUS do not support shared cache banking, and the hint is ignored on those architectures.
+ * Note: AMD devices and recent Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.
  *
  */
 hipError_t hipDeviceSetSharedMemConfig ( hipSharedMemConfig config );
@@ -607,7 +605,7 @@ hipError_t hipEventElapsedTime(float *ms, hipEvent_t start, hipEvent_t stop);
  *
  * Query the status of the specified event.  This function will return #hipErrorNotReady if all commands
  * in the appropriate stream (specified to hipEventRecord) have completed.  If that work has not completed,
- * or if hipEventRecord was not called on the event, then cudaSuccess is returned. 
+ * or if hipEventRecord was not called on the event, then hipSuccess is returned.
  *
  *
  */
@@ -638,7 +636,7 @@ hipError_t hipEventQuery(hipEvent_t event) ;
 
 
 /**
- *  Allocate memory on the default accelerator
+ *  @brief Allocate memory on the default accelerator
  *
  *  @param[out] ptr Pointer to the allocated memory
  *  @param[in]  size Requested memory size
@@ -648,89 +646,118 @@ hipError_t hipMalloc(void** ptr, size_t size) ;
 
 
 /**
- *  Allocate pinned host memory
+ *  @brief Allocate pinned host memory
  *
- *  @param[in]  ptr Pointer to the allocated host pinned memory
+ *  @param[out]  ptr Pointer to the allocated host pinned memory
- *  @param[out] size Requested memory size
+ *  @param[in] size Requested memory size
  *  @return Error code
  */
 hipError_t hipMallocHost(void** ptr, size_t size) ;
 
 
-
-// TODO-doc (error codes)
 /**
- *  Free memory allocated by the hcc hip memory allocation API.
+ *  @brief Free memory allocated by the hcc hip memory allocation API.
  *  This API performs an implicit hipDeviceSynchronize() call.
  *
  *  @param[in] ptr Pointer to memory to be freed
- *  @return Error code
+ *  @return #hipSuccess, #hipErrorMemoryFree
  */
 hipError_t hipFree(void* ptr);
 
 
 
-// TODO-doc (error codes)
 /**
- *  Free memory allocated by the hcc hip host memory allocation API
+ *  @brief Free memory allocated by the hcc hip host memory allocation API
  *
  *  @param[in] ptr Pointer to memory to be freed
- *  @return Error code
+ *  @return #hipSuccess, #hipErrorMemoryFree
  */
 hipError_t hipFreeHost(void* ptr);
 
 
 
-
-// TODO-doc (error codes)
 /**
- *  Copy data from src to dst.  It supports memory from host to device,
+ *  @brief Copy data from src to dst.
+ *
+ *  It supports memory from host to device,
  *  device to host, device to device and host to host
  *  The src and dst must not overlap.
- *  If the 
+ *  TODO: cudaErrorInvalidMemcpyDirection error code is not supported right now, use hipErrorUnknown for now
  *
- *  This function is host-synchronous for most inputs.  
+ *  @param[out]  dst Data being copy to
- *  It uses the default NULL stream and will synchronize with other blocking streams on the same device.
- *
- *  @param[ being copy to
  *  @param[in]  src Data being copy from
  *  @param[in]  sizeBytes Data size in bytes
  *  @param[in]  copyType Memory copy type
- *  @return Error code
+ *  @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryFree, #hipErrorUnknown
  */
 hipError_t hipMemcpy(void* dst, const void* src, size_t sizeBytes, hipMemcpyKind kind);
 
 
+/**
+ *  @brief Copies @p sizeBytes bytes from the memory area pointed to by @p src to the memory area pointed to by @p offset bytes from the start of symbol @p symbol.
+ *
+ *  The memory areas may not overlap. Symbol can either be a variable that resides in global or constant memory space, or it can be a character string,
+ *  naming a variable that resides in global or constant memory space. Kind can be either hipMemcpyHostToDevice or hipMemcpyDeviceToDevice
+ *  TODO: cudaErrorInvalidSymbol and cudaErrorInvalidMemcpyDirection is not supported, use hipErrorUnknown for now.  
+ *
+ *  @param[in]  symbolName - Symbol destination on device
+ *  @param[in]  src - Data being copy from
+ *  @param[in]  sizeBytes - Data size in bytes
+ *  @param[in]  offset - Offset from start of symbol in bytes
+ *  @param[in]  kind - Type of transfer
+ *  @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryFree, #hipErrorUnknown
+ */
 hipError_t hipMemcpyToSymbol(const char* symbolName, const void *src, size_t sizeBytes, size_t offset, hipMemcpyKind kind);
 
 
-
-// TODO-doc (error codes)
 /**
- *  Copy data from src to dst asynchronously.  It supports memory from host to device,
+ *  @brief Copy data from src to dst asynchronously.
+ *
+ *  TODO: cudaErrorInvalidMemcpyDirection error code is not supported right now, use hipErrorUnknown for now
+ *
+ *  @param[out] dst Data being copy to
+ *  @param[in]  src Data being copy from
+ *  @param[in]  sizeBytes Data size in bytes
+ *  @param[in]  accelerator_view Accelerator view which the copy is being enqueued
+ *  @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryFree, #hipErrorUnknown
+ */
+hipError_t hipMemcpyAsync(void* dst, const void* src, size_t sizeBytes, hipMemcpyKind kind, hipStream_t stream=0);
+
+
+/**
+ *  @brief Copy data from src to dst asynchronously.
+ *
+ * It supports memory from host to device,
  *  device to host, device to device and host to host.
  *
  *  @param[out] dst Data being copy to
  *  @param[in]  src Data being copy from
  *  @param[in]  sizeBytes Data size in bytes
  *  @param[in]  accelerator_view Accelerator view which the copy is being enqueued
- *  @return Error code
+ *  @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryFree
  */
-hipError_t hipMemcpyAsync(void* dst, const void* src, size_t sizeBytes, hipMemcpyKind kind, hipStream_t stream=0);
-
-
-// TODO-doc
-/*
- * This function is host-asynchronous and may return before the memset operation completes.
- * Same as hipMemsetAsync with null stream.
- *
- * */
 hipError_t hipMemset(void* dst, int  value, size_t sizeBytes );
+
+
+/**
+ *  @brief Fills the first sizeBytes bytes of the memory area pointed to by dev with the constant byte value value.
+ *
+ *  hipMemsetAsync() is asynchronous with respect to the host, so the call may return before the memset is complete.
+ *  The operation can optionally be associated to a stream by passing a non-zero stream argument.
+ *  If stream is non-zero, the operation may overlap with operations in other streams.
+ *
+ *  @param[out] dst Pointer to device memory
+ *  @param[in]  value - Value to set for each byte of specified memory
+ *  @param[in]  sizeBytes - Size in bytes to set
+ *  @param[in]  stream - Stream identifier
+ *  @return #hipSuccess, #hipErrorInvalidValue, #hipErrorMemoryFree
+ */
 hipError_t hipMemsetAsync(void* dst, int  value, size_t sizeBytes, hipStream_t = 0 );
 
 
 /*
- * @brief Query memory info.  Return snapshot of free memory, and total allocatable memory on the device.
+ * @brief Query memory info.
+ * Return snapshot of free memory, and total allocatable memory on the device.
  *
  * Returns in *free a snapshot of the current free memory o
  **/
@@ -759,20 +786,60 @@ hipError_t hipMemGetInfo  (size_t * free, size_t * total)   ;
  * @param [in] peerDevice
  *
  * Returns "1" in @p canAccessPeer if the specified @p device is capable
- * of directly accessing memory phyically located on peerDevice , or "0" if not.
+ * of directly accessing memory physically located on peerDevice , or "0" if not.
  */
 hipError_t hipDeviceCanAccessPeer ( int* canAccessPeer, int  device, int  peerDevice );
 
-// TODO-DOC
+
+
+/**
+ * @brief Disables registering memory on peerDevice for direct access from the current device.
+ *
+ * If there are any allocations on peerDevice which were registered in the current device using hipPeerRegister() then these allocations will be automatically unregistered.
+ * Returns hipErrorPeerAccessNotEnabled if direct access to memory on peerDevice has not yet been enabled from the current device.
+ *
+ * @param [in] peerDevice
+ * TODO:cudaErrorPeerAccessNotEnabled and cudaErrorInvalidDevice error not supported in HIP, return hipErrorUnknown
+ * Returns #hipSuccess, #hipErrorUnknown
+ */
 hipError_t  hipDeviceDisablePeerAccess ( int  peerDevice );
 
-// TODO-DOC
+/**
+ * @brief Enables registering memory on peerDevice for direct access from the current device.
+ *
+ * @param [in] peerDevice
+ * @param [in] flags
+ *
+ * TODO:cudaErrorInvalidDevice error not supported in HIP, return hipErrorUnknown
+ * Returns #hipSuccess, #hipErrorInvalidDevice, #hipErrorInvalidValue, #hipErrorUnknown
+ */
 hipError_t  hipDeviceEnablePeerAccess ( int  peerDevice, unsigned int  flags );
 
-// TODO-DOC
+/**
+ * @brief Copies memory from one device to memory on another device.
+ *
+ * @param [out] dst - Destination device pointer.
+ * @param [in] dstDevice - Destination device
+ * @param [in] src - Source device pointer
+ * @param [in] srcDevice - Source device
+ * @param [in] sizeBytes - Size of memory copy in bytes
+ *
+ * Returns #hipSuccess, #hipErrorInvalidValue, #hipErrorInvalidDevice
+ */
 hipError_t hipMemcpyPeer ( void* dst, int  dstDevice, const void* src, int  srcDevice, size_t sizeBytes );
 
-// TODO-DOC
+/**
+ * @brief Copies memory from one device to memory on another device.
+ *
+ * @param [out] dst - Destination device pointer.
+ * @param [in] dstDevice - Destination device
+ * @param [in] src - Source device pointer
+ * @param [in] srcDevice - Source device
+ * @param [in] sizeBytes - Size of memory copy in bytes
+ * @param [in] stream - Stream identifier
+ *
+ * Returns #hipSuccess, #hipErrorInvalidValue, #hipErrorInvalidDevice
+ */
 hipError_t hipMemcpyPeerAsync ( void* dst, int  dstDevice, const void* src, int  srcDevice, size_t sizeBytes, hipStream_t stream=0 );
 // doxygen end PeerToPeer
 /**
@@ -789,13 +856,13 @@ hipError_t hipMemcpyPeerAsync ( void* dst, int  dstDevice, const void* src, int
  */
 
 /**
- * @brief Returns the approximate HIP driver versin.
+ * @brief Returns the approximate HIP driver version.
  *
- * @warning The HIP feature set does not correpond to an exact CUDA SDK driver revision.  
+ * @warning The HIP feature set does not correspond to an exact CUDA SDK driver revision.
  * This function always set *driverVersion to 4 as an approximation though HIP supports
  * some features which were introduced in later CUDA SDK revisions.
  * HIP apps code should not rely on the driver revision number here and should
- * use arch feature flags to test device capabiliies or conditional compilation.
+ * use arch feature flags to test device capabilities or conditional compilation.
  *
  */
 hipError_t hipDriverGetVersion(int *driverVersion) ;
@@ -815,7 +882,7 @@ hipError_t hipDriverGetVersion(int *driverVersion) ;
  *  @{
  *
  *
- *  The cudaProfilerInitialize API format for "configFile" is not supported.  
+ *  @warning The cudaProfilerInitialize API format for "configFile" is not supported.
  *
  *  On AMD platforms, hipProfilerStart and hipProfilerStop require installation of AMD's GPU
  *  perf counter API and defining GPU_PERF
@@ -854,12 +921,12 @@ hipError_t hipDriverGetVersion(int *driverVersion) ;
 #ifdef __HCC__
 #include <hc.hpp>
 /**
- * @brief Return hc::acclerator associated with the specified deviceId
+ * @brief Return hc::accelerator associated with the specified deviceId
  */
 hipError_t hipHccGetAccelerator(int deviceId, hc::accelerator *acc);
 
 /**
- * @brief Return hc::acclerator_view associated with the specified stream
+ * @brief Return hc::accelerator_view associated with the specified stream
  */
 hipError_t hipHccGetAcceleratorView(hipStream_t stream, hc::accelerator_view **av);
 #endif

include/hcc_detail/hip_texture.h

@@ -21,7 +21,7 @@ THE SOFTWARE.
 */
 #pragma once
 /**
- *  @file  hip_kalmar_texture.h
+ *  @file  hcc_detail/hip_texture.h
  *  @brief HIP C++ Texture API for hcc compiler
  */
 

include/hcc_detail/hip_vector_types.h

@@ -19,6 +19,12 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 */
+
+/**
+ *  @file  hcc_detail/hip_vector_types.h
+ *  @brief Defines the different newt vector types for HIP runtime.
+ */
+
 #if defined (__HCC__) &&  (__hcc_workweek__ < 16032)
 #error("This version of HIP requires a newer version of HCC.");
 #endif

include/hcc_detail/host_defines.h

@@ -19,6 +19,12 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 */
+
+/**
+ *  @file  hcc_detail/host_defines.h
+ *  @brief TODO-doc
+ */
+
 #ifdef __HCC__
 /**
  * Function and kernel markers

include/hip_runtime_api.h

@@ -22,7 +22,7 @@ THE SOFTWARE.
 /**
  * @file hip_runtime_api.h
  *
- * Defines the API signatures for HIP runtime. 
+ * @brief Defines the API signatures for HIP runtime.
  * This file can be compiled with a standard compiler.
  */
 
@@ -60,7 +60,7 @@ typedef struct {
     // Misc
     unsigned hasSurfaceFuncs          : 1;   ///< Surface functions
     unsigned has3dGrid                : 1;   ///< Grid and group dims are 3D (rather than 2D)
-    unsigned hasDynamicParallelism    : 1;   ///< Dynamic parallellism
+    unsigned hasDynamicParallelism    : 1;   ///< Dynamic parallelism
 } hipDeviceArch_t;
 
 
@@ -115,10 +115,10 @@ typedef enum hipError_t {
   ,hipErrorMemoryFree              ///< Memory free error.
   ,hipErrorUnknownSymbol           ///< Unknown symbol
   ,hipErrorOutOfResources          ///< Out of resources error
-  ,hipErrorInvalidValue            ///< One or more of the paramters passed to the API call is NULL or not in an acceptable range.
+  ,hipErrorInvalidValue            ///< One or more of the parameters passed to the API call is NULL or not in an acceptable range.
   ,hipErrorInvalidResourceHandle   ///< Resource handle (hipEvent_t or hipStream_t) invalid.
   ,hipErrorInvalidDevice           ///< DeviceID must be in range 0...#compute-devices.
-  ,hipErrorNoDevice                ///< Call to cudaGetDeviceCount returned 0 devices
+  ,hipErrorNoDevice                ///< Call to hipGetDeviceCount returned 0 devices
   ,hipErrorNotReady                ///< indicates that asynchronous operations enqueued earlier are not ready.  This is not actually an error, but is used to distinguish from hipSuccess (which indicates completion).  APIs that return this error include hipEventQuery and hipStreamQuery.
 
   ,hipErrorUnknown                 ///< Unknown error