CUDA 驱动程序 API :: CUDA Toolkit 文档

6.25. 占用率

本节介绍低级别 CUDA 驱动程序应用程序编程接口的占用率计算函数。

函数

CUresult cuOccupancyAvailableDynamicSMemPerBlock ( size_t* dynamicSmemSize, CUfunction func, int numBlocks, int blockSize ): 返回在 SM 上启动 numBlocks 个块时每个块可用的动态共享内存。
CUresult cuOccupancyMaxActiveBlocksPerMultiprocessor ( int* numBlocks, CUfunction func, int blockSize, size_t dynamicSMemSize ): 返回函数的占用率。
CUresult cuOccupancyMaxActiveBlocksPerMultiprocessorWithFlags ( int* numBlocks, CUfunction func, int blockSize, size_t dynamicSMemSize, unsigned int flags ): 返回函数的占用率。
CUresult cuOccupancyMaxActiveClusters ( int* numClusters, CUfunction func, const CUlaunchConfig* config ): 给定内核函数 (func) 和启动配置 (config)，返回可以在目标设备上共存的最大集群数量，结果存储在 *numClusters 中。
CUresult cuOccupancyMaxPotentialBlockSize ( int* minGridSize, int* blockSize, CUfunction func, CUoccupancyB2DSize blockSizeToDynamicSMemSize, size_t dynamicSMemSize, int blockSizeLimit ): 建议具有合理占用率的启动配置。
CUresult cuOccupancyMaxPotentialBlockSizeWithFlags ( int* minGridSize, int* blockSize, CUfunction func, CUoccupancyB2DSize blockSizeToDynamicSMemSize, size_t dynamicSMemSize, int blockSizeLimit, unsigned int flags ): 建议具有合理占用率的启动配置。
CUresult cuOccupancyMaxPotentialClusterSize ( int* clusterSize, CUfunction func, const CUlaunchConfig* config ): 给定内核函数 (func) 和启动配置 (config)，返回最大集群大小，结果存储在 *clusterSize 中。

函数

CUresult cuOccupancyAvailableDynamicSMemPerBlock ( size_t* dynamicSmemSize, CUfunction func, int numBlocks, int blockSize )

返回在启动时每个块可用的动态共享内存numBlocksSM 上的块。

参数

dynamicSmemSize: - 返回的最大动态共享内存
func: - 用于计算占用率的内核函数
numBlocks: - 适合 SM 的块数
blockSize: - 块的大小

返回值

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_UNKNOWN

描述

在*dynamicSmemSize中返回允许每个 SMnumBlocks块的最大动态共享内存大小。

请注意，此 API 也可以与无上下文内核 CUkernel 一起使用，方法是使用 cuLibraryGetKernel() 查询句柄，然后将其强制转换为 CUfunction 后传递给 API。此处，用于计算的上下文将是当前上下文。

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

CUresult cuOccupancyMaxActiveBlocksPerMultiprocessor ( int* numBlocks, CUfunction func, int blockSize, size_t dynamicSMemSize )

返回函数的占用率。

参数

numBlocks: - 返回的占用率
func: - 用于计算占用率的内核
blockSize: - 内核计划启动的块大小
dynamicSMemSize: - 计划的每个块动态共享内存使用量，以字节为单位

返回值

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_UNKNOWN

描述

在*numBlocks每个流式多处理器允许的最大活动块数。

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cudaOccupancyMaxActiveBlocksPerMultiprocessor

CUresult cuOccupancyMaxActiveBlocksPerMultiprocessorWithFlags ( int* numBlocks, CUfunction func, int blockSize, size_t dynamicSMemSize, unsigned int flags )

返回函数的占用率。

参数

numBlocks: - 返回的占用率
func: - 用于计算占用率的内核
blockSize: - 内核计划启动的块大小
dynamicSMemSize: - 计划的每个块动态共享内存使用量，以字节为单位
flags: - 占用率计算器的请求行为

返回值

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_UNKNOWN

描述

在*numBlocks每个流式多处理器允许的最大活动块数。

TheFlags参数控制特殊情况的处理方式。有效标志为

CU_OCCUPANCY_DEFAULT，它保持与 cuOccupancyMaxActiveBlocksPerMultiprocessor 相同的默认行为；

CU_OCCUPANCY_DISABLE_CACHING_OVERRIDE，它抑制了全局缓存影响占用率的平台上的默认行为。在此类平台上，如果启用了缓存，但每个块 SM 资源使用率将导致零占用率，则占用率计算器将计算占用率，如同禁用了缓存一样。设置 CU_OCCUPANCY_DISABLE_CACHING_OVERRIDE 使占用率计算器在此类情况下返回 0。有关此功能的更多信息，请参见 Maxwell 调优指南的“统一 L1/纹理缓存”部分。

请注意，此 API 也可以与无启动上下文内核 CUkernel 一起使用，方法是使用 cuLibraryGetKernel() 查询句柄，然后将其强制转换为 CUfunction 后传递给 API。此处，用于计算的上下文将是当前上下文。

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cudaOccupancyMaxActiveBlocksPerMultiprocessorWithFlags

