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

Occupancy

Occupancy#

HIP Runtime API Reference: Occupancy
Occupancy
Collaboration diagram for Occupancy:

Functions

hipError_t hipModuleOccupancyMaxPotentialBlockSize (int *gridSize, int *blockSize, hipFunction_t f, size_t dynSharedMemPerBlk, int blockSizeLimit)
 determine the grid and block sizes to achieves maximum occupancy for a kernel More...
 
hipError_t hipModuleOccupancyMaxPotentialBlockSizeWithFlags (int *gridSize, int *blockSize, hipFunction_t f, size_t dynSharedMemPerBlk, int blockSizeLimit, unsigned int flags)
 determine the grid and block sizes to achieves maximum occupancy for a kernel More...
 
hipError_t hipModuleOccupancyMaxActiveBlocksPerMultiprocessor (int *numBlocks, hipFunction_t f, int blockSize, size_t dynSharedMemPerBlk)
 Returns occupancy for a device function. More...
 
hipError_t hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags (int *numBlocks, hipFunction_t f, int blockSize, size_t dynSharedMemPerBlk, unsigned int flags)
 Returns occupancy for a device function. More...
 
hipError_t hipOccupancyMaxActiveBlocksPerMultiprocessor (int *numBlocks, const void *f, int blockSize, size_t dynSharedMemPerBlk)
 Returns occupancy for a device function. More...
 
hipError_t hipOccupancyMaxActiveBlocksPerMultiprocessorWithFlags (int *numBlocks, const void *f, int blockSize, size_t dynSharedMemPerBlk, unsigned int flags)
 Returns occupancy for a device function. More...
 
hipError_t hipOccupancyMaxPotentialBlockSize (int *gridSize, int *blockSize, const void *f, size_t dynSharedMemPerBlk, int blockSizeLimit)
 determine the grid and block sizes to achieves maximum occupancy for a kernel More...
 

Detailed Description



This section describes the occupancy functions of HIP runtime API.

Function Documentation

◆ hipModuleOccupancyMaxActiveBlocksPerMultiprocessor()

hipError_t hipModuleOccupancyMaxActiveBlocksPerMultiprocessor ( int *  numBlocks,
hipFunction_t  f,
int  blockSize,
size_t  dynSharedMemPerBlk 
)

Returns occupancy for a device function.

Parameters
[out]numBlocksReturned occupancy
[in]fKernel function (hipFunction) for which occupancy is calulated
[in]blockSizeBlock size the kernel is intended to be launched with
[in]dynSharedMemPerBlkDynamic shared memory usage (in bytes) intended for each block
Returns
hipSuccess, hipErrorInvalidValue

◆ hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags()

hipError_t hipModuleOccupancyMaxActiveBlocksPerMultiprocessorWithFlags ( int *  numBlocks,
hipFunction_t  f,
int  blockSize,
size_t  dynSharedMemPerBlk,
unsigned int  flags 
)

Returns occupancy for a device function.

Parameters
[out]numBlocksReturned occupancy
[in]fKernel function(hipFunction_t) for which occupancy is calulated
[in]blockSizeBlock size the kernel is intended to be launched with
[in]dynSharedMemPerBlkDynamic shared memory usage (in bytes) intended for each block
[in]flagsExtra flags for occupancy calculation (only default supported)
Returns
hipSuccess, hipErrorInvalidValue

◆ hipModuleOccupancyMaxPotentialBlockSize()

hipError_t hipModuleOccupancyMaxPotentialBlockSize ( int *  gridSize,
int *  blockSize,
hipFunction_t  f,
size_t  dynSharedMemPerBlk,
int  blockSizeLimit 
)

determine the grid and block sizes to achieves maximum occupancy for a kernel

Parameters
[out]gridSizeminimum grid size for maximum potential occupancy
[out]blockSizeblock size for maximum potential occupancy
[in]fkernel function for which occupancy is calulated
[in]dynSharedMemPerBlkdynamic shared memory usage (in bytes) intended for each block
[in]blockSizeLimitthe maximum block size for the kernel, use 0 for no limit

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Returns
hipSuccess, hipErrorInvalidValue

◆ hipModuleOccupancyMaxPotentialBlockSizeWithFlags()

hipError_t hipModuleOccupancyMaxPotentialBlockSizeWithFlags ( int *  gridSize,
int *  blockSize,
hipFunction_t  f,
size_t  dynSharedMemPerBlk,
int  blockSizeLimit,
unsigned int  flags 
)

determine the grid and block sizes to achieves maximum occupancy for a kernel

Parameters
[out]gridSizeminimum grid size for maximum potential occupancy
[out]blockSizeblock size for maximum potential occupancy
[in]fkernel function for which occupancy is calulated
[in]dynSharedMemPerBlkdynamic shared memory usage (in bytes) intended for each block
[in]blockSizeLimitthe maximum block size for the kernel, use 0 for no limit
[in]flagsExtra flags for occupancy calculation (only default supported)

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Returns
hipSuccess, hipErrorInvalidValue

◆ hipOccupancyMaxActiveBlocksPerMultiprocessor()

hipError_t hipOccupancyMaxActiveBlocksPerMultiprocessor ( int *  numBlocks,
const void *  f,
int  blockSize,
size_t  dynSharedMemPerBlk 
)

Returns occupancy for a device function.

Parameters
[out]numBlocksReturned occupancy
[in]fKernel function for which occupancy is calulated
[in]blockSizeBlock size the kernel is intended to be launched with
[in]dynSharedMemPerBlkDynamic shared memory usage (in bytes) intended for each block
Returns
hipSuccess, hipErrorInvalidDeviceFunction, hipErrorInvalidValue

◆ hipOccupancyMaxActiveBlocksPerMultiprocessorWithFlags()

hipError_t hipOccupancyMaxActiveBlocksPerMultiprocessorWithFlags ( int *  numBlocks,
const void *  f,
int  blockSize,
size_t  dynSharedMemPerBlk,
unsigned int  flags 
)

Returns occupancy for a device function.

Parameters
[out]numBlocksReturned occupancy
[in]fKernel function for which occupancy is calulated
[in]blockSizeBlock size the kernel is intended to be launched with
[in]dynSharedMemPerBlkDynamic shared memory usage (in bytes) intended for each block
[in]flagsExtra flags for occupancy calculation (currently ignored)
Returns
hipSuccess, hipErrorInvalidDeviceFunction, hipErrorInvalidValue

◆ hipOccupancyMaxPotentialBlockSize()

hipError_t hipOccupancyMaxPotentialBlockSize ( int *  gridSize,
int *  blockSize,
const void *  f,
size_t  dynSharedMemPerBlk,
int  blockSizeLimit 
)

determine the grid and block sizes to achieves maximum occupancy for a kernel

Parameters
[out]gridSizeminimum grid size for maximum potential occupancy
[out]blockSizeblock size for maximum potential occupancy
[in]fkernel function for which occupancy is calulated
[in]dynSharedMemPerBlkdynamic shared memory usage (in bytes) intended for each block
[in]blockSizeLimitthe maximum block size for the kernel, use 0 for no limit

Please note, HIP does not support kernel launch with total work items defined in dimension with size gridDim x blockDim >= 2^32.

Returns
hipSuccess, hipErrorInvalidValue