From 00b92e6e35a2cb1b55ca1db80ea4e40e52bfaf37 Mon Sep 17 00:00:00 2001 From: Rahul Garg Date: Thu, 1 Sep 2016 12:19:41 +0530 Subject: [PATCH] Added doxygen documentation for hipCtxXXX APIs Change-Id: Id9cf3491e9a8c78cb7bfeb9976c36d6fe565628f [ROCm/hip commit: 94f035d80db09122751cc5ffd19bf0df5796f1f8] --- .../hip/include/hcc_detail/hip_runtime_api.h | 111 +++++++++++++++++- projects/hip/src/hip_context.cpp | 72 ++++++++++-- 2 files changed, 173 insertions(+), 10 deletions(-) diff --git a/projects/hip/include/hcc_detail/hip_runtime_api.h b/projects/hip/include/hcc_detail/hip_runtime_api.h index 0114a0772b..fbcca3d12f 100644 --- a/projects/hip/include/hcc_detail/hip_runtime_api.h +++ b/projects/hip/include/hcc_detail/hip_runtime_api.h @@ -1062,34 +1062,137 @@ hipError_t hipMemcpyPeerAsync(void* dst, int dstDevice, const void* src, int src hipError_t hipInit(unsigned int flags) ; +/** + *------------------------------------------------------------------------------------------------- + *------------------------------------------------------------------------------------------------- + * @defgroup Context Management + * @{ + */ -// TODO-ctx +/** + * @brief Create a context and set it as current/ default context + * + * @param [out] ctx + * @param [in] flags + * @param [in] associated device handle + * + * @returns #hipSuccess, #hipErrorInvalidContext + */ hipError_t hipCtxCreate(hipCtx_t *ctx, unsigned int flags, hipDevice_t device); hipError_t hipCtxDestroy(hipCtx_t ctx); +/** + * @brief Pop the current/default context and return the popped context. + * + * @param [out] ctx + * + * @returns #hipSuccess + */ + hipError_t hipCtxPopCurrent(hipCtx_t* ctx); +/** + * @brief Push the context to be set as current/ default context + * + * @param [in] ctx + * + * @returns #hipSuccess, #hipErrorInvalidContext + */ + hipError_t hipCtxPushCurrent(hipCtx_t ctx); +/** + * @brief Set the passed context as current/default + * + * @param [in] ctx + * + * @returns #hipSuccess + */ + hipError_t hipCtxSetCurrent(hipCtx_t ctx); +/** + * @brief Get the handle of the current/ default context + * + * @param [out] ctx + * + * @returns #hipSuccess + */ + hipError_t hipCtxGetCurrent(hipCtx_t* ctx); +/** + * @brief Get the handle of the device associated with current/default context + * + * @param [out] device + * + * @returns #hipSuccess, #hipErrorInvalidContext + */ + hipError_t hipCtxGetDevice(hipDevice_t *device); +/** + * @brief Returns the approximate HIP api version. + * + * @warning The HIP feature set does not correspond to an exact CUDA SDK api revision. + * This function always set *apiVersion 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 api revision number here and should + * use arch feature flags to test device capabilities or conditional compilation. + * + */ hipError_t hipCtxGetApiVersion (hipCtx_t ctx,int *apiVersion); +/** + * @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. + * + */ hipError_t hipCtxGetCacheConfig ( hipFuncCache *cacheConfig ); +/** + * @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. + * + */ hipError_t hipCtxSetCacheConfig ( hipFuncCache cacheConfig ); +/** + * @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. + * + */ hipError_t hipCtxSetSharedMemConfig ( hipSharedMemConfig 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. + * + */ hipError_t hipCtxGetSharedMemConfig ( hipSharedMemConfig * pConfig ); +/** + * @brief Blocks until the default context has completed all preceding requested tasks. + * + * This function waits for all streams on the default context to complete execution, and then returns. + * + * @returns #hipSuccess. +*/ hipError_t hipCtxSynchronize ( void ); +/** + * @brief Get flags used for creating current/default context. + * + * @param [out] flags + * + * @returns #hipSuccess. +*/ + hipError_t hipCtxGetFlags ( unsigned int* flags ); /** @@ -1110,7 +1213,7 @@ hipError_t hipCtxGetFlags ( unsigned int* flags ); hipError_t hipCtxEnablePeerAccess (hipCtx_t peerCtx, unsigned int flags); /** - * @brief Disable direct access from current device's virtual address space to memory allocations physically located on a peer device through contex.Disables direct access to memory allocations in a peer context and unregisters any registered allocations. + * @brief Disable direct access from current context's virtual address space to memory allocations physically located on a peer context.Disables direct access to memory allocations in a peer context and unregisters any registered allocations. * * Returns hipErrorPeerAccessNotEnabled if direct access to memory on peerDevice has not yet been enabled from the current device. * @@ -1120,6 +1223,10 @@ hipError_t hipCtxEnablePeerAccess (hipCtx_t peerCtx, unsigned int flags); * @warning PeerToPeer support is experimental. */ hipError_t hipCtxDisablePeerAccess (hipCtx_t peerCtx); +// doxygen end Context Management +/** + * @} + */ // TODO-ctx diff --git a/projects/hip/src/hip_context.cpp b/projects/hip/src/hip_context.cpp index f1d9ff8387..e19c45d2c3 100644 --- a/projects/hip/src/hip_context.cpp +++ b/projects/hip/src/hip_context.cpp @@ -41,6 +41,10 @@ hipError_t ihipCtxStackUpdate() return ihipLogStatus(e); } +/** + * @return #hipSuccess, #hipErrorInvalidValue + */ +//--- hipError_t hipInit(unsigned int flags) { HIP_INIT_API(flags); @@ -55,7 +59,10 @@ hipError_t hipInit(unsigned int flags) return ihipLogStatus(e); } - +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxCreate(hipCtx_t *ctx, unsigned int flags, hipDevice_t device) { HIP_INIT_API(ctx, flags, device); // FIXME - review if we want to init @@ -68,7 +75,10 @@ hipError_t hipCtxCreate(hipCtx_t *ctx, unsigned int flags, hipDevice_t device) return ihipLogStatus(e); } - +/** + * @return #hipSuccess, #hipErrorInvalidDevice + */ +//--- hipError_t hipDeviceGet(hipDevice_t *device, int deviceId) { HIP_INIT_API(device, deviceId); // FIXME - review if we want to init @@ -99,6 +109,10 @@ hipError_t hipDriverGetVersion(int *driverVersion) return ihipLogStatus(hipSuccess); } +/** + * @return #hipSuccess, #hipErrorInvalidValue + */ +//--- hipError_t hipCtxDestroy(hipCtx_t ctx) { HIP_INIT_API(ctx); @@ -121,6 +135,10 @@ hipError_t hipCtxDestroy(hipCtx_t ctx) return ihipLogStatus(e); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxPopCurrent(hipCtx_t* ctx) { HIP_INIT_API(ctx); @@ -141,6 +159,10 @@ hipError_t hipCtxPopCurrent(hipCtx_t* ctx) return ihipLogStatus(e); } +/** + * @return #hipSuccess, #hipErrorInvalidContext + */ +//--- hipError_t hipCtxPushCurrent(hipCtx_t ctx) { HIP_INIT_API(ctx); @@ -155,16 +177,14 @@ hipError_t hipCtxPushCurrent(hipCtx_t ctx) return ihipLogStatus(e); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxGetCurrent(hipCtx_t* ctx) { HIP_INIT_API(ctx); hipError_t e = hipSuccess; -#if 0 - *ctx = ihipGetTlsDefaultCtx(); - if(*ctx == nullptr) { - *ctx = NULL; //TODO - is it required? Can return nullptr? - } -#endif if(!tls_ctxStack.empty()) { *ctx= tls_ctxStack.top(); } @@ -174,6 +194,10 @@ hipError_t hipCtxGetCurrent(hipCtx_t* ctx) return ihipLogStatus(e); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxSetCurrent(hipCtx_t ctx) { HIP_INIT_API(ctx); @@ -188,6 +212,10 @@ hipError_t hipCtxSetCurrent(hipCtx_t ctx) return ihipLogStatus(e); } +/** + * @return #hipSuccess, #hipErrorInvalidContext + */ +//--- hipError_t hipCtxGetDevice(hipDevice_t *device) { HIP_INIT_API(device); @@ -204,6 +232,10 @@ hipError_t hipCtxGetDevice(hipDevice_t *device) return ihipLogStatus(e); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxGetApiVersion (hipCtx_t ctx,int *apiVersion) { HIP_INIT_API(apiVersion); @@ -215,6 +247,10 @@ hipError_t hipCtxGetApiVersion (hipCtx_t ctx,int *apiVersion) return ihipLogStatus(hipSuccess); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxGetCacheConfig ( hipFuncCache *cacheConfig ) { HIP_INIT_API(cacheConfig); @@ -224,6 +260,10 @@ hipError_t hipCtxGetCacheConfig ( hipFuncCache *cacheConfig ) return ihipLogStatus(hipSuccess); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxSetCacheConfig ( hipFuncCache cacheConfig ) { HIP_INIT_API(cacheConfig); @@ -233,6 +273,10 @@ hipError_t hipCtxSetCacheConfig ( hipFuncCache cacheConfig ) return ihipLogStatus(hipSuccess); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxSetSharedMemConfig ( hipSharedMemConfig config ) { HIP_INIT_API(config); @@ -242,6 +286,10 @@ hipError_t hipCtxSetSharedMemConfig ( hipSharedMemConfig config ) return ihipLogStatus(hipSuccess); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxGetSharedMemConfig ( hipSharedMemConfig * pConfig ) { HIP_INIT_API(pConfig); @@ -251,12 +299,20 @@ hipError_t hipCtxGetSharedMemConfig ( hipSharedMemConfig * pConfig ) return ihipLogStatus(hipSuccess); } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxSynchronize ( void ) { HIP_INIT_API(1); return ihipSynchronize(); //TODP Shall check validity of ctx? } +/** + * @return #hipSuccess + */ +//--- hipError_t hipCtxGetFlags ( unsigned int* flags ) { HIP_INIT_API(flags);