cuDLA 设备句柄

cuDLA 模块句柄

导入NvSciBuffers的访问权限标志

设备属性类型。

支持的栅栏类型。

设备创建模式。

模块属性类型。

cudlaModuleLoadFromMemory的模块加载标志。

cuDLA NvSciSync属性。

错误代码。

cudlaSubmitTask的任务提交标志。

创建一个设备句柄。

参数

device

- Device number (can be 0 or 1).

devHandle

- Pointer to hold the created cuDLA device handle.

flags

- Flags controlling device creation. Valid values for flags are:

• CUDLA_CUDA_DLA - 在此模式下，cuDLA作为CUDA编程模型的扩展，允许使用CUDA结构提交DLA工作。
• CUDLA_STANDALONE - 在此模式下，cuDLA独立运行，不与CUDA进行任何交互。

返回

cudlaSuccess, cudlaErrorOutOfResources, cudlaErrorInvalidParam, cudlaErrorIncompatibleDlaSWVersion, cudlaErrorCreationFailed, cudlaErrorCuda, cudlaErrorUmd, cudlaErrorUnsupportedOperation

描述

创建一个cuDLA设备实例，可用于提交DLA操作。应用程序可以在混合模式或独立模式下创建该句柄。在混合模式下，此API会使用当前设置的GPU设备来决定所创建的DLA设备句柄的关联关系。如果当前设置的GPU设备是dGPU，由于目前cuDLA不支持dGPU，此函数将返回cudlaErrorUnsupportedOperation。每个DLA硬件实例支持16个cuDLA设备句柄。

销毁设备句柄。

参数

devHandle

- A valid device handle.

返回

cudlaSuccess, cudlaErrorInvalidDevice, cudlaErrorCuda, cudlaErrorUmd

描述

销毁通过cudlaCreateDevice创建的cuDLA设备实例。在销毁句柄之前，必须确保之前提交给设备的所有任务都已完成。否则可能导致应用程序崩溃。

在混合模式下，cuDLA内部使用CUDA通过主上下文执行内存分配。因此，在销毁或重置CUDA主上下文之前，必须销毁所有cuDLA设备初始化。

获取cuDLA设备属性。

参数

devHandle

- The input cuDLA device handle.

attrib

- The attribute that is being requested.

pAttribute

- The output pointer where the attribute will be available.

返回

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorInvalidDevice, cudlaErrorUmd, cudlaErrorInvalidAttribute

描述

CUDA与DLA之间的UVA寻址需要底层内核模式驱动的特殊支持。应用程序应查询cuDLA运行时以检查当前版本的cuDLA是否支持UVA寻址。

获取设备数量。

参数

pNumDevices

- The number of DLA devices will be available in this variable upon successful completion.

返回

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorUmd, cudlaErrorIncompatibleDlaSWVersion

描述

获取可用的DLA设备数量。

获取任务执行中的最后一个异步错误。

参数

devHandle

- A valid device handle.

返回

cudlaSuccess, cudlaErrorInvalidDevice, cudlaErrorDlaErrInvalidInput, cudlaErrorDlaErrInvalidPreAction, cudlaErrorDlaErrNoMem, cudlaErrorDlaErrProcessorBusy, cudlaErrorDlaErrTaskStatusMismatch, cudlaErrorDlaErrEngineTimeout, cudlaErrorDlaErrDataMismatch, cudlaErrorUnknown

描述

DLA任务在DLA硬件上异步执行。因此，在任务提交时无法获知任务执行状态。可以通过此接口查询特定设备句柄最近由DLA硬件执行的任务状态。

请注意，此函数返回的cudlaSuccess状态码并不保证最近执行的任务一定成功。由于该函数会立即返回，它只能反映调用时刻的任务状态快照。为确保任务完成，应用程序必须在混合或独立模式下对已提交的任务进行同步，然后再调用此API检查错误。

获取cuDLA的NvSciSync属性。

参数

attrList

- Attribute list created by the application.

flags

- Applications can use this flag to specify how they intend to use the NvSciSync object created from the attrList. The valid values of flags can be one of the following (or an OR of these values):

• CUDLA_NVSCISYNC_ATTR_WAIT, 指定应用程序打算将使用此属性列表创建的NvSciSync对象作为cuDLA中的等待器使用，因此需要cuDLA填充等待器特定的NvSciSyncAttr。
• CUDLA_NVSCISYNC_ATTR_SIGNAL，指定应用程序打算将使用此属性列表创建的NvSciSync对象作为cuDLA中的信号发送器使用，因此需要cuDLA填充信号发送器特定的NvSciSyncAttr。

