Star529
642
代码
代码
Issues25
Pull Requests129
Actions
项目讨论
Wiki
分析
Star529
642
cann-robotcann-robotrefactor: 删除 aclrtDim3 统一使用 dim3，新增 SIMT API 参考文档
f8d17335创建于 9 天前历史提交

14. Kernel加载与执行

本章节描述 CANN Runtime 的 Kernel 加载与执行接口，包括二进制加载、函数获取、参数组装及 Kernel 启动。

概念及使用说明

相关概念

本章中的接口涉及对算子的算子二进制、核函数、核函数参数列表以及参数的操作，为便于理解，您可以先通过下图了解它们之间的关系。

  • 算子二进制：编译算子源码，可得到算子二进制文件*.o。对于CANN内置算子，可从算子二进制包（包名为Ascend-cann-*-ops-*.run）中获取算子二进制文件。对于自定义算子，可在编译算子、发布二进制之后获取算子二进制文件。自定义算子的开发、编译请参见《Ascend C算子开发指南》。
  • 核函数：是算子设备侧实现的入口函数。当前允许使用C/C++函数的语法扩展来编写设备端的运行代码，用户在核函数中进行数据访问和计算操作，由此实现该算子的所有功能。

Kernel加载与执行接口调用流程

关键流程说明如下：

  1. 调用aclInit接口初始化。

  2. 申请运行时资源，包括调用aclrtSetDevice接口指定用于运算的Device、调用aclrtCreateStream接口创建Stream。

  3. 调用aclrtBinaryLoadFromFile接口加载算子二进制文件。

    AI CPU算子还支持从内存加载算子二进制数据的方式（调用aclrtBinaryLoadFromData接口），但加载算子二进制数据后，还需配合使用aclrtRegisterCpuFunc接口注册AI CPU算子信息。

  4. 调用aclrtBinaryGetFunctionByEntry或aclrtBinaryGetFunction接口获取核函数句柄。

  5. **（可选）**根据核函数句柄操作其参数列表，操作包括：

    1. 初始化参数列表

      当前支持由系统管理内存（调用aclrtKernelArgsInit接口）、由用户管理内存（调用aclrtKernelArgsInitByUserMem接口）两种方式。

    2. 追加参数、更新参数值

      核函数参数列表中包含不同类型的参数，例如指针类型参数、placeholder、uint8_t类型参数等，其中：

      • 指针类型参数：其值为Device内存地址。一般来说，算子的输入、输出是该种类型的参数，用户需提前调用Device内存申请接口（例如aclrtMalloc接口）申请内存，并自行拷贝数据至Device侧。
      • placeholder：也是指针类型参数，但区别在于，用户无需手动将参数数据复制到Device，这项操作由Runtime完成。在追加参数时Runtime并不会填写真实的Device地址，而是在Launch Kernel时才会刷新为真实的Device地址，所以称之为placeholder。对算子的非输入、输出参数，可以使用placeholder方式，将小块数据（建议小于2KB）的Host->Device拷贝合并到Launch Kernel时的一次拷贝操作中去，减少拷贝次数，提升性能。

      不同类型参数，可调用不同的参数追加接口：

      • 对于placeholder参数，由于关联的内存必须放在所有参数之后，所以在追加参数时，先调用aclrtKernelArgsAppendPlaceHolder接口占位，等所有参数都追加之后，可调用aclrtKernelArgsGetPlaceHolderBuffer接口获取对应占位符指向的内存地址。用户可根据获取的内存地址，管理该内存中的数据。
      • 对于非placeholder参数（例如指针类型参数、uint8_t类型参数等），调用aclrtKernelArgsAppend接口将用户设置的参数值追加拷贝到argsHandle指向的参数数据区域。如果要更新参数值，可调用aclrtKernelArgsParaUpdate接口进行更新。

      注意，核函数参数列表中，实际可能存在多个参数，并且不同类型的参数可能交错出现，因此需要按照参数列表中的参数顺序从左到右进行追加，追加的参数最多支持128个。

    3. 结束参数列表的追加、参数值的更新

      在所有参数追加之后，调用aclrtKernelArgsFinalize接口以标识参数组装完毕。但aclrtKernelArgsFinalize接口之后，也支持继续更新参数值，更新之后，还要再调用一次aclrtKernelArgsFinalize接口。

  6. 调用Launch Kernel接口，启动对应算子的计算任务。

    若使用aclrtArgsHandle参数列表句柄组装核函数的入参数据，则调用aclrtLaunchKernelWithConfig接口启动对应算子的计算任务。该方式下，用户只需按顺序在参数列表中追加参数，无需关注内存中的组装细节，也无需关注内部参数。

    若核函数的入参数据都存放在Host或Device内存中，则调用aclrtLaunchKernel、aclrtLaunchKernelV2或aclrtLaunchKernelWithHostArgs接口启动对应算子的计算任务。

  7. 调用接口aclrtBinaryUnLoad卸载算子二进制文件。

  8. 释放运行时资源，包括调用aclrtDestroyStream接口释放Stream、调用aclrtResetDevice接口释放Device上的资源。

  9. 调用aclFinalize接口去初始化。

