cuDLA 设备句柄

cuDLA 模块句柄

导入 NvSciBuffers 的访问权限标志

设备属性类型。

支持的 Fence 类型。

设备创建模式。

模块属性类型。

用于 cudlaModuleLoadFromMemory 的模块加载标志。

cuDLA NvSciSync 属性。

错误代码。

用于 cudlaSubmitTask 的任务提交标志。

创建设备句柄。

参数

device

- 设备编号（可以是 0 或 1）。

devHandle

- 用于保存创建的 cuDLA 设备句柄的指针。

flags

- 控制设备创建的标志。有效值为flags是

• 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，则此函数返回 cudlaErrorUnsupportedOperation，因为 cuDLA 目前在 dGPU 上不受支持。cuDLA 每个 DLA HW 实例支持 16 个 cuDLA 设备句柄。

销毁设备句柄。

参数

devHandle

- 有效的设备句柄。

返回值

cudlaSuccess, cudlaErrorInvalidDevice, cudlaErrorCuda, cudlaErrorUmd

描述

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

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

获取 cuDLA 设备属性。

参数

devHandle

- 输入 cuDLA 设备句柄。

attrib

- 正在请求的属性。

pAttribute

- 属性将在其中可用的输出指针。

返回值

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorInvalidDevice, cudlaErrorUmd, cudlaErrorInvalidAttribute

描述

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

获取设备计数。

参数

pNumDevices

- 成功完成后，DLA 设备的数量将在此变量中可用。

返回值

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorUmd, cudlaErrorIncompatibleDlaSWVersion

描述

获取可用的 DLA 设备数量。

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

参数

devHandle

- 有效的设备句柄。

返回值

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

描述

DLA 任务在 DLA HW 上异步执行。因此，任务执行的状态在任务提交时未知。可以使用此接口查询最近为特定设备句柄执行的 DLA HW 执行的任务状态。

请注意，从此函数返回 cudlaSuccess 返回代码不一定意味着最近的任务执行成功。由于此函数立即返回，因此它只能报告调用时的时间快照的任务状态。为了保证任务完成，应用程序必须在混合模式或独立模式下同步提交的任务，然后调用此 API 以检查错误。

获取 cuDLA 的 NvSciSync 属性。

参数

attrList

- 应用程序创建的属性列表。

flags

- 应用程序可以使用此标志来指定他们打算如何使用从attrList. 创建的 NvSciSync 对象。 的有效值flags可以是以下值之一（或这些值的 OR 运算）

• 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 处于 Operational 状态时，不允许进行 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 库版本。

返回值

cudlaSuccess, cudlaErrorInvalidParam

描述

cuDLA 是语义化版本控制的。此函数将返回版本，格式为 1000000*主版本号 + 1000*次版本号 + 补丁版本号。

将外部内存导入到 cuDLA 中。

参数

devHandle

- 有效的设备句柄。

desc

- 包含有关已分配外部内存的描述。

devPtr

- 映射可用的输出指针。

flags

- 应用程序可以使用此标志来指定需要向 DLA 注册的内存的内存访问权限。 的有效值flags可以是以下之一

• 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

- 有效的设备句柄。

desc

- 包含信号量对象。

devPtr

- 映射可用的输出指针。

flags

- 保留供将来使用。必须设置为 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

- 通过先前调用 cudlaCreateDevice 创建的有效 cuDLA 设备句柄。

ptr

- 要注册的 CUDA 指针。

size

- 映射的大小，即必须映射的 ptr 中的字节数。

devPtr

- 映射可用的输出指针。

flags

- 应用程序可以使用此标志来控制注册过程的多个方面。 的有效值flags可以是以下值之一（或这些值的 OR 运算）

• 0, 默认值
• CUDLA_TASK_STATISTICS，指定需要将外部内存注册到 DLA 以进行逐层统计。

返回值

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

描述

作为注册的一部分，将创建一个系统映射，DLA HW 可以通过该映射访问底层的 CUDA 内存。生成的映射在 devPtr 中可用，应用程序在提交操作中引用此内存时必须使用此映射。

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

从 DLA 引擎注销输入内存。

参数

devHandle

- 通过先前调用 cudlaCreateDevice 创建的有效 cuDLA 设备句柄。

devPtr

- 要注销的指针。

返回值

cudlaSuccess, cudlaErrorInvalidDevice, cudlaErrorInvalidAddress, cudlaErrorUmd

描述

删除使 DLA HW 能够访问内存的系统映射。此映射可能是通过先前调用 cudlaMemRegister 、 cudlaImportExternalMemory 或 cudlaImportExternalSemaphore 创建的。

获取 DLA 模块属性。

参数

hModule

- 输入 DLA 模块。

attrType

- 正在请求的属性类型。

attribute

- 属性将在其中可用的输出指针。

返回值

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

描述

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

加载 DLA 模块。

参数

devHandle

- 输入 cuDLA 设备句柄。模块将在此句柄的上下文中加载。