返回

• cudlaSuccess, API调用成功返回，无错误。
• cudlaErrorInvalidParam, 该API调用失败，因为传入了无效参数attrList。
• cudlaErrorUnsupportedOperation, 此错误代码表示API调用失败，因为该操作在混合模式下不受支持。
• cudlaErrorInvalidAttribute, API调用失败，因为参数attrList包含无效值。
• cudlaErrorNvSci, 此错误代码表示在API调用过程中NvSci操作出现错误。
• cudlaErrorNotPermittedOperation，此错误代码表示当DRIVE OS处于运行状态时不允许进行该API调用。
• cudlaErrorUnknown, 该错误代码表示发生了未知错误。

描述

获取应用程序创建的属性列表中NvSciSync的属性。

cuDLA支持两种类型的NvSciSync对象原语 -

• 同步点

• 默认情况下，确定性信号量cuDLA会优先处理同步点原语而非确定性信号量原语，并在NvSciSync属性列表中设置这些优先级。

对于确定性信号量，用于创建NvSciSync对象的NvSciSync属性列表必须将NvSciSyncAttrKey_RequireDeterministicFences键的值设置为true。

cuDLA还支持NvSciSync对象上的时间戳功能。等待者可以通过将NvSciSync属性"NvSciSyncAttrKey_WaiterRequireTimestamps"设置为true来请求此功能。

如果NvSci初始化失败，此函数将返回cudlaErrorUnsupportedOperation。在某些情况下，当底层NvSci操作失败时，此函数可能返回cudlaErrorNvSci或cudlaErrorInvalidAttribute。

此API将使用等同于以下公共属性键值的值更新输入nvSciSyncAttrList：

NvSciSyncAttrKey_RequiredPerm 被设置为

• 如果标志的值设置为CUDLA_NVSCISYNC_ATTR_WAIT，则使用NvSciSyncAccessPerm_SignalOnly。

• 如果标志值设置为CUDLA_NVSCISYNC_ATTR_SIGNAL，则使用NvSciSyncAccessPerm_WaitOnly权限。

• 如果标志的值设置为CUDLA_NVSCISYNC_ATTR_SIGNAL | CUDLA_NVSCISYNC_ATTR_WAIT，则使用NvSciSyncAccessPerm_WaitSignal。

由于NvSciSyncAttrKey_RequiredPerm是由cuDLA内部设置的，因此不允许应用程序设置此值。

返回该库的版本号。

参数

version

- cuDLA library version will be available in this variable upon successful execution.

返回

cudlaSuccess, cudlaErrorInvalidParam

描述

cuDLA采用语义化版本号。此函数将返回版本号，格式为1000000*主版本号 + 1000*次版本号 + 修订号。

将外部内存导入到cuDLA中。

参数

devHandle

- A valid device handle.

desc

- Contains description about allocated external memory.

devPtr

- The output pointer where the mapping will be available.

flags

- Application can use this flag to specify the memory access permissions of the memory that needs to be registered with DLA. The valid values of flags can be one of the following:

• CUDLA_READ_WRITE_PERM，指定外部内存需要以读写内存的形式注册到DLA。
• CUDLA_READ_ONLY_PERM，指定外部内存需要以只读内存的形式注册到DLA。
• CUDLA_TASK_STATISTICS，指定外部内存需要向DLA注册以获取分层统计信息。

返回

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorInvalidDevice, cudlaErrorUnsupportedOperation, cudlaErrorNvSci, cudlaErrorInvalidAttribute, cudlaErrorMemoryRegistered, cudlaErrorUmd

描述

通过向DLA注册导入已分配的外部内存。成功注册后，返回的指针可用于任务提交。

在Tegra平台上，cuDLA仅支持在独立模式下导入NvSciBuf对象。如果NvSci初始化失败（可能是由于在混合模式下使用了此API或NvSci库初始化出现问题），该函数将返回cudlaErrorUnsupportedOperation。当底层NvSci操作失败时，该函数在某些情况下可能返回cudlaErrorNvSci或cudlaErrorInvalidAttribute。

将外部信号量导入到cuDLA中。

参数

devHandle

- A valid device handle.

desc

- Contains sempahore object.

devPtr

- The output pointer where the mapping will be available.

flags

- Reserved for future. Must be set to 0.

返回

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorInvalidDevice, cudlaErrorUnsupportedOperation, cudlaErrorNvSci, cudlaErrorInvalidAttribute, cudlaErrorMemoryRegistered

描述

通过向DLA注册导入已分配的外部信号量。成功注册后，返回的指针可用于任务提交中以通知同步对象。

