This page contains proposed changes for a future release of ROCm. Read the latest Linux release of ROCm documentation for your production environments.

Context Management [Deprecated]

Context Management [Deprecated]#

HIP Runtime API Reference: Context Management [Deprecated]
Context Management [Deprecated]
Collaboration diagram for 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. More...
 
hipError_t hipCtxDestroy (hipCtx_t ctx)
 Destroy a HIP context. More...
 
hipError_t hipCtxPopCurrent (hipCtx_t *ctx)
 Pop the current/default context and return the popped context. More...
 
hipError_t hipCtxPushCurrent (hipCtx_t ctx)
 Push the context to be set as current/ default context. More...
 
hipError_t hipCtxSetCurrent (hipCtx_t ctx)
 Set the passed context as current/default. More...
 
hipError_t hipCtxGetCurrent (hipCtx_t *ctx)
 Get the handle of the current/ default context. More...
 
hipError_t hipCtxGetDevice (hipDevice_t *device)
 Get the handle of the device associated with current/default context. More...
 
hipError_t hipCtxGetApiVersion (hipCtx_t ctx, int *apiVersion)
 Returns the approximate HIP api version. More...
 
hipError_t hipCtxGetCacheConfig (hipFuncCache_t *cacheConfig)
 Get Cache configuration for a specific function. More...
 
hipError_t hipCtxSetCacheConfig (hipFuncCache_t cacheConfig)
 Set L1/Shared cache partition. More...
 
hipError_t hipCtxSetSharedMemConfig (hipSharedMemConfig config)
 Set Shared memory bank configuration. More...
 
hipError_t hipCtxGetSharedMemConfig (hipSharedMemConfig *pConfig)
 Get Shared memory bank configuration. More...
 
hipError_t hipCtxSynchronize (void)
 Blocks until the default context has completed all preceding requested tasks. More...
 
hipError_t hipCtxGetFlags (unsigned int *flags)
 Return flags used for creating default context. More...
 
hipError_t hipCtxEnablePeerAccess (hipCtx_t peerCtx, unsigned int flags)
 Enables direct access to memory allocations in a peer context. More...
 
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. More...
 
hipError_t hipDevicePrimaryCtxGetState (hipDevice_t dev, unsigned int *flags, int *active)
 Get the state of the primary context. More...
 
hipError_t hipDevicePrimaryCtxRelease (hipDevice_t dev)
 Release the primary context on the GPU. More...
 
hipError_t hipDevicePrimaryCtxRetain (hipCtx_t *pctx, hipDevice_t dev)
 Retain the primary context on the GPU. More...
 
hipError_t hipDevicePrimaryCtxReset (hipDevice_t dev)
 Resets the primary context on the GPU. More...
 
hipError_t hipDevicePrimaryCtxSetFlags (hipDevice_t dev, unsigned int flags)
 Set flags for the primary context. More...
 

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]ctxContext to create
[in]flagsContext creation flags
[in]devicedevice 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]ctxContext 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]peerCtxPeer context to be disabled
Returns
hipSuccess, hipErrorPeerAccessNotEnabled
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]peerCtxPeer context
[in]flagsflags, need to set as 0
Returns
hipSuccess, hipErrorInvalidDevice, hipErrorInvalidValue, hipErrorPeerAccessAlreadyEnabled
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]ctxContext to check
[out]apiVersionAPI 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]cacheConfigCache 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]ctxThe 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]deviceThe 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]flagsPointer 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]pConfigPointer 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]ctxThe 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]ctxThe 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]cacheConfigCache 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]ctxThe 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]configShared 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]devDevice to get primary context flags for
[out]flagsPointer to store flags
[out]activePointer 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]devDevice 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]devDevice 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]pctxReturned context handle of the new context
[in]devDevice 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]devDevice for which the primary context flags are set
[in]flagsNew flags for the device
Returns
hipSuccess, hipErrorContextAlreadyInUse
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.