6.35. 绿色上下文环境

本节介绍CUDA驱动中用于创建和操作绿色上下文的API。绿色上下文是传统上下文的轻量级替代方案，能够传入一组初始化所需的资源。这使得开发者可以表示GPU的不同空间分区，为其分配资源，并通过CUDA提供的相同编程模型（如流、内核启动等）来定位这些分区。

使用这套新API主要有4个步骤。

对于CU_DEV_RESOURCE_TYPE_SM，创建的分区具有最低SM数量要求，通常会向上取整并将提供的minCount与cuDevSmResourceSplitByCount对齐。以下是每种架构的指导原则，可能会有所变化：

  • 在计算架构6.X上：最小数量为1个SM。

  • 在计算架构7.X上：最小数量为2个SM，且必须是2的倍数。

  • 在计算架构8.X上：最小数量为4个SM，且必须是2的倍数。

  • 在计算架构9.0及以上版本：最小数量为8个流式多处理器(SMs)，且必须是8的倍数。

未来，可以通过提供标志来在功能和性能特性与更细粒度的SM分区之间进行权衡。

即使绿色上下文具有不相交的SM分区，也不能保证在其中启动的内核会并发运行或具有前向进度保证。这是由于其他资源（如硬件连接，参见CUDA_DEVICE_MAX_CONNECTIONS）可能导致依赖关系。此外，在某些情况下，工作负载可能会在比配置更多的SM上运行（但绝不会更少）。以下是可能表现出这种行为的两种场景：

  • 在Volta及以上架构的MPS上：当使用CUDA_MPS_ACTIVE_THREAD_PERCENTAGE时，用于运行内核的SM集合可以扩展到MPS客户端所使用的SM数量值。

  • 在计算架构9.x上：当加载了支持动态并行性(CDP)的模块时，所有在绿色上下文环境下运行的内核可能会使用并共享额外的2个SM资源。

类

struct 
struct 

类型定义

typedef CUdevResourceDesc_st *  CUdevResourceDesc

枚举

enum CUdevResourceType

Functions

CUresult cuCtxFromGreenCtx ( CUcontext* pContext, CUgreenCtx hCtx )
Converts a green context into the primary context.
CUresult cuCtxGetDevResource ( CUcontext hCtx, CUdevResource* resource, CUdevResourceType type )
Get context resources.
CUresult cuDevResourceGenerateDesc ( CUdevResourceDesc* phDesc, CUdevResource* resources, unsigned int  nbResources )
Generate a resource descriptor.
CUresult cuDevSmResourceSplitByCount ( CUdevResource* result, unsigned int* nbGroups, const CUdevResource* input, CUdevResource* remaining, unsigned int  useFlags, unsigned int  minCount )
Splits CU_DEV_RESOURCE_TYPE_SM resources.
CUresult cuDeviceGetDevResource ( CUdevice device, CUdevResource* resource, CUdevResourceType type )
Get device resources.
CUresult cuGreenCtxCreate ( CUgreenCtx* phCtx, CUdevResourceDesc desc, CUdevice dev, unsigned int  flags )
Creates a green context with a specified set of resources.
CUresult cuGreenCtxDestroy ( CUgreenCtx hCtx )
Destroys a green context.
CUresult cuGreenCtxGetDevResource ( CUgreenCtx hCtx, CUdevResource* resource, CUdevResourceType type )
Get green context resources.
CUresult cuGreenCtxRecordEvent ( CUgreenCtx hCtx, CUevent hEvent )
Records an event.
CUresult cuGreenCtxStreamCreate ( CUstream* phStream, CUgreenCtx greenCtx, unsigned int  flags, int  priority )
Create a stream for use in the green context.
CUresult cuGreenCtxWaitEvent ( CUgreenCtx hCtx, CUevent hEvent )
Make a green context wait on an event.
CUresult cuStreamGetGreenCtx ( CUstream hStream, CUgreenCtx* phCtx )
Query the green context associated with a stream.

类型定义

typedef CUdevResourceDesc_st * CUdevResourceDesc

一个不透明的描述符句柄。该描述符封装了多个已创建和配置的资源。通过 cuDevResourceGenerateDesc 创建

枚举

enum CUdevResourceType

资源类型

数值
CU_DEV_RESOURCE_TYPE_INVALID = 0
CU_DEV_RESOURCE_TYPE_SM = 1
Streaming multiprocessors related information

Functions

CUresult cuCtxFromGreenCtx ( CUcontext* pContext, CUgreenCtx hCtx )
将绿色上下文转换为主上下文。
参数
pContext
Returned primary context with green context resources
hCtx
Green context to convert
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE

描述

该API将绿色上下文转换为返回在pContext中的主上下文。需要注意的是，转换后的上下文pContext是一个普通的主上下文，但具有指定绿色上下文hCtx的资源。转换完成后，就可以使用cuCtxSetCurrent或任何接受CUcontext参数的CUDA API来将其设置为当前上下文。

用户应在调用任何接受CUcontext的CUDA API之前调用此API。否则将导致API返回CUDA_ERROR_INVALID_CONTEXT错误。

另请参阅：

cuGreenCtxCreate

CUresult cuCtxGetDevResource ( CUcontext hCtx, CUdevResource* resource, CUdevResourceType type )
获取上下文资源。
参数
hCtx
- Context to get resource for
resource
- Output pointer to a CUdevResource structure
type
- Type of resource to retrieve
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_RESOURCE_TYPE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_CONTEXT

描述

获取由hCtx表示的上下文中可用的type资源 注意：此API在32位平台上不受支持。

另请参阅：

cuDevResourceGenerateDesc

CUresult cuDevResourceGenerateDesc ( CUdevResourceDesc* phDesc, CUdevResource* resources, unsigned int  nbResources )
生成资源描述符。
参数
phDesc
- Output descriptor
resources
- Array of resources to be included in the descriptor
nbResources
- Number of resources passed in resources
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_RESOURCE_TYPE, CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION

描述

生成一个包含resources中指定资源集的单一资源描述符。生成的资源描述符是通过cuGreenCtxCreate API创建绿色上下文所必需的。只要满足以下要求，可以传入相同类型的资源。

一个成功的API调用必须包含：

  • 一个有效的phDesc描述符输出指针，以及一个有效的resources指针数组，数组大小通过nbResources传递。如果在resources中提供了多个资源，则这些资源必须来自同一设备，否则将返回CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION。如果在resources中提供了多个类型为CU_DEV_RESOURCE_TYPE_SM的资源，则它们必须是来自同一分割API实例的输出（无论是result还是remaining），否则将返回CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION。

注意：该API不支持32位平台。

另请参阅：

cuDevSmResourceSplitByCount

CUresult cuDevSmResourceSplitByCount ( CUdevResource* result, unsigned int* nbGroups, const CUdevResource* input, CUdevResource* remaining, unsigned int  useFlags, unsigned int  minCount )
Splits CU_DEV_RESOURCE_TYPE_SM resources.
参数
result
- Output array of CUdevResource resources. Can be NULL to query the number of groups.
nbGroups
- This is a pointer, specifying the number of groups that would be or should be created as described below.
input
- Input SM resource to be split. Must be a valid CU_DEV_RESOURCE_TYPE_SM resource.
remaining
- If the input resource cannot be cleanly split among nbGroups, the remaining is placed in here. Can be ommitted (NULL) if the user does not need the remaining set.
useFlags
- Flags specifying how these partitions are used or which constraints to abide by when splitting the input. Zero is valid for default behavior.
minCount
- Minimum number of SMs required
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_RESOURCE_TYPE, CUDA_ERROR_INVALID_RESOURCE_CONFIGURATION

描述

将CU_DEV_RESOURCE_TYPE_SM资源分割为nbGroups组，遵循minCount中指定的最小SM数量以及useFlags中的使用标志。如果result为NULL，该API会模拟分割操作并在nbGroups中返回可创建的组数。否则，nbGroups必须指向result数组的元素数量，返回时API会用实际创建的组数覆盖nbGroups值。分割后的组将被写入result数组中。当需要较少的组数时，nbGroups可能小于总组数。

该API用于对输入资源进行空间分区。输入资源需来自cuDeviceGetDevResource、cuCtxGetDevResource或cuGreenCtxGetDevResource之一。该API的限制在于：若未先创建描述符及使用该描述符的绿色上下文，则无法再次分割输出结果。

在创建分组时，API会考虑输入资源的性能和功能特性，并确保分割形成一组互不相交的对称分区。由于集群要求或minCount的对齐与粒度要求，这可能导致实际创建的分组数量少于单纯将总SM计数除以minCount得到的结果。

remainder集合不具备与result中分组相同的功能或性能保证。使用时应谨慎规划，不建议对remainder集合进行未来分区。

支持以下标志：

  • CU_DEV_SM_RESOURCE_SPLIT_IGNORE_SM_COSCHEDULING : 降低最小SM数量和对齐要求，并将每个SM视为独立于其层级结构。这样可以实现更细粒度的分区，但会牺牲高级功能（例如在计算能力9.0+上的大型集群支持）。

  • CU_DEV_SM_RESOURCE_SPLIT_MAX_POTENTIAL_CLUSTER_SIZE : 仅适用于计算能力9.0及以上版本。尝试创建可能允许最大线程集群大小的组。这可以在绿色上下文创建后通过cuOccupancyMaxPotentialClusterSize进行查询。