在Tegra平台上，cuDLA仅支持在独立模式下导入NvSciSync对象。cuDLA支持的NvSciSync对象原语包括同步点和确定性信号量。

cuDLA还支持NvSciSync对象上的时间戳功能，用户可以通过该功能获取特定围栏信号触发时的DLA时钟快照。在任何时间点，最多只能有512个有效的时间戳缓冲区与围栏关联。例如，如果用户从启用了时间戳的单个NvSciSync对象创建了513个围栏，那么第1个围栏关联的时间戳缓冲区将与第513个围栏相同。

如果NvSci初始化失败（可能是由于在混合模式下使用此API或NvSci库初始化出现问题），该函数将返回cudlaErrorUnsupportedOperation。在某些情况下，当底层NvSci操作失败时，该函数可能返回cudlaErrorNvSci或cudlaErrorInvalidAttribute。

将CUDA内存注册到DLA引擎。

参数

devHandle

- A valid cuDLA device handle create by a previous call to cudlaCreateDevice.

ptr

- The CUDA pointer to be registered.

size

- The size of the mapping i.e the number of bytes from ptr that must be mapped.

devPtr

- The output pointer where the mapping will be available.

flags

- Applications can use this flag to control several aspects of the registration process. The valid values of flags can be one of the following (or an OR of these values):

• 0, 默认
• CUDLA_TASK_STATISTICS，指定外部内存需要向DLA注册以获取分层统计信息。

返回

cudlaSuccess, cudlaErrorInvalidDevice, cudlaErrorInvalidParam, cudlaErrorInvalidAddress, cudlaErrorCuda, cudlaErrorUmd, cudlaErrorOutOfResources, cudlaErrorMemoryRegistered, cudlaErrorUnsupportedOperation

描述

作为注册过程的一部分，系统会创建一个映射关系，使DLA硬件能够访问底层的CUDA内存。生成的映射信息存储在devPtr中，应用程序在提交操作中引用该内存时必须使用此映射。

如果待注册的指针或大小无效，该函数将返回cudlaErrorInvalidAddress。此外，如果输入指针已被注册过，则该函数将返回cudlaErrorMemoryRegistered。尝试重新注册内存不会在cuDLA中造成任何不可恢复的错误，即使发生此错误后应用程序仍可继续使用cuDLA API。

从DLA引擎中注销输入内存。

参数

devHandle

- A valid cuDLA device handle create by a previous call to cudlaCreateDevice.

devPtr

- The pointer to be unregistered.

返回

cudlaSuccess, cudlaErrorInvalidDevice, cudlaErrorInvalidAddress, cudlaErrorUmd

描述

使DLA硬件能够访问内存的系统映射已被移除。该映射可能是由之前调用cudlaMemRegister、cudlaImportExternalMemory或cudlaImportExternalSemaphore创建的。

获取DLA模块属性。

参数

hModule

- The input DLA module.

attrType

- The attribute type that is being requested.

attribute

- The output pointer where the attribute will be available.

返回

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorInvalidModule, cudlaErrorInvalidDevice, cudlaErrorUmd, cudlaErrorInvalidAttribute, cudlaErrorUnsupportedOperation

描述

从已加载的模块中获取模块属性。如果模块未在任何设备中加载，此API将返回cudlaErrorInvalidDevice。

加载一个DLA模块。

参数

devHandle

- The input cuDLA device handle. The module will be loaded in the context of this handle.

pModule

- A pointer to an in-memory module.

moduleSize

- The size of the module.

hModule

- The address in which the loaded module handle will be available upon successful execution.

flags

- Applications can use this flag to specify how the module is going to be used. The valid values of flags can be one of the following:

• CUDLA_MODULE_DEFAULT, 默认值为0。
• CUDLA_MODULE_ENABLE_FAULT_DIAGNOSTICS, 应用程序可以指定此标志来加载用于执行DLA硬件故障诊断的模块。设置此标志后，pModule和moduleSize参数应为NULL和0，因为诊断模块是内部加载的。

返回

cudlaSuccess, cudlaErrorInvalidDevice, cudlaErrorInvalidParam, cudlaErrorOutOfResources, cudlaErrorUnsupportedOperation, cudlaErrorUmd

描述

将模块加载到当前设备句柄中。

• 不允许将多个可加载项加载到单个cuDLA设备句柄上。

• 在cuDLA设备句柄的生命周期内，一个可加载对象只能被加载一次。

卸载一个DLA模块。

参数

hModule

- Handle to the loaded module.

flags

- Reserved for future. Must be set to 0.

返回

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorInvalidDevice, cudlaErrorInvalidModule, cudlaErrorUmd