CUresult cuOccupancyMaxActiveClusters ( int* numClusters, CUfunction func, const CUlaunchConfig* config )

给定内核函数 (func) 和启动配置 (config)，返回可以在目标设备上共存的最大集群数量，结果存储在*numClusters.

参数

numClusters: - 返回的可以在目标设备上共存的最大集群数量
func: - 用于计算最大集群数量的内核函数
config: - 给定内核函数的启动配置

返回值

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_CLUSTER_SIZE, CUDA_ERROR_UNKNOWN

描述

如果函数已设置所需的集群大小（参见 cudaFuncGetAttributes / cuFuncGetAttribute），则来自 config 的集群大小必须未指定或与所需大小匹配。如果没有所需大小，则必须在 config 中指定集群大小，否则该函数将返回错误。

请注意，内核函数的各种属性可能会影响占用率计算。运行时环境可能会影响硬件调度集群的方式，因此不保证可以实现计算出的占用率。

请注意，此 API 也可以与无上下文内核 CUkernel 一起使用，方法是使用 cuLibraryGetKernel() 查询句柄，然后将其强制转换为 CUfunction 后传递给 API。此处，用于计算的上下文将从指定的流中获取config->hStream或者在 NULL 流的情况下从当前上下文中获取。

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cudaFuncGetAttributes, cuFuncGetAttribute

CUresult cuOccupancyMaxPotentialBlockSize ( int* minGridSize, int* blockSize, CUfunction func, CUoccupancyB2DSize blockSizeToDynamicSMemSize, size_t dynamicSMemSize, int blockSizeLimit )

建议具有合理占用率的启动配置。

参数

minGridSize: - 返回的实现最大占用率所需的最小网格大小
blockSize: - 返回的可实现最大占用率的最大块大小
func: - 用于计算启动配置的内核
blockSizeToDynamicSMemSize: - 一个函数，用于计算每个块的动态共享内存量func基于块大小的使用量
dynamicSMemSize: - 计划的动态共享内存使用量，以字节为单位
blockSizeLimit: - 最大块大小func旨在处理

返回值

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_UNKNOWN

描述

在*blockSize可以实现最大占用率的合理块大小（或者，每个多处理器具有最少块的最大活动 Warp 数量），并在*minGridSize中返回实现最大占用率的最小网格大小。

如果blockSizeLimit为 0，则配置器将使用设备/函数允许的最大块大小。

如果不需要每个块的动态共享内存分配，则用户应将blockSizeToDynamicSMemSize和dynamicSMemSize都保留为 0。

如果需要每个块的动态共享内存分配，那么如果动态共享内存大小与块大小无关，则应通过dynamicSMemSize传递大小，并且blockSizeToDynamicSMemSize应为 NULL。

否则，如果每个块的动态共享内存大小随不同的块大小而变化，则用户需要通过blockSizeToDynamicSMemSize提供一个一元函数，该函数计算给定任何块大小的func所需的动态共享内存。dynamicSMemSize将被忽略。示例签名为

‎    // Take block size, returns dynamic shared memory needed
          size_t blockToSmem(int blockSize);

注意

请注意，此函数也可能返回来自先前异步启动的错误代码。

另请参阅

cudaOccupancyMaxPotentialBlockSize

CUresult cuOccupancyMaxPotentialBlockSizeWithFlags ( int* minGridSize, int* blockSize, CUfunction func, CUoccupancyB2DSize blockSizeToDynamicSMemSize, size_t dynamicSMemSize, int blockSizeLimit, unsigned int flags )

建议具有合理占用率的启动配置。

参数

minGridSize: - 返回的实现最大占用率所需的最小网格大小
blockSize: - 返回的可实现最大占用率的最大块大小
func: - 用于计算启动配置的内核
blockSizeToDynamicSMemSize: - 一个函数，用于计算每个块的动态共享内存量func基于块大小的使用量
dynamicSMemSize: - 计划的动态共享内存使用量，以字节为单位
blockSizeLimit: - 最大块大小func旨在处理
flags: - 选项

返回值

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_UNKNOWN

描述

是 cuOccupancyMaxPotentialBlockSize 的扩展版本。除了传递给 cuOccupancyMaxPotentialBlockSize 的参数外，cuOccupancyMaxPotentialBlockSizeWithFlags 还接受一个Flags参数。

TheFlags参数控制特殊情况的处理方式。有效标志为

CU_OCCUPANCY_DEFAULT，它保持与 cuOccupancyMaxPotentialBlockSize 相同的默认行为；

CU_OCCUPANCY_DISABLE_CACHING_OVERRIDE，它抑制了全局缓存影响占用率的平台上的默认行为。在此类平台上，产生最大占用率的启动配置可能不支持全局缓存。设置 CU_OCCUPANCY_DISABLE_CACHING_OVERRIDE 保证生成的启动配置与全局缓存兼容，但可能会牺牲占用率。有关此功能的更多信息，请参见 Maxwell 调优指南的“统一 L1/纹理缓存”部分。