Context Management [Deprecated]#
Functions | |
hipError_t | hipCtxCreate (hipCtx_t *ctx, unsigned int flags, hipDevice_t device) |
Create a context and set it as current/default context. | |
hipError_t | hipCtxDestroy (hipCtx_t ctx) |
Destroy a HIP context. | |
hipError_t | hipCtxPopCurrent (hipCtx_t *ctx) |
Pop the current/default context and return the popped context. | |
hipError_t | hipCtxPushCurrent (hipCtx_t ctx) |
Push the context to be set as current/ default context. | |
hipError_t | hipCtxSetCurrent (hipCtx_t ctx) |
Set the passed context as current/default. | |
hipError_t | hipCtxGetCurrent (hipCtx_t *ctx) |
Get the handle of the current/ default context. | |
hipError_t | hipCtxGetDevice (hipDevice_t *device) |
Get the handle of the device associated with current/default context. | |
hipError_t | hipCtxGetApiVersion (hipCtx_t ctx, int *apiVersion) |
Returns the approximate HIP api version. | |
hipError_t | hipCtxGetCacheConfig (hipFuncCache_t *cacheConfig) |
Get Cache configuration for a specific function. | |
hipError_t | hipCtxSetCacheConfig (hipFuncCache_t cacheConfig) |
Set L1/Shared cache partition. | |
hipError_t | hipCtxSetSharedMemConfig (hipSharedMemConfig config) |
Set Shared memory bank configuration. | |
hipError_t | hipCtxGetSharedMemConfig (hipSharedMemConfig *pConfig) |
Get Shared memory bank configuration. | |
hipError_t | hipCtxSynchronize (void) |
Blocks until the default context has completed all preceding requested tasks. | |
hipError_t | hipCtxGetFlags (unsigned int *flags) |
Return flags used for creating default context. | |
hipError_t | hipCtxEnablePeerAccess (hipCtx_t peerCtx, unsigned int flags) |
Enables direct access to memory allocations in a peer context. | |
hipError_t | hipCtxDisablePeerAccess (hipCtx_t peerCtx) |
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. | |
hipError_t | hipDevicePrimaryCtxGetState (hipDevice_t dev, unsigned int *flags, int *active) |
Get the state of the primary context. | |
hipError_t | hipDevicePrimaryCtxRelease (hipDevice_t dev) |
Release the primary context on the GPU. | |
hipError_t | hipDevicePrimaryCtxRetain (hipCtx_t *pctx, hipDevice_t dev) |
Retain the primary context on the GPU. | |
hipError_t | hipDevicePrimaryCtxReset (hipDevice_t dev) |
Resets the primary context on the GPU. | |
hipError_t | hipDevicePrimaryCtxSetFlags (hipDevice_t dev, unsigned int flags) |
Set flags for the primary context. | |
Detailed Description
This section describes the context management functions of HIP runtime API.
- Warning
On the AMD platform, context management APIs are deprecated as there are better alternate interfaces, such as using hipSetDevice and stream APIs to achieve the required functionality.
On the NVIDIA platform, CUDA supports the driver API that defines "Context" and "Devices" as separate entities. Each context contains a single device, which can theoretically have multiple contexts. HIP initially added limited support for these APIs to facilitate easy porting from existing driver codes.
These APIs are only for equivalent driver APIs on the NVIDIA platform.
Function Documentation
◆ hipCtxCreate()
hipError_t hipCtxCreate | ( | hipCtx_t * | ctx, |
unsigned int | flags, | ||
hipDevice_t | device | ||
) |
Create a context and set it as current/default context.
- Parameters
-
[out] ctx Context to create [in] flags Context creation flags [in] device device handle
- Returns
- hipSuccess
- See also
- hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxDestroy()
hipError_t hipCtxDestroy | ( | hipCtx_t | ctx | ) |
Destroy a HIP context.
- Parameters
-
[in] ctx Context to destroy
- Returns
- hipSuccess, hipErrorInvalidValue
- See also
- hipCtxCreate, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent,hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize , hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxDisablePeerAccess()
hipError_t hipCtxDisablePeerAccess | ( | hipCtx_t | peerCtx | ) |
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.
- Parameters
-
[in] peerCtx Peer context to be disabled
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- PeerToPeer support is experimental.
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxEnablePeerAccess()
hipError_t hipCtxEnablePeerAccess | ( | hipCtx_t | peerCtx, |
unsigned int | flags | ||
) |
Enables direct access to memory allocations in a peer context.
Memory which already allocated on peer device will be mapped into the address space of the current device. In addition, all future memory allocations on peerDeviceId will be mapped into the address space of the current device when the memory is allocated. The peer memory remains accessible from the current device until a call to hipDeviceDisablePeerAccess or hipDeviceReset.
- Parameters
-
[in] peerCtx Peer context [in] flags flags, need to set as 0
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- PeerToPeer support is experimental.
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxGetApiVersion()
hipError_t hipCtxGetApiVersion | ( | hipCtx_t | ctx, |
int * | apiVersion | ||
) |
Returns the approximate HIP api version.
- Parameters
-
[in] ctx Context to check [out] apiVersion API version to get
- Returns
- hipSuccess
- 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.
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetDevice, hipCtxGetFlags, hipCtxPopCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxGetCacheConfig()
hipError_t hipCtxGetCacheConfig | ( | hipFuncCache_t * | cacheConfig | ) |
Get Cache configuration for a specific function.
- Parameters
-
[out] cacheConfig Cache configuration
- Returns
- hipSuccess
- Warning
- AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxGetCurrent()
hipError_t hipCtxGetCurrent | ( | hipCtx_t * | ctx | ) |
Get the handle of the current/ default context.
- Parameters
-
[out] ctx The context to get as current
- Returns
- hipSuccess, hipErrorInvalidContext
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetDevice, hipCtxGetFlags, hipCtxPopCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxGetDevice()
hipError_t hipCtxGetDevice | ( | hipDevice_t * | device | ) |
Get the handle of the device associated with current/default context.
- Parameters
-
[out] device The device from the current context
- Returns
- hipSuccess, hipErrorInvalidContext
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxGetFlags()
hipError_t hipCtxGetFlags | ( | unsigned int * | flags | ) |
Return flags used for creating default context.
- Parameters
-
[out] flags Pointer of flags
- Returns
- hipSuccess
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxGetSharedMemConfig()
hipError_t hipCtxGetSharedMemConfig | ( | hipSharedMemConfig * | pConfig | ) |
Get Shared memory bank configuration.
- Parameters
-
[out] pConfig Pointer of shared memory configuration
- Returns
- hipSuccess
- Warning
- AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxPopCurrent()
hipError_t hipCtxPopCurrent | ( | hipCtx_t * | ctx | ) |
Pop the current/default context and return the popped context.
- Parameters
-
[out] ctx The current context to pop
- Returns
- hipSuccess, hipErrorInvalidContext
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxSetCurrent, hipCtxGetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxPushCurrent()
hipError_t hipCtxPushCurrent | ( | hipCtx_t | ctx | ) |
Push the context to be set as current/ default context.
- Parameters
-
[in] ctx The current context to push
- Returns
- hipSuccess, hipErrorInvalidContext
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize , hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxSetCacheConfig()
hipError_t hipCtxSetCacheConfig | ( | hipFuncCache_t | cacheConfig | ) |
Set L1/Shared cache partition.
- Parameters
-
[in] cacheConfig Cache configuration to set
- Returns
- hipSuccess
- Warning
- AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxSetCurrent()
hipError_t hipCtxSetCurrent | ( | hipCtx_t | ctx | ) |
Set the passed context as current/default.
- Parameters
-
[in] ctx The context to set as current
- Returns
- hipSuccess, hipErrorInvalidContext
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize , hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxSetSharedMemConfig()
hipError_t hipCtxSetSharedMemConfig | ( | hipSharedMemConfig | config | ) |
Set Shared memory bank configuration.
- Parameters
-
[in] config Shared memory configuration to set
- Returns
- hipSuccess
- Warning
- AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipCtxSynchronize()
hipError_t hipCtxSynchronize | ( | void | ) |
Blocks until the default context has completed all preceding requested tasks.
- Returns
- hipSuccess
- Warning
- This function waits for all streams on the default context to complete execution, and then returns.
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent cuCtx driver API on the NVIDIA platform.
◆ hipDevicePrimaryCtxGetState()
hipError_t hipDevicePrimaryCtxGetState | ( | hipDevice_t | dev, |
unsigned int * | flags, | ||
int * | active | ||
) |
Get the state of the primary context.
- Parameters
-
[in] dev Device to get primary context flags for [out] flags Pointer to store flags [out] active Pointer to store context state; 0 = inactive, 1 = active
- Returns
- hipSuccess
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent driver API on the NVIDIA platform.
◆ hipDevicePrimaryCtxRelease()
hipError_t hipDevicePrimaryCtxRelease | ( | hipDevice_t | dev | ) |
Release the primary context on the GPU.
- Parameters
-
[in] dev Device which primary context is released
- Returns
- hipSuccess
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This function return hipSuccess though doesn't release the primaryCtx by design on HIP/HCC path.
- This API is deprecated on the AMD platform, only for equivalent driver API on the NVIDIA platform.
◆ hipDevicePrimaryCtxReset()
hipError_t hipDevicePrimaryCtxReset | ( | hipDevice_t | dev | ) |
Resets the primary context on the GPU.
- Parameters
-
[in] dev Device which primary context is reset
- Returns
- hipSuccess
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent driver API on the NVIDIA platform.
◆ hipDevicePrimaryCtxRetain()
hipError_t hipDevicePrimaryCtxRetain | ( | hipCtx_t * | pctx, |
hipDevice_t | dev | ||
) |
Retain the primary context on the GPU.
- Parameters
-
[out] pctx Returned context handle of the new context [in] dev Device which primary context is released
- Returns
- hipSuccess
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent driver API on the NVIDIA platform.
◆ hipDevicePrimaryCtxSetFlags()
hipError_t hipDevicePrimaryCtxSetFlags | ( | hipDevice_t | dev, |
unsigned int | flags | ||
) |
Set flags for the primary context.
- Parameters
-
[in] dev Device for which the primary context flags are set [in] flags New flags for the device
- See also
- hipCtxCreate, hipCtxDestroy, hipCtxGetFlags, hipCtxPopCurrent, hipCtxGetCurrent, hipCtxSetCurrent, hipCtxPushCurrent, hipCtxSetCacheConfig, hipCtxSynchronize, hipCtxGetDevice
- Warning
- This API is deprecated on the AMD platform, only for equivalent driver API on the NVIDIA platform.