描述

从加载该模块的设备句柄中卸载模块。如果模块未加载到有效设备中，此API将返回cudlaErrorInvalidDevice。

设置任务超时时间，单位为毫秒。

参数

devHandle

- A valid device handle.

timeout

- task timeout value in ms.

返回

cudlaSuccess, cudlaErrorInvalidParam

描述

为每个设备句柄设置任务超时时间（毫秒）。如果用户未明确设置超时时间，cuDLA默认将超时值设为30秒。

如果设备句柄无效或超时时间为0或超时时间超过1000秒，该函数将返回cudlaErrorInvalidParam，否则返回cudlaSuccess。

在DLA上提交推理操作。

参数

devHandle

- A valid cuDLA device handle.

ptrToTasks

- A list of inferencing tasks.

numTasks

- The number of tasks.

stream

- The stream on which the DLA task has to be submitted.

flags

- Applications can use this flag to control several aspects of the submission process. The valid values of flags can be one of the following (or an OR of these values):

• 0, 默认值
• CUDLA_SUBMIT_NOOP，指定提交的任务在DLA执行期间必须跳过。但是，所有waitEvents和signalEvents的依赖关系必须满足。当进行NULL数据提交时此标志会被忽略，因为在这种情况下仅会内部存储等待和信号事件以供下一个任务提交使用。
• CUDLA_SUBMIT_SKIP_LOCK_ACQUIRE，指定提交的任务正在被加入设备句柄队列，且此时没有其他线程正在向该设备句柄队列加入其他任务。这是一个应用程序可用于优化的标志。通常，cuDLA API会在内部获取全局锁以保证线程安全。但在应用程序向不同设备句柄提交任务的情况下，此锁会导致不必要的串行化。如果应用程序在多个线程中提交一个或多个任务，且这些提交面向不同的设备句柄，并且在各自的提交中没有共享数据作为任务信息的一部分，则应用程序可以在提交时指定此标志以跳过内部锁获取。共享数据还包括混合模式操作中的输入流。因此，如果使用相同的流提交两个不同的任务，即使两个设备句柄不同，此标志的使用也是无效的。
• CUDLA_SUBMIT_DIAGNOSTICS_TASK，指定提交的任务是为DLA硬件运行永久性故障诊断。用户可以使用此任务来探测DLA硬件的状态。设置此标志后，在独立模式下不允许用户进行仅包含事件（等待/信号或两者）的任务提交（此时张量信息为NULL）。这是因为该任务始终运行在内部加载的诊断模块上。该诊断模块不需要任何输入张量，因此不需要输入张量内存，但用户需要查询输出张量的数量，分配输出张量内存，并在使用提交任务时传递这些信息。

返回

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorInvalidDevice, cudlaErrorInvalidModule, cudlaErrorCuda, cudlaErrorUmd, cudlaErrorOutOfResources, cudlaErrorInvalidAddress, cudlaErrorUnsupportedOperation, cudlaErrorInvalidAttribute, cudlaErrorNvScicudlaErrorOs

描述

该操作接收一系列任务，并按输入任务数组中的顺序将它们提交到DLA硬件执行。假设输入和输出张量（如果使用还包括统计缓冲区）已通过cudlaMemRegister（混合模式）或cudlaImportExternalMemory（独立模式）预先注册。若未完成预注册，可能导致本函数返回cudlaErrorInvalidAddress错误。

stream参数必须指定为在混合模式下提交DLA任务执行的CUDA流。在独立模式下，此参数必须传递为NULL，否则将导致此函数返回cudlaErrorInvalidParam。

cudlaTask 结构体提供了指定等待和信号事件的机制，这些事件分别表示 cuDLA 在执行 cudlaSubmitTask() 时必须等待和触发的操作。每个提交的任务将在开始执行前等待其所有等待事件被触发，并提供一个信号事件（如果在 cudlaSubmitTask 期间请求了该事件），应用程序（或任何其他实体）可以等待该信号事件以确保提交的任务已完成执行。在 cuDLA 1.0 中，仅支持将 NvSciSync 栅栏作为等待事件的一部分。此外，只有 NvSciSync 对象（通过 cudlaImportExternalSemaphore 注册）可以作为信号事件的一部分被触发，并且与触发事件对应的栅栏将作为 cudlaSubmitTask 的一部分返回。