pModule

- 指向内存中模块的指针。

moduleSize

- 模块的大小。

hModule

- 加载的模块句柄将在成功执行后在此地址中可用。

flags

- 应用程序可以使用此标志来指定模块的使用方式。 的有效值flags可以是以下之一

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

返回值

cudlaSuccess, cudlaErrorInvalidDevice, cudlaErrorInvalidParam, cudlaErrorOutOfResources, cudlaErrorUnsupportedOperation, cudlaErrorUmd

描述

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

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

• 可加载项在 cuDLA 设备句柄生命周期中只能加载一次。

卸载 DLA 模块。

参数

hModule

- 加载模块的句柄。

flags

- 保留供将来使用。必须设置为 0。

返回值

cudlaSuccess, cudlaErrorInvalidParam, cudlaErrorInvalidDevice, cudlaErrorInvalidModule, cudlaErrorUmd

描述

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

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

参数

devHandle

- 有效的设备句柄。

timeout

- 任务超时值，单位为毫秒。

返回值

cudlaSuccess, cudlaErrorInvalidParam

描述

为每个设备句柄设置任务超时时间，单位为毫秒。如果用户未显式设置超时时间，cuDLA 会将默认超时值设置为 30 秒。

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

在 DLA 上提交推理操作。

参数

devHandle

- 有效的 cuDLA 设备句柄。

ptrToTasks

- 推理任务列表。

numTasks

- 任务数。

stream

- 必须在哪个流上提交 DLA 任务。

flags

- 应用程序可以使用此标志来控制提交过程的多个方面。 的有效值flags可以是以下值之一（或这些值的 OR 运算）

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

返回值

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

描述

此操作接受一系列任务，并将它们提交到 DLA HW 以按照它们在输入任务数组中出现的相同顺序执行。输入和输出张量（以及统计缓冲区，如果使用）假定已使用 cudlaMemRegister （在混合模式下）或 cudlaImportExternalMemory （在独立模式下）预先注册。否则可能会导致此函数返回 cudlaErrorInvalidAddress。

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

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

在独立模式下，如果在 cudlaTask 结构中将 inputTensor 和 outputTensor 字段设置为 NULL，则任务提交被解释为必须为后续任务提交考虑的 wait 和 signal 事件的入队。不执行实际的任务提交。多个此类后续任务提交（输入/输出张量字段中具有 NULL 字段）将覆盖要考虑的 wait 和 signal 事件列表。换句话说，在非 NULL 提交之前的最新非 NULL wait 事件和/或最新非 NULL signal 事件将被考虑用于后续实际任务提交。在独立模式下的实际任务提交期间，将要考虑的有效 wait 事件和 signal 事件是应用程序使用 NULL 数据提交设置的事件，以及在该特定任务提交中为 waitEvents 和 signalEvents 字段设置的事件。作为 NULL 数据提交一部分设置的 wait 事件仅被视为第一个任务的依赖项，并且当任务列表中的最后一个任务完成时，作为 NULL 数据提交一部分设置的 signal 事件将发出信号。适用于 waitEvents 和 signalEvents 的所有约束（如下所述）也适用于组合列表。

cuDLA 支持 3 种栅栏 - preFence、SOF 栅栏和 EOF 栅栏。

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

• SOF（帧开始）栅栏是在 DLA 上开始任务执行之前发出信号的栅栏类型。使用 cudlaFenceType 作为 CUDLA_NVSCISYNC_FENCE_SOF 将栅栏标记为 SOF 栅栏。

• EOF（帧结束）栅栏是在 DLA 上完成任务执行后发出信号的栅栏类型。使用 cudlaFenceType 作为 CUDLA_NVSCISYNC_FENCE 将栅栏标记为 EOF 栅栏。

对于 wait 事件，应用程序应

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

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

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

• 在 cudlaWaitEvents 中列出所有栅栏。

对于 signal 事件，应用程序应

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

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

• 将注册的对象和相应的栅栏放置在 cudlaSignalEvents 中。在确定性信号量的情况下，不需要在 cudlaSignalEvents 中传递栅栏。

  当 cudlaSubmitTask 成功返回时，cudlaSignalEvents 中存在的栅栏可用于等待特定任务完成。cuDLA 支持 1 个同步点和任意数量的信号量作为 cudlaSignalEvents 的一部分。如果指定了多个同步点，则返回 cudlaErrorInvalidParam。

cuDLA 遵循 DLA 的限制，每个 DLA 任务支持总共 29 个 preFence 和 SOF 栅栏，以及 29 个 EOF 栅栏。

在提交期间，用户可以选择为网络的各个层启用逐层统计分析。此选项需要通过指定额外的输出缓冲区来实现，这些输出缓冲区将包含分析信息。具体来说，

• “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，并且标志是 CUDLA_SUBMIT_DIAGNOSTICS_TASK。

• 有效的 signal 事件列表具有多个要发出信号的同步点。

• 如果不支持逐层功能。

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

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

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