aclrtBinaryLoadFromFile

aclError aclrtBinaryLoadFromFile(const char* binPath, aclrtBinaryLoadOptions *options, aclrtBinHandle *binHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

从文件加载并解析算子二进制文件，输出指向算子二进制的binHandle。

对于AI Core算子，若使用本接口加载并解析算子二进制文件，需配套使用aclrtLaunchKernelWithConfig、aclrtLaunchKernelV2或aclrtLaunchKernelWithHostArgs接口下发计算任务。

参数说明

参数名 输入/输出 说明
binPath 输入 算子二进制文件（.o文件）的路径，要求绝对路径。
对于AI CPU算子，该参数支持传算子信息库文件（.json）。
options 输入 加载算子二进制文件的可选参数。类型定义请参见aclrtBinaryLoadOptions。
binHandle 输出 标识算子二进制的句柄。类型定义请参见aclrtBinHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

针对某一型号的产品，编译生成的算子二进制文件，必须在相同型号的产品上使用。




aclrtBinaryLoadFromData

aclError aclrtBinaryLoadFromData(const void *data, size_t length, const aclrtBinaryLoadOptions *options, aclrtBinHandle *binHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

从内存加载并解析算子二进制数据，输出指向算子二进制的binHandle。

调用本接口用于加载AI CPU算子信息（aclrtBinaryLoadOption.type包含ACL_RT_BINARY_LOAD_OPT_CPU_KERNEL_MODE）时，还需配合使用aclrtRegisterCpuFunc接口注册AI CPU算子。

注意，系统仅将算子加载至当前Context所对应的Device上，因此在调用aclrtLaunchKernelWithConfig接口启动算子计算任务时，所在的Device必须与算子加载时的Device相同。

参数说明

参数名 输入/输出 说明
data 输入 存放算子二进制数据的Host内存地址，不能为空。
length 输入 算子二进制数据的内存大小，必须大于0，单位Byte。
options 输入 加载算子二进制文件的可选参数。类型定义请参见aclrtBinaryLoadOptions。
binHandle 输出 标识算子二进制的句柄。类型定义请参见aclrtBinHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtBinaryGetFunction

aclError aclrtBinaryGetFunction(const aclrtBinHandle binHandle, const char *kernelName, aclrtFuncHandle *funcHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据核函数名称，查找到对应的核函数，并使用funcHandle表达。

对于同一个binHandle，首次调用aclrtBinaryGetFunction接口时，会默认将binHandle关联的算子二进制数据拷贝至当前Context对应的Device上。

参数说明

参数名 输入/输出 说明
binHandle 输入 算子二进制句柄。类型定义请参见aclrtBinHandle。
调用aclrtBinaryLoadFromFile接口或aclrtBinaryLoadFromData接口获取算子二进制句柄，再将其作为入参传入本接口。
kernelName 输入 核函数名称。
funcHandle 输出 核函数句柄。类型定义请参见aclrtFuncHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtBinaryGetFunctionByEntry

aclError aclrtBinaryGetFunctionByEntry(aclrtBinHandle binHandle, uint64_t funcEntry, aclrtFuncHandle *funcHandle)

须知：本接口为预留接口，暂不支持。

功能说明

根据Function Entry获取核函数句柄。

对于同一个binHandle，首次调用aclrtBinaryGetFunctionByEntry接口时，会默认将binHandle关联的算子二进制数据拷贝至当前Context对应的Device上。

参数说明

参数名 输入/输出 说明
binHandle 输入 算子二进制句柄。类型定义请参见aclrtBinHandle。
调用aclrtBinaryLoadFromFile接口或aclrtBinaryLoadFromData接口获取算子二进制句柄，再将其作为入参传入本接口。
funcEntry 输入 标识核函数的关键字。
funcHandle 输出 核函数句柄。类型定义请参见aclrtFuncHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtBinaryGetDevAddress

aclError aclrtBinaryGetDevAddress(const aclrtBinHandle binHandle, void **binAddr, size_t *binSize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

获取算子二进制数据在Device上的内存地址及内存大小。

参数说明

参数名 输入/输出 说明
binHandle 输入 算子二进制句柄。类型定义请参见aclrtBinHandle。
调用aclrtBinaryLoadFromFile接口或aclrtBinaryLoadFromData接口获取算子二进制句柄，再将其作为入参传入本接口。
binAddr 输出 算子二进制数据在Device上的内存地址。
如果加载算子二进制时设置了懒加载标识（将aclrtBinaryLoadOptions.aclrtBinaryLoadOption.aclrtBinaryLoadOptionValue.isLazyLoad设置为1），那么调用本接口获取到的binAddr为空指针。
binSize 输出 算子二进制数据的大小，单位Byte。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtBinaryGetGlobal

aclError aclrtBinaryGetGlobal(aclrtBinHandle binHandle, const char *name, void **dptr, size_t *size)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据全局变量名称，获取算子二进制中的全局变量在Device侧的内存地址和大小。

参数说明

参数名 输入/输出 说明
binHandle 输入 算子二进制句柄。类型定义请参见aclrtBinHandle。
调用aclrtBinaryLoadFromFile接口或aclrtBinaryLoadFromData接口获取算子二进制句柄，再将其作为入参传入本接口。
name 输入 全局变量名称。需与算子二进制中定义的全局变量名称一致。
dptr 输出 Device侧全局变量的地址指针。
若此处传nullptr，表示不需要获取地址。
size 输出 Device侧全局变量的大小，单位Byte。
若此处传nullptr，表示不需要获取大小。
dptr和size不能同时为nullptr。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtBinarySetExceptionCallback

aclError aclrtBinarySetExceptionCallback(aclrtBinHandle binHandle, aclrtOpExceptionCallback callback, void *userData)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

调用本接口注册回调函数。若多次设置回调函数，以最后一次设置为准。

在执行算子之前，调用本接口注册回调函数。如果算子执行过程中出现异常，将触发回调函数的执行，并将异常信息存储在aclrtExceptionInfo结构体中。之后，可以通过调用aclrtGetArgsFromExceptionInfo和aclrtGetFuncHandleFromExceptionInfo接口，从异常信息中获取用户下发算子执行任务时的参数以及核函数句柄。目前，支持获取AI Core算子或AICPU算子执行异常时的信息。

参数说明

参数名 输入/输出 说明
binHandle 输入 算子二进制句柄。
调用aclrtBinaryLoadFromFile接口或aclrtBinaryLoadFromData接口获取算子二进制句柄，再将其作为入参传入本接口。
取值详见aclrtBinHandle。
callback 输入 指定要注册的回调函数。
回调函数的函数原型为：
typedef void (aclrtOpExceptionCallback)(aclrtExceptionInfoexceptionInfo, void *userData);
userData 输入 待传递给回调函数的用户数据的指针。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtGetArgsFromExceptionInfo

aclError aclrtGetArgsFromExceptionInfo(const aclrtExceptionInfo *info, void **devArgsPtr, uint32_t *devArgsLen)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

从aclrtExceptionInfo异常信息中获取用户下发算子执行任务时的参数。此接口与aclrtBinarySetExceptionCallback接口配合使用。

参数说明

参数名 输入/输出 说明
info 输入 异常信息的指针。
devArgsPtr 输出 用户下发算子执行任务时的参数。
devArgsLen 输出 参数个数。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtGetFuncHandleFromExceptionInfo

aclError aclrtGetFuncHandleFromExceptionInfo(const aclrtExceptionInfo *info, aclrtFuncHandle *func)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

从aclrtExceptionInfo异常信息中获取核函数句柄。此接口与aclrtBinarySetExceptionCallback接口配合使用。

参数说明

参数名 输入/输出 说明
info 输入 异常信息的指针。
func 输出 核函数句柄。类型定义请参见aclrtFuncHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtGetFunctionAddr

aclError aclrtGetFunctionAddr(aclrtFuncHandle funcHandle, void **aicAddr, void **aivAddr)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据核函数句柄获取Device侧算子起始地址。

不同产品上的AI数据处理核心单元不同，关于Core的定义及详细说明，请参见aclrtDevAttr。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
aicAddr 输出 AI Core或Cube Core上的算子起始地址。

- 对于以下产品，此处返回的是Cube Core上的算子起始地址。Ascend 950PR/Ascend 950DT
Atlas A3 训练系列产品/Atlas A3 推理系列产品
Atlas A2 训练系列产品/Atlas A2 推理系列产品
aivAddr 输出 Vector Core上的算子起始地址。
若通过本接口获取到aivAddr为空，则表示该算子不在Vector Core上执行。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtGetFunctionSize

aclError aclrtGetFunctionSize(aclrtFuncHandle funcHandle, size_t *aicSize, size_t *aivSize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：不支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：不支持
  • IPV350：不支持

功能说明

根据核函数句柄获取核函数代码段的大小。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
aicSize 输出 在AI Core或Cube Core上执行算子的代码段大小，单位Byte。
如果算子仅在Vector Core上执行，则该值为0。
aivSize 输出 在Vector Core上执行算子的代码段大小，单位Byte。
如果算子仅在AI Core或Cube Core上执行，则该值为0。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtGetFunctionName

aclError aclrtGetFunctionName(aclrtFuncHandle funcHandle, uint32_t maxLen, char *name)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据核函数句柄获取核函数名称。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
maxLen 输入 用户申请用于存储核函数名称的最大内存大小，单位Byte。
name 输出 核函数名称。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtGetFunctionAttribute

aclError aclrtGetFunctionAttribute(aclrtFuncHandle funcHandle, aclrtFuncAttribute attrType, int64_t *attrValue)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据核函数句柄获取核函数属性信息。

此接口仅支持查询算子二进制文件中的核函数属性信息。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
attrType 输入 指定属性。类型定义请参见aclrtFuncAttribute。
attrValue 输出 获取属性值。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtGetHardwareSyncAddr

aclError aclrtGetHardwareSyncAddr(void **addr)

产品支持情况

  • Ascend 950PR/Ascend 950DT：不支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：不支持
  • Atlas 推理系列产品：不支持
  • Atlas 训练系列产品：不支持
  • IPV350：不支持

功能说明

获取Cube Core、Vector Core之间的同步地址。

参数说明

参数名 输入/输出 说明
addr 输出 同步地址。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtRegisterCpuFunc

aclError aclrtRegisterCpuFunc(const aclrtBinHandle handle, const char *funcName, const char *kernelName, aclrtFuncHandle *funcHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

若使用aclrtBinaryLoadFromData接口加载AI CPU算子二进制数据，还需配合使用本接口注册AI CPU算子信息，得到对应的funcHandle。

本接口只用于AI CPU算子，其它算子会返回报错ACL_ERROR_RT_PARAM_INVALID。

参数说明

参数名 输入/输出 说明
handle 输入 算子二进制句柄。类型定义请参见aclrtBinHandle。
调用aclrtBinaryLoadFromData接口获取算子二进制句柄，再将其作为入参传入本接口。
funcName 输入 执行AI CPU算子的入口函数。不能为空。
kernelName 输入 AI CPU算子的opType。不能为空。
funcHandle 输出 函数句柄。类型定义请参见aclrtFuncHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsInit

aclError aclrtKernelArgsInit(aclrtFuncHandle funcHandle, aclrtArgsHandle *argsHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据核函数句柄初始化参数列表，并获取标识参数列表的句柄。

与aclrtKernelArgsInitByUserMem接口的区别在于，调用本接口表示由系统管理内存。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
调用aclrtBinaryGetFunctionByEntry或aclrtBinaryGetFunction获取核函数句柄，再将其作为入参传入本接口。
argsHandle 输出 参数列表句柄。类型定义请参见aclrtArgsHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsInitByUserMem

aclError aclrtKernelArgsInitByUserMem(aclrtFuncHandle funcHandle, aclrtArgsHandle argsHandle, void *userHostMem, size_t actualArgsSize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据核函数句柄初始化参数列表，并获取标识参数列表的句柄。

与aclrtKernelArgsInit接口的区别在于，调用本接口表示由用户管理内存。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
调用aclrtBinaryGetFunctionByEntry或aclrtBinaryGetFunction获取核函数句柄，再将其作为入参传入本接口。
argsHandle 输出 参数列表句柄。类型定义请参见aclrtArgsHandle。
需提前调用aclrtKernelArgsGetHandleMemSize接口获取内存大小，申请Host内存，再将Host内存地址作为入参传入此处。
userHostMem 输入 Host内存地址。
需提前调用aclrtKernelArgsGetMemSize接口获取内存大小，申请Host内存，再将Host内存地址作为入参传入此处。
actualArgsSize 输入 内存大小。
需提前调用aclrtKernelArgsGetMemSize接口获取内存大小，再将其作为入参传入此处。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsGetMemSize

aclError aclrtKernelArgsGetMemSize(aclrtFuncHandle funcHandle, size_t userArgsSize, size_t *actualArgsSize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

获取Kernel Launch时参数列表所需内存的实际大小。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
userArgsSize 输入 在内存中存放参数列表数据所需的大小，单位为Byte。
每个参数数据的内存大小都需要8字节对齐，这里的userArgsSize是这些对齐后的参数数据内存大小相加的总和。
actualArgsSize 输出 Kernel Launch时参数列表所需内存的实际大小，单位为Byte。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsGetHandleMemSize

aclError aclrtKernelArgsGetHandleMemSize(aclrtFuncHandle funcHandle, size_t *memSize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

获取参数列表句柄占用的内存大小。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
memSize 输出 参数列表句柄占用的内存大小，单位为Byte。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsAppend

aclError aclrtKernelArgsAppend(aclrtArgsHandle argsHandle, void *param, size_t paramSize, aclrtParamHandle *paramHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

调用本接口将用户设置的参数值追加拷贝到argsHandle指向的参数数据区域。若参数列表中有多个参数，则需按顺序追加参数。

如果要更新参数值，可调用aclrtKernelArgsParaUpdate接口进行更新。

参数说明

参数名 输入/输出 说明
argsHandle 输入 参数列表句柄。类型定义请参见aclrtArgsHandle。
param 输入 待追加参数值的内存地址。
此处为Host内存地址。
paramSize 输入 内存大小，单位Byte。
paramHandle 输出 参数句柄。类型定义请参见aclrtParamHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsAppendPlaceHolder

aclError aclrtKernelArgsAppendPlaceHolder(aclrtArgsHandle argsHandle, aclrtParamHandle *paramHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

对于placeholder参数，调用本接口先占位，返回的是paramHandle占位符。

若参数列表中有多个参数，则需按顺序追加参数。等所有参数都追加之后，可调用aclrtKernelArgsGetPlaceHolderBuffer接口获取paramHandle占位符指向的内存地址。

参数说明

参数名 输入/输出 说明
argsHandle 输入 参数列表句柄。类型定义请参见aclrtArgsHandle。
paramHandle 输出 参数句柄。类型定义请参见aclrtParamHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsGetPlaceHolderBuffer

aclError aclrtKernelArgsGetPlaceHolderBuffer(aclrtArgsHandle argsHandle, aclrtParamHandle paramHandle, size_t dataSize, void **bufferAddr)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据用户指定的内存大小，获取paramHandle占位符指向的内存地址。

参数说明

参数名 输入/输出 说明
argsHandle 输入 参数列表句柄。类型定义请参见aclrtArgsHandle。
paramHandle 输入 参数句柄。类型定义请参见aclrtParamHandle。
此处的paramHandle需与aclrtKernelArgsAppendPlaceHolder接口中的paramHandle保持一致。
dataSize 输入 内存大小。
bufferAddr 输出 paramHandle占位符指向的内存地址。
后续由用户管理该内存中的数据，但无需管理该内存的生命周期。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsParaUpdate

aclError aclrtKernelArgsParaUpdate(aclrtArgsHandle argsHandle, aclrtParamHandle paramHandle, void *param, size_t paramSize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

通过aclrtKernelArgsAppend接口追加的参数，可调用本接口更新参数值。

参数说明

参数名 输入/输出 说明
argsHandle 输入 参数列表句柄。类型定义请参见aclrtArgsHandle。
paramHandle 输入 参数句柄。类型定义请参见aclrtParamHandle。
param 输入 待更新参数值的内存地址。
此处为Host内存地址。
paramSize 输入 内存大小，单位Byte。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtKernelArgsFinalize

aclError aclrtKernelArgsFinalize(aclrtArgsHandle argsHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

在所有参数追加完成后，调用本接口以标识参数组装完毕。

参数说明

参数名 输入/输出 说明
argsHandle 输入 参数列表句柄。类型定义请参见aclrtArgsHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtLaunchKernel

aclError aclrtLaunchKernel(aclrtFuncHandle funcHandle, uint32_t numBlocks, const void *argsData, size_t argsSize, aclrtStream stream)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：支持

功能说明

启动对应算子的计算任务，异步接口。此处的算子为使用Ascend C语言开发的自定义算子。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
调用aclrtBinaryGetFunction接口根据kernelName获取funcHandle。
numBlocks 输入 指定核函数将会在几个核上执行。
argsData 输入 存放核函数所有入参数据的Device内存地址指针。
内存申请接口请参见内存管理。
注意，执行本接口下发任务的Device需与argsData中使用的Device内存要是同一个Device。
argsSize 输入 argsData参数值的大小，单位为Byte。
stream 输入 指定执行任务的Stream。类型定义请参见aclrtStream。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

参考资源

下表的几个接口都用于启用对应算子的计算任务，但功能和使用方式有所不同：

接口 核函数参数值的传入方式 核函数参数值的存放位置 是否可指定任务下发的配置信息
aclrtLaunchKernel 在接口中指定存放核函数所有入参数据的Device内存地址指针 Device内存 否
aclrtLaunchKernelV2 在接口中指定存放核函数所有入参数据的Device内存地址指针 Device内存 是
aclrtLaunchKernelWithConfig 在接口中指定参数列表句柄aclrtArgsHandle Host内存 是
aclrtLaunchKernelWithHostArgs 在接口中指定存放核函数所有入参数据的Host内存地址指针 Host内存 是
aclrtLaunchKernelWithArgsArray 在接口中指定参数数组指针，每个元素指向一个参数数据 Host内存 是
aclrtLaunchSIMTKernelWithArgsArray 用于SIMT核函数，在接口中指定参数数组指针，每个元素指向一个参数数据 Host内存 是
aclrtLaunchSIMTKernelWithHostArgs 用于SIMT核函数，在接口中指定存放核函数所有入参数据的Host内存地址指针 Host内存 是



aclrtLaunchKernelV2

aclError aclrtLaunchKernelV2(aclrtFuncHandle funcHandle, uint32_t numBlocks, const void *argsData, size_t argsSize, aclrtLaunchKernelCfg *cfg, aclrtStream stream)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

指定任务下发的配置信息，并启动对应算子的计算任务。异步接口。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
numBlocks 输入 指定核函数将会在几个核上执行。
argsData 输入 存放核函数所有入参数据的Device内存地址指针。
内存申请接口请参见内存管理。
注意，执行本接口下发任务的Device需与argsData中使用的Device内存要是同一个Device。
argsSize 输入 argsData参数值的大小，单位为Byte。
cfg 输入 任务下发的配置信息。类型定义请参见aclrtLaunchKernelCfg。
不指定配置时，此处可传NULL。
stream 输入 指定执行任务的Stream。类型定义请参见aclrtStream。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

参考资源

各Launch接口的功能和使用方式对比请参见Launch接口对比表。




aclrtLaunchKernelWithConfig

aclError aclrtLaunchKernelWithConfig(aclrtFuncHandle funcHandle, uint32_t numBlocks, aclrtStream stream, aclrtLaunchKernelCfg *cfg, aclrtArgsHandle argsHandle, void *reserve)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

指定任务下发的配置信息，并启动对应算子的计算任务。异步接口。

若使用本接口下发AI Core算子的计算任务，需配套使用aclrtBinaryLoadFromFile接口加载并解析算子二进制文件。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
numBlocks 输入 指定核函数将会在几个核上执行。
stream 输入 指定执行任务的Stream。类型定义请参见aclrtStream。
cfg 输入 任务下发的配置信息。类型定义请参见aclrtLaunchKernelCfg。
不指定配置时，此处可传NULL。
argsHandle 输入 参数列表句柄。类型定义请参见aclrtArgsHandle。
reserve 输入 预留参数。当前固定传NULL。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

参考资源

各Launch接口的功能和使用方式对比请参见Launch接口对比表。




aclrtLaunchKernelWithHostArgs

aclError aclrtLaunchKernelWithHostArgs(aclrtFuncHandle funcHandle, uint32_t numBlocks, aclrtStream stream, aclrtLaunchKernelCfg *cfg, void *hostArgs, size_t argsSize, aclrtPlaceHolderInfo *placeHolderArray, size_t placeHolderNum)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

指定任务下发的配置信息，并启动对应算子的计算任务。异步接口。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
numBlocks 输入 指定核函数将会在几个核上执行。
stream 输入 指定执行任务的Stream。类型定义请参见aclrtStream。
cfg 输入 任务下发的配置信息。类型定义请参见aclrtLaunchKernelCfg。
不指定配置时，此处可传NULL。
hostArgs 输入 存放核函数所有入参数据的Host内存地址指针。
argsSize 输入 hostArgs参数值的大小，单位为Byte。
placeHolderArray 输入 placeholder参数数组。类型定义请参见aclrtPlaceHolderInfo。
placeHolderNum 输入 placeholder参数数组的大小。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

参考资源

各Launch接口的功能和使用方式对比请参见Launch接口对比表。




aclrtLaunchKernelWithArgsArray

aclError aclrtLaunchKernelWithArgsArray(void *func, uint32_t numBlocks, aclrtStream stream, aclrtLaunchKernelCfg *cfg, void **args)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

基于参数数组的方式传递核函数入参，并启动对应算子的计算任务。异步接口。

参数说明

参数名 输入/输出 说明
func 输入 内核函数指针。此处可以是__global__声明的核函数名（比如myKernel），也可以是aclrtFuncHandle类型的核函数句柄。
numBlocks 输入 指定核函数将会在几个核上执行。
stream 输入 指定执行任务的Stream。类型定义请参见aclrtStream。
cfg 输入 任务下发的配置信息。类型定义请参见aclrtLaunchKernelCfg。
不指定配置时，此处可传NULL。
args 输入 参数数组指针。
参数数组中的每个元素均指向核函数参数数据在Host侧的内存地址。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

参数数组中的元素顺序需与核函数参数顺序保持一致，且参数数组大小需与核函数参数数量保持一致，否则会导致未定义行为。

参考资源

各Launch接口的功能和使用方式对比请参见Launch接口对比表。




aclrtCreateBinary

aclrtBinary aclrtCreateBinary(const void *data, size_t dataLen)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

创建aclrtBinary类型的数据，该数据类型用于描述算子二进制信息。此处的算子为使用Ascend C语言开发的自定义算子。

如需销毁aclrtBinary类型的数据，请参见aclrtDestroyBinary。

参数说明

参数名 输入/输出 说明
data 输入 存放算子二进制文件（*.o文件）数据的内存地址指针。
Ascend EP标准形态下，此处需申请Host上的内存；Ascend RC形态或Control CPU开放形态下，此处需申请Device上的内存。
dataLen 输入 内存大小，单位Byte。

返回值说明

返回aclrtBinary类型的指针。

约束说明

Ascend EP标准形态下，data参数处需申请Host上的内存。

Ascend RC形态或Control CPU开放形态下，data参数处需申请Device上的内存。

data参数处需申请Device上的内存。




aclrtDestroyBinary

aclError aclrtDestroyBinary(aclrtBinary binary)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

销毁通过aclrtCreateBinary接口创建的aclrtBinary类型的数据。此处的算子为使用Ascend C语言开发的自定义算子。

注意，此处仅销毁aclrtBinary的数据，调用aclrtCreateBinary接口时传入的data内存需由用户自行、及时释放，否则可能会导致内存异常。

参数说明

参数名 输入/输出 说明
binary 输入 待销毁的aclrtBinary类型的数据。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtBinaryLoad

aclError aclrtBinaryLoad(const aclrtBinary binary, aclrtBinHandle *binHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

解析、加载算子二进制文件，输出指向算子二进制的binHandle，同时将算子二进制文件数据拷贝至当前Context对应的Device上。此处的算子为使用Ascend C语言开发的自定义算子。

参数说明

参数名 输入/输出 说明
binary 输入 算子二进制信息。
此处需先调用aclrtCreateBinary接口，获取aclrtBinary类型数据的指针。
binHandle 输出 指向二进制的handle。类型定义请参见aclrtBinHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtBinaryUnLoad

aclError aclrtBinaryUnLoad(aclrtBinHandle binHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

删除binHandle指向的算子二进制数据，同时也删除加载算子二进制文件时拷贝到Device上的算子二进制数据。

参数说明

参数名 输入/输出 说明
binHandle 输入 算子二进制句柄。类型定义请参见aclrtBinHandle。
该handle在调用aclrtBinaryLoadFromFile、aclrtBinaryLoadFromData或者aclrtBinaryLoad接口时生成。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

调用本接口删除算子二进制数据时，需跟aclrtBinaryLoadFromFile、aclrtBinaryLoadFromData或者aclrtBinaryLoad接口在同一个Context下，这样才能一并删除加载算子二进制文件时拷贝到Device上的算子二进制数据，否则可能会导致Device上的算子二进制数据删除异常。




aclrtFunctionGetBinary

aclError aclrtFunctionGetBinary(const aclrtFuncHandle funcHandle, aclrtBinHandle *binHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据核函数句柄获取算子二进制句柄。

参数说明

参数名 输入/输出 说明
funcHandle 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
binHandle 输出 算子二进制的句柄。类型定义请参见aclrtBinHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtFunctionGetParamCount

aclError aclrtFunctionGetParamCount(const void *func, size_t *paramCount)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

从核函数句柄获取参数个数。

使用本接口查询核函数的参数列表中包含多少个参数后，再配合aclrtFunctionGetParamInfo接口使用，可遍历获取每个参数的详细信息（偏移和大小）。

参数说明

参数名 输入/输出 说明
func 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
paramCount 输出 核函数参数列表中所包含的参数数量。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtFunctionGetParamInfo

aclError aclrtFunctionGetParamInfo(const void *func, size_t paramIndex, size_t *paramOffset, size_t *paramSize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

根据索引从核函数句柄获取参数信息（偏移和大小）。

参数说明

参数名 输入/输出 说明
func 输入 核函数句柄。类型定义请参见aclrtFuncHandle。
paramIndex 输入 参数索引。
可先调用aclrtFunctionGetParamCount接口获取可用的参数数量后，这个paramIndex的取值范围：[0，(参数数量-1)].
paramOffset 输出 参数在参数数据区中的偏移，单位为Byte。
paramSize 输出 参数的大小，单位为Byte。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtFunctionGetAvailDynUbufPerBlock

aclError aclrtFunctionGetAvailDynUbufPerBlock(void *func, uint32_t flags, size_t *dynamicUbufSize)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：支持
  • IPV350：不支持

功能说明

对于SIMT（Single Instruction Multiple Thread）核函数，本接口通过dynamicUbufSize输出Kernel Launch前可设置的最大动态UB buffer大小。

对于非SIMT核函数，本接口返回成功，且dynamicUbufSize固定为0。

参数说明

参数名 输入/输出 说明
func 输入 核函数句柄。类型定义请参见aclrtFuncHandle，不能为空。
flags 输入 预留参数，当前固定配置为0。
dynamicUbufSize 输出 每个Block可用的动态UB buffer大小，单位为Byte，不能为空。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。




aclrtGetFuncBySymbol

aclError aclrtGetFuncBySymbol(const void *symbol, aclrtFuncHandle *funcHandle)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
  • Atlas 200I/500 A2 推理产品：不支持
  • Atlas 推理系列产品：支持
  • Atlas 训练系列产品：不支持
  • IPV350：不支持

功能说明

根据核函数名（__global__声明的函数名，比如myKernel）获取核函数句柄。

本接口仅适用于使用Ascend C语言开发自定义算子并基于毕昇编译器进行Host和Device代码混合编译的场景。不适用于直接加载算子二进制文件的场景。 用户自定义Device侧核函数后，可以通过本接口根据核函数名在内部符号表中查找到对应的核函数，并使用funcHandle表达，用于后续Launch Kernel。

参数说明

参数名 输入/输出 说明
symbol 输入 核函数名。
funcHandle 输出 核函数句柄。类型定义请参见aclrtFuncHandle。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

  • 本接口只能用于算子静态Shape场景，且仅支持AI Core算子。
  • 核函数句柄仅在当前Device有效，切换Device后需要重新获取。



aclrtLaunchSIMTKernelWithArgsArray

aclError aclrtLaunchSIMTKernelWithArgsArray(void *func, dim3 gridDim, dim3 blockDim, size_t dynUbufSize, aclrtStream stream, aclrtLaunchKernelCfg *cfg, void **args)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
  • Atlas 200I/500 A2 推理产品：不支持
  • Atlas 推理系列产品：不支持
  • Atlas 训练系列产品：不支持
  • IPV350：不支持

功能说明

基于参数数组的方式传递SIMT（Single Instruction Multiple Thread）核函数入参，并启动对应算子的计算任务。异步接口。

参数说明

参数名 输入/输出 说明
func 输入 内核函数指针。此处可以是__global__声明的核函数名（比如myKernel），也可以是aclrtFuncHandle类型的核函数句柄。
gridDim 输入 线程块网格，由多个线程块（Thread Block）组成。Grid采用三维结构，其维度X、Y和Z分别表示不同维度下线程块的大小。类型定义请参见dim3。
blockDim 输入 线程块（Thread Block），采用三维结构，其维度X、Y和Z分别表示线程块中三个维度的线程数。类型定义请参见dim3。
dynUbufSize 输入 用于指定SIMT（Single Instruction Multiple Thread）算子执行时需要的UB（Unified Buffer，统一缓冲区）动态内存大小，单位Byte。若cfg中同时设置了ACL_RT_LAUNCH_KERNEL_ATTR_DYN_UBUF_SIZE属性，本参数的优先级更高。
stream 输入 指定执行任务的Stream。类型定义请参见aclrtStream。
cfg 输入 任务下发的配置信息。类型定义请参见aclrtLaunchKernelCfg。
不指定配置时，此处可传NULL。
args 输入 参数数组指针。
参数数组中的每个元素均指向核函数参数数据在Host侧的内存地址。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

参数数组中的元素顺序需与核函数参数顺序保持一致，且参数数组大小需与核函数参数数量保持一致，否则会导致未定义行为。

参考资源

各Launch接口的功能和使用方式对比请参见Launch接口对比表。




aclrtLaunchSIMTKernelWithHostArgs

aclError aclrtLaunchSIMTKernelWithHostArgs(void *func, dim3 gridDim, dim3 blockDim, size_t dynUbufSize, aclrtStream stream, aclrtLaunchKernelCfg *cfg, void *hostArgs, size_t argsSize, aclrtPlaceHolderInfo *placeHolderArray, size_t placeHolderNum)

产品支持情况

  • Ascend 950PR/Ascend 950DT：支持
  • Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
  • Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
  • Atlas 200I/500 A2 推理产品：不支持
  • Atlas 推理系列产品：不支持
  • Atlas 训练系列产品：不支持
  • IPV350：不支持

功能说明

基于Host内存参数的方式传递SIMT（Single Instruction Multiple Thread）核函数入参，并启动对应算子的计算任务。异步接口。

参数说明

参数名 输入/输出 说明
func 输入 内核函数指针。此处可以是__global__声明的核函数名（比如myKernel），也可以是aclrtFuncHandle类型的核函数句柄。
gridDim 输入 线程块网格，由多个线程块（Thread Block）组成。Grid采用三维结构，其维度X、Y和Z分别表示不同维度下线程块的大小。类型定义请参见dim3。
blockDim 输入 线程块（Thread Block），采用三维结构，其维度X、Y和Z分别表示线程块中三个维度的线程数。类型定义请参见dim3。
dynUbufSize 输入 用于指定SIMT（Single Instruction Multiple Thread）算子执行时需要的UB（Unified Buffer，统一缓冲区）动态内存大小，单位Byte。若cfg中同时设置了ACL_RT_LAUNCH_KERNEL_ATTR_DYN_UBUF_SIZE属性，本参数的优先级更高。
stream 输入 指定执行任务的Stream。类型定义请参见aclrtStream。
cfg 输入 任务下发的配置信息。类型定义请参见aclrtLaunchKernelCfg。
不指定配置时，此处可传NULL。
hostArgs 输入 存放核函数所有入参数据的Host内存地址指针。
argsSize 输入 hostArgs参数值的大小，单位为Byte。
placeHolderArray 输入 placeholder参数数组。类型定义请参见aclrtPlaceHolderInfo。
placeHolderNum 输入 placeholder参数数组的大小。

返回值说明

返回0表示成功，返回其他值表示失败，请参见aclError。

约束说明

  • hostArgs内存需按核函数参数顺序紧凑排列，且argsSize需与实际参数总大小一致。
  • placeHolderArray中的地址偏移必须与hostArgs中placeholder参数的实际位置对应。

参考资源

各Launch接口的功能和使用方式对比请参见Launch接口对比表。