# ROCm Documentation has moved to docs.amd.com

Device management¶

Device management types and functions.

hipDeviceSynchronize¶

hipError_t hipDeviceSynchronize(void)¶

Waits on all active streams on current device.

When this command is invoked, the host thread gets blocked until all the commands associated with streams associated with the device. HIP does not support multiple blocking modes (yet!).

Return: #hipSuccess
See: hipSetDevice, hipDeviceReset

hipDeviceReset¶

hipError_t hipDeviceReset(void)¶

The state of current device is discarded and updated to a fresh state.

Calling this function deletes all streams created, memory allocated, kernels running, events created. Make sure that no other thread is using the device or streams, memory, kernels, events associated with the current device.

Return: #hipSuccess
See: hipDeviceSynchronize

hipSetDevice¶

hipError_t hipSetDevice(int deviceId)¶

Set default device to be used for subsequent hip API calls from this thread.

Sets

device as the default device for the calling host thread. Valid device id’s are 0… (hipGetDeviceCount()-1).

Parameters

[in] deviceId: Valid device in range 0…hipGetDeviceCount().

Many HIP APIs implicitly use the “default device” :

Any device memory subsequently allocated from this host thread (using hipMalloc) will be allocated on device.
Any streams or events created from this host thread will be associated with device.
Any kernels launched from this host thread (using hipLaunchKernelGGL) will be executed on device (unless a specific stream is specified, in which case the device associated with that stream will be used).

This function may be called from any host thread. Multiple host threads may use the same device. This function does no synchronization with the previous or new device, and has very little runtime overhead. Applications can use hipSetDevice to quickly switch the default device before making a HIP runtime call which uses the default device.

The default device is stored in thread-local-storage for each thread. Thread-pool implementations may inherit the default device of the previous thread. A good practice is to always call hipSetDevice at the start of HIP coding sequency to establish a known standard device.

Return: #hipSuccess, #hipErrorInvalidDevice, #hipErrorDeviceAlreadyInUse
See: hipGetDevice, hipGetDeviceCount

hipGetDevice¶

hipError_t hipGetDevice(int *deviceId)¶

Return the default device id for the calling host thread.

HIP maintains an default device for each thread using thread-local-storage. This device is used implicitly for HIP runtime APIs called by this thread. hipGetDevice returns in *

device the default device for the calling host thread.

Parameters

[out] device: *device is written with the default device

Return: #hipSuccess
See: hipSetDevice, hipGetDevicesizeBytes

hipGetDeviceCount¶

hipError_t hipGetDeviceCount(int *count)¶

Return number of compute-capable devices.

Returns in

*count the number of devices that have ability to run compute commands. If there are no such devices, then hipGetDeviceCount will return #hipErrorNoDevice. If 1 or more devices can be found, then hipGetDeviceCount returns #hipSuccess.

Return

#hipSuccess, #hipErrorNoDevice

Parameters

[output]: count Returns number of compute-capable devices.

hipDeviceGetAttribute¶

hipError_t hipDeviceGetAttribute(int *pi, hipDeviceAttribute_t attr, int deviceId)¶

Query for a specific device attribute.

Return

#hipSuccess, #hipErrorInvalidDevice, #hipErrorInvalidValue

Parameters

[out] pi: pointer to value to return
[in] attr: attribute to query
[in] deviceId: which device to query for information

hipGetDeviceProperties¶

hipError_t hipGetDeviceProperties(hipDeviceProp_t *prop, int deviceId)¶

Returns device properties.

Bug:

HCC always returns 0 for maxThreadsPerMultiProcessor

HCC always returns 0 for regsPerBlock

HCC always returns 0 for l2CacheSize

Return

#hipSuccess, #hipErrorInvalidDevice

Parameters

[out] prop: written with device properties
[in] deviceId: which device to query for information

Populates hipGetDeviceProperties with information for the specified device.

hipDeviceSetCacheConfig¶

hipError_t hipDeviceSetCacheConfig(hipFuncCache_t cacheConfig)¶

Set L1/Shared cache partition.

Return

#hipSuccess, #hipErrorInitializationError Note: AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.

Parameters

[in] cacheConfig:

hipDeviceGetCacheConfig¶

hipError_t hipDeviceGetCacheConfig(hipFuncCache_t *cacheConfig)¶

Set Cache configuration for a specific function.

Return

#hipSuccess, #hipErrorInitializationError Note: AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.

Parameters

[in] cacheConfig:

hipDeviceGetLimit¶

hipError_t hipDeviceGetLimit(size_t *pValue, enum hipLimit_t limit)¶

Get Resource limits of current device.

Return

#hipSuccess, #hipErrorUnsupportedLimit, #hipErrorInvalidValue Note: Currently, only hipLimitMallocHeapSize is available

Parameters

[out] pValue:
[in] limit:

hipFuncSetCacheConfig¶

hipError_t hipFuncSetCacheConfig(const void *func, hipFuncCache_t config)¶

Set Cache configuration for a specific function.

Return

#hipSuccess, #hipErrorInitializationError Note: AMD devices and some Nvidia GPUS do not support reconfigurable cache. This hint is ignored on those architectures.

Parameters

[in] config;:

hipDeviceGetSharedMemConfig¶

hipError_t hipDeviceGetSharedMemConfig(hipSharedMemConfig *pConfig)¶

Returns bank width of shared memory for current device.

Note: AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.

Return

#hipSuccess, #hipErrorInvalidValue, #hipErrorInitializationError

Parameters

[out] pConfig:

hipDeviceSetSharedMemConfig¶

hipError_t hipDeviceSetSharedMemConfig(hipSharedMemConfig config)¶

The bank width of shared memory on current device is set.

Note: AMD devices and some Nvidia GPUS do not support shared cache banking, and the hint is ignored on those architectures.

Return

#hipSuccess, #hipErrorInvalidValue, #hipErrorInitializationError

Parameters

[in] config:

hipSetDeviceFlags¶

hipError_t hipSetDeviceFlags(unsigned flags)¶

The current device behavior is changed according the flags passed.

hipDeviceMapHost : Allow mapping host memory. On ROCM, this is always allowed and the flag is ignored. hipDeviceLmemResizeToMax :

Warning

ROCm silently ignores this flag.

Return

#hipSuccess, #hipErrorInvalidDevice, #hipErrorSetOnActiveProcess

Parameters

[in] flags: The schedule flags impact how HIP waits for the completion of a command running on a device. hipDeviceScheduleSpin : HIP runtime will actively spin in the thread which submitted the work until the command completes. This offers the lowest latency, but will consume a CPU core and may increase power. hipDeviceScheduleYield : The HIP runtime will yield the CPU to system so that other tasks can use it. This may increase latency to detect the completion but will consume less power and is friendlier to other tasks in the system. hipDeviceScheduleBlockingSync : On ROCm platform, this is a synonym for hipDeviceScheduleYield. hipDeviceScheduleAuto : Use a hueristic to select between Spin and Yield modes. If the number of HIP contexts is greater than the number of logical processors in the system, use Spin scheduling. Else use Yield scheduling.

hipChooseDevice¶

hipError_t hipChooseDevice(int *device, const hipDeviceProp_t *prop)¶

Device which matches hipDeviceProp_t is returned.

Return

#hipSuccess, #hipErrorInvalidValue

Parameters

[out] device: ID
[in] device: properties pointer