一个成功的API调用必须满足以下条件之一：

  • 一个有效的result指针数组，其大小为传入的nbGroups参数值，且input类型为CU_DEV_RESOURCE_TYPE_SM。minCount的值必须在0到input中指定的SM数量之间。remaining可以为NULL。

  • 当result传入NULL，且nbGroups为有效的整数指针，input类型为CU_DEV_RESOURCE_TYPE_SM时。minCount的值必须在0到input指定的SM数量之间。remaining可以为NULL。此操作查询API将会创建的组数量。

注意：该API不支持32位平台。

另请参阅：

cuGreenCtxGetDevResource, cuCtxGetDevResource, cuDeviceGetDevResource

CUresult cuDeviceGetDevResource ( CUdevice device, CUdevResource* resource, CUdevResourceType type )
获取设备资源。
参数
device
- Device to get resource for
resource
- Output pointer to a CUdevResource structure
type
- Type of resource to retrieve
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_RESOURCE_TYPE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_INVALID_DEVICE

描述

获取device可用的type资源。这通常是进一步划分或配置资源的起点。

注意：该API不支持32位平台。

另请参阅：

cuDevResourceGenerateDesc

CUresult cuGreenCtxCreate ( CUgreenCtx* phCtx, CUdevResourceDesc desc, CUdevice dev, unsigned int  flags )
创建一个带有指定资源集的绿色上下文。
参数
phCtx
- Pointer for the output handle to the green context
desc
- Descriptor generated via cuDevResourceGenerateDesc which contains the set of resources to be used
dev
- Device on which to create the green context.
flags
- One of the supported green context creation flags. CU_GREEN_CTX_DEFAULT_STREAM is required.
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_DEVICE, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_NOT_SUPPORTED, CUDA_ERROR_OUT_OF_MEMORY

描述

该API会创建一个绿色上下文，其中包含描述符desc中指定的资源，并通过句柄phCtx返回。此API将保留设备dev上的主上下文，该上下文会在绿色上下文销毁时释放。建议在调用此API之前先激活主上下文，以避免多次触发主上下文初始化和反初始化的高昂开销。

该API不会自动将绿色上下文设为当前上下文。如需将其设为当前上下文，您需要先通过cuCtxFromGreenCtx将绿色上下文转换为CUcontext，然后显式调用cuCtxSetCurrent或cuCtxPushCurrent进行设置。需要注意的是，一个绿色上下文同一时间只能在一个线程中设为当前上下文。系统内部没有同步机制来支持多线程同时访问同一个绿色上下文的API调用。

注意：该API不支持32位平台。

支持的标志有：

  • CU_GREEN_CTX_DEFAULT_STREAM : 在绿色上下文中创建要使用的默认流。必需项。

另请参阅：

cuGreenCtxDestroy, cuCtxFromGreenCtx, cuCtxSetCurrent, cuCtxPushCurrent, cuDevResourceGenerateDesc, cuDevicePrimaryCtxRetain, cuCtxCreate, cuCtxCreate_v3

CUresult cuGreenCtxDestroy ( CUgreenCtx hCtx )
销毁一个绿色上下文。
参数
hCtx
- Green context to be destroyed
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_CONTEXT_IS_DESTROYED

描述

销毁绿色上下文，释放该绿色上下文所针对设备的主上下文。同时也会释放为该绿色上下文配置的所有资源（这些资源最初是通过资源描述符提供的）。

另请参阅：

cuGreenCtxCreate, cuCtxDestroy

CUresult cuGreenCtxGetDevResource ( CUgreenCtx hCtx, CUdevResource* resource, CUdevResourceType type )
获取绿色上下文资源。
参数
hCtx
- Green context to get resource for
resource
- Output pointer to a CUdevResource structure
type
- Type of resource to retrieve
返回

CUDA_SUCCESSCUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_RESOURCE_TYPE, CUDA_ERROR_INVALID_VALUE

描述

获取由hCtx表示的绿色上下文可用的type资源

另请参阅：

cuDevResourceGenerateDesc

CUresult cuGreenCtxRecordEvent ( CUgreenCtx hCtx, CUevent hEvent )
记录一个事件。
参数
hCtx
- Green context to record event for
hEvent
- Event to record
返回

CUDA_SUCCESSCUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED

描述