在独立模式下，如果在cudlaTask结构体中将inputTensor和outputTensor字段设置为NULL，则任务提交将被解释为等待和信号事件的入队操作，这些事件必须被后续任务提交考虑。实际上并未执行真正的任务提交。在输入/输出Tensor字段中多次提交带有NULL字段的后续任务将覆盖待考虑的等待和信号事件列表。换句话说，在非NULL提交之前最新的非NULL等待事件和/或最新的非NULL信号事件将被用于后续实际任务提交。在独立模式下执行实际任务提交时，将被考虑的有效等待事件和信号事件包括：应用程序通过NULL数据提交设置的内容，以及该特定任务提交在waitEvents和signalEvents字段中设置的内容。作为NULL数据提交一部分设置的等待事件仅被视为第一个任务的依赖项，而作为NULL数据提交一部分设置的信号事件将在任务列表的最后一个任务完成时触发。所有单独适用于waitEvents和signalEvents的约束条件（如下所述）同样适用于组合后的列表。

cuDLA支持3种类型的fence - preFence、SOF fence和EOF fence。

• preFence是DLA等待开始任务执行时的围栏类型。使用cudlaFenceType作为CUDLA_NVSCISYNC_FENCE来将围栏标记为preFence。

• SOF(Start Of Frame)围栏是一种在DLA上任务执行开始前发出信号的围栏类型。使用cudlaFenceType 设置为CUDLA_NVSCISYNC_FENCE_SOF来将围栏标记为SOF围栏。

• EOF(End Of Frame)围栏是一种在DLA上任务执行完成后发出信号的围栏类型。使用cudlaFenceType为CUDLA_NVSCISYNC_FENCE来将围栏标记为EOF围栏。

对于等待事件，应用程序预期会

• 使用cudlaImportExternalSemaphore注册其同步对象。

• 使用CudlaFence创建所需数量的preFence占位符。

• 使用应用程序中的相关围栏填充占位符。

• 列出cudlaWaitEvents中的所有围栏。

对于信号事件，应用程序预期会

• 使用cudlaImportExternalSemaphore注册其同步对象。

• 使用CudlaFence创建所需数量的SOF和EOF围栏占位符围栏。

• 将注册对象和对应的栅栏放入cudlaSignalEvents中。对于确定性信号量，无需在cudlaSignalEvents中传递栅栏。

  当cudlaSubmitTask成功返回时，可以使用cudlaSignalEvents中的栅栏来等待特定任务完成。cuDLA支持1个同步点和任意数量的信号量作为cudlaSignalEvents的组成部分。如果指定超过1个同步点，将返回cudlaErrorInvalidParam错误。

cuDLA遵循DLA的限制，每个DLA任务最多支持29个preFences和SOF fences的组合，以及29个EOF fences。

在提交过程中，用户可以选择为网络的各个层启用逐层统计性能分析功能。 该选项需要通过指定额外的输出缓冲区来启用，这些缓冲区将包含性能分析信息。具体而言，

• "cudlaTask::numOutputTensors" 应为 cudlaModuleGetAttributes(...,CUDLA_NUM_OUTPUT_TENSORS,...) 和 cudlaModuleGetAttributes(...,CUDLA_NUM_OUTPUT_TASK_STATISTICS,...) 返回值的总和

• "cudlaTask::outputTensor" 应包含附加了统计输出缓冲区数组的输出张量数组。

如果出现以下情况，该函数可能返回 cudlaErrorUnsupportedOperation

• 以混合模式使用的流处于捕获状态。

• 应用程序尝试在混合模式下使用NvSci功能。

• 针对特定平台加载NvSci库失败。

• 指定了除CUDLA_NVSCISYNC_FENCE之外的围栏类型。

• 在混合模式下，waitEvents或signaEvents不为NULL。

• 在混合模式下，inputTensor或outputTensor为NULL，且标志不是CUDLA_SUBMIT_DIAGNOSTICS_TASK。

• 在独立模式下，当inputTensor为NULL且outputTensor不为NULL，或者相反情况时，且标志位不是CUDLA_SUBMIT_DIAGNOSTICS_TASK。

• 在独立模式下，当inputTensor和outputTensor为NULL且任务数量不等于1，并且标志不是CUDLA_SUBMIT_DIAGNOSTICS_TASK时。

• inputTensor 不为 NULL 或 output tensor 为 NULL 且 flags 为 CUDLA_SUBMIT_DIAGNOSTICS_TASK。

• 有效信号事件列表包含多个需要同步的信号点。

• 如果层间特征不受支持。

• 如果未满足每个任务的preFences、SOF fences和EOF fences限制。

在某些情况下，当底层NvSci操作失败时，此函数可能返回cudlaErrorNvSci或cudlaErrorInvalidAttribute。

如果内部系统操作失败，此函数可能返回cudlaErrorOs。