在本次调用时，捕获hCtx绿色上下文中的所有活动到hEvent中。hEvent和hCtx必须来自同一个主上下文，否则将返回CUDA_ERROR_INVALID_HANDLE。随后调用如cuEventQuery()或cuGreenCtxWaitEvent()等函数将检查或等待被捕获工作的完成。本次调用后对hCtx的使用不会修改hEvent。

Note:

如果指定的绿色上下文hCtx中有流处于捕获模式，API将返回CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED。在这种情况下，调用将使所有冲突的捕获失效。

另请参阅：

cuGreenCtxWaitEvent, cuEventRecord, cuCtxRecordEvent, cuCtxWaitEvent

CUresult cuGreenCtxStreamCreate ( CUstream* phStream, CUgreenCtx greenCtx, unsigned int  flags, int  priority )
创建一个流用于绿色上下文。
参数
phStream
- Returned newly created stream
greenCtx
- Green context for which to create the stream for
flags
- Flags for stream creation. CU_STREAM_NON_BLOCKING must be specified.
priority
- Stream priority. Lower numbers represent higher priorities. See cuCtxGetStreamPriorityRange for more information about meaningful stream priorities that can be passed.
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE, CUDA_ERROR_OUT_OF_MEMORY

描述

为指定的绿色上下文greenCtx创建一个流，并在phStream中返回一个句柄。该流可以通过调用cuStreamDestroy()来销毁。请注意，该API会忽略调用线程的当前上下文，而是在指定的绿色上下文greenCtx中创建流。

flags 支持的值为：

  • CU_STREAM_NON_BLOCKING: 必须指定此标志。它表示在创建的流中运行的工作可以与默认流中的工作并发执行，且创建的流不应与默认流进行任何隐式同步。

指定priority会影响流中工作的调度优先级。优先级机制会在可能时优先运行较高优先级的工作，但不会抢占已在运行的工作，也不对执行顺序提供任何其他功能性保证。priority遵循数值越小优先级越高的惯例，'0'表示默认优先级。可通过cuCtxGetStreamPriorityRange查询有效数值优先级的范围。若指定的优先级超出cuCtxGetStreamPriorityRange返回的数值范围，将自动调整为该范围内的最小值或最大值。

Note:

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

  • 在当前实现中，只有优先级流中启动的计算内核会受到流优先级的影响。流优先级对主机到设备和设备到主机的内存操作没有影响。

另请参阅：

cuStreamDestroy, cuGreenCtxCreatecuStreamCreate, cuStreamGetPriority, cuCtxGetStreamPriorityRange, cuStreamGetFlags, cuStreamGetDevicecuStreamWaitEvent, cuStreamQuery, cuStreamSynchronize, cuStreamAddCallback, cudaStreamCreateWithPriority

CUresult cuGreenCtxWaitEvent ( CUgreenCtx hCtx, CUevent hEvent )
让绿色上下文等待一个事件。
参数
hCtx
- Green context to wait
hEvent
- Event to wait on
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE, CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED

描述

使所有后续提交到绿色上下文hCtx的工作等待hEvent中捕获的所有工作完成。该同步将在设备上执行，不会阻塞调用CPU线程。有关事件捕获内容的详细信息，请参阅cuGreenCtxRecordEvent()或cuEventRecord()。

Note:

  • hEvent可能来自与hCtx不同的上下文或设备。

  • 如果指定的事件hEvent属于正在进行的捕获序列，或者指定的绿色上下文hCtx中有流处于捕获模式，API将返回CUDA_ERROR_STREAM_CAPTURE_UNSUPPORTED并使捕获失效。

另请参阅：

cuGreenCtxRecordEvent, cuStreamWaitEventcuCtxRecordEvent, cuCtxWaitEvent

CUresult cuStreamGetGreenCtx ( CUstream hStream, CUgreenCtx* phCtx )
查询与流关联的绿色上下文。
参数
hStream
- Handle to the stream to be queried
phCtx
- Returned green context associated with the stream
返回

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_HANDLE,

描述

返回流所关联的CUDA绿色上下文，如果流未关联任何绿色上下文则返回NULL。

流句柄 hStream 可以指向以下任意一种情况：

Passing an invalid handle will result in undefined behavior.

Note:

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

另请参阅：

cuStreamDestroy, cuStreamCreate, cuStreamCreateWithPriority, cuStreamGetCtx_v2, cuGreenCtxStreamCreate, cuStreamGetPriority, cuStreamGetFlags, cuStreamGetDevicecuStreamWaitEvent, cuStreamQuery, cuStreamSynchronize, cuStreamAddCallback, cudaStreamCreate, cudaStreamCreateWithFlags