当前位置： 首页 > news >正文

cann/runtime其他接口API文档

news 2026/5/9 12:40:34

24. 其他接口

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

本章节描述 CANN Runtime 的其他辅助接口，包括版本查询、数据类型转换等。

  • size_t aclDataTypeSize(aclDataType dataType)：获取aclDataType数据的大小，单位Byte。
  • float aclFloat16ToFloat(aclFloat16 value)：将aclFloat16类型的数据转换为float（指float32）类型的数据。
  • aclFloat16 aclFloatToFloat16(float value)：将float（指float32）类型的数据转换为aclFloat16类型的数据。
  • aclError aclrtGetVersion(int32_t *majorVersion, int32_t *minorVersion, int32_t *patchVersion)：查询接口版本号，acl接口版本号命名采用：A.B.C模式，其中，A表示有不兼容修改，B表示新增接口，C表示bug修复。
  • aclError aclsysGetCANNVersion(aclCANNPackageName name, aclCANNPackageVersion *version)：查询CANN软件包版本号。
  • aclError aclGetCannAttributeList(const aclCannAttr **cannAttrList, size_t *num)：查询运行环境中CANN软件和对应AI处理器支持的特性列表。
  • aclError aclGetCannAttribute(aclCannAttr cannAttr, int32_t *value)：查询运行环境是否支持指定的CANN特性。
  • aclError aclGetDeviceCapability(uint32_t deviceId, aclDeviceInfo deviceInfo, int64_t *value)：查询运行环境中对应Device的硬件规格大小。
  • aclError aclrtCacheLastTaskOpInfo(const void * const infoPtr, const size_t infoSize)：基于捕获方式构建模型运行实例场景下，把指定内存中的算子信息按照infoSize大小缓存到当前线程中最后下发的任务上。
  • aclError aclrtCacheLastTaskExtendInfo(const char* const extendInfoPtr, const size_t infoSize)：将指定内存中的自定义扩展信息按照infoSize大小缓存到当前线程中最后下发的任务上。
  • aclError aclrtProfTrace(void *userdata, int32_t length, aclrtStream stream)：支持用户在网络指定位置下发自定义的Profiling打点。异步接口。
  • aclError aclsysGetVersionNum(char *pkgName, int32_t *versionNum)：根据软件包名称查询版本号，版本号是数值类型，通过计算各包安装目录下version.info文件中的version字段的主、次、补丁等版本信息的权重得出。
  • aclError aclsysGetVersionStr(char *pkgName, char *versionStr)：根据软件包名称查询版本号，版本号是字符串类型，与各包安装目录下version.info文件中的version保持一致。

aclDataTypeSize

size_t aclDataTypeSize(aclDataType dataType)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

获取aclDataType数据的大小，单位Byte。

参数说明

参数名输入/输出说明
dataType输入指定要获取大小的aclDataType数据。类型定义请参见aclDataType。

返回值说明

返回aclDataType数据的大小，单位Byte。




aclFloat16ToFloat

float aclFloat16ToFloat(aclFloat16 value)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

将aclFloat16类型的数据转换为float（指float32）类型的数据。

参数说明

参数名输入/输出说明
value输入待转换的数据。类型定义请参见aclFloat16。

返回值说明

转换后的数据。




aclFloatToFloat16

aclFloat16 aclFloatToFloat16(float value)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

将float（指float32）类型的数据转换为aclFloat16类型的数据。

参数说明

参数名输入/输出说明
value输入待转换的数据。

返回值说明

转换后的数据。

注意，由于C语言无float16类型，此处返回值使用uint16_t对数据进行存储。若用户需要打印，需自行将uint16_t解释成float16进行打印，或者转成float进行打印。




aclrtGetVersion

aclError aclrtGetVersion(int32_t *majorVersion, int32_t *minorVersion, int32_t *patchVersion)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

查询接口版本号，acl接口版本号命名采用：A.B.C模式，其中，A表示有不兼容修改，B表示新增接口，C表示bug修复。

参数说明

参数名输入/输出说明
majorVersion输出主版本号的指针，从1开始，如果出现接口的不兼容变更时，加1。
minorVersion输出次版本号的指针，从0开始，按照迭代周期，有新增接口时加1。
patchVersion输出补丁版本号的指针，从0开始，表示本版本仅解决了问题。
在majorVersion、minorVersion不变的情况下加1；但majorVersion、minorVersion增加的时候，patchVersion一般为0。

返回值说明

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




aclsysGetCANNVersion（废弃）

aclError aclsysGetCANNVersion(aclCANNPackageName name, aclCANNPackageVersion *version)

须知：此接口后续版本会废弃，请使用aclsysGetVersionStr、aclsysGetVersionNum接口。

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

查询CANN软件包版本号。

参数说明

参数名输入/输出说明
name输入指定要查询的软件包。类型定义请参见aclCANNPackageName。
若指定要查询的软件包没有安装，则本接口返回报错。
version输出CANN软件包版本号。类型定义请参见aclCANNPackageVersion。

返回值说明

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




aclGetCannAttributeList

aclError aclGetCannAttributeList(const aclCannAttr **cannAttrList, size_t *num)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

查询运行环境中CANN软件和对应AI处理器支持的特性列表。

参数说明

参数名输入/输出说明
cannAttrList输出用于保存运行环境支持的特性枚举数组。类型定义请参见aclCannAttr。
用户无需提前申请内存，应用进程退出时，内存自动释放。
num输出用于保存支持的特性数量，与cannAttrList数组长度保持一致。

返回值说明

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




aclGetCannAttribute

aclError aclGetCannAttribute(aclCannAttr cannAttr, int32_t *value)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

查询运行环境是否支持指定的CANN特性。

参数说明

参数名输入/输出说明
cannAttr输入特性列表枚举值，一次查询可指定其中一项。类型定义请参见aclCannAttr。
value输出是否支持：

- 1：支持
- 0：不支持

返回值说明

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




aclGetDeviceCapability

aclError aclGetDeviceCapability(uint32_t deviceId, aclDeviceInfo deviceInfo, int64_t *value)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

查询运行环境中对应Device的硬件规格大小。

参数说明

参数名输入/输出说明
deviceId输入Device ID。
用户调用aclrtGetDeviceCount接口获取可用的Device数量后，这个Device ID的取值范围：[0, (可用的Device数量-1)]
deviceInfo输入指定Device上的硬件规格类型。类型定义请参见aclDeviceInfo。
value输出硬件规格值。

返回值说明

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




aclrtCacheLastTaskOpInfo

aclError aclrtCacheLastTaskOpInfo(const void * const infoPtr, const size_t infoSize)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

基于捕获方式构建模型运行实例场景下，把指定内存中的算子信息按照infoSize大小缓存到当前线程中最后下发的任务上。

参数说明

参数名输入/输出说明
infoPtr输入缓存信息内存地址指针，此处是Host内存
infoSize输入缓存信息内存大小，取值范围：(0, 64K]，单位Byte。

返回值说明

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

接口调用流程

本接口需与以下其它关键接口配合使用，以便控制后续采集性能数据时附带算子信息：

  1. 调用aclmdlRICaptureBegin接口开始捕获任务。

  2. 调用aclrtSetStreamAttribute接口开启算子信息缓存开关。

  3. 下发算子执行任务，例如调用aclrtLaunchKernelWithConfig接口。

  4. 调用aclrtGetStreamAttribute接口获取算子信息缓存开关是否开启。

    只有在捕获状态下，且通过aclrtSetStreamAttribute接口开启了算子信息缓存开关，此处的aclrtGetStreamAttribute接口才能获取到算子信息缓存开关已开启的状态，后续才可以缓存算子信息。

  5. 调用aclrtCacheLastTaskOpInfo接口缓存算子信息。

  6. 再次调用aclrtSetStreamAttribute接口关闭算子信息缓存开关。

  7. 调用aclmdlRICaptureEnd接口结束任务捕获。

  8. 开启采集性能数据（参见Profiling数据采集接口章节下的接口）后，调用aclmdlRIExecuteAsync接口执行推理。

    在此过程中，采集的性能数据会附带算子信息。

  9. 最后，调用aclmdlRIDestroy接口销毁模型运行实例时，算子缓存信息也会被一并释放。




aclrtCacheLastTaskExtendInfo

aclError aclrtCacheLastTaskExtendInfo(const char* const extendInfoPtr, const size_t infoSize)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

将指定内存中的自定义扩展信息按照infoSize大小缓存到当前线程中最后下发的任务上。后续可以通过调用aclmdlRIDebugJsonPrint接口将自定义扩展信息以JSON格式导出到文件中，然后，通过tracing方式（例如chrome://tracing/）查看。 当前仅支持在捕获模型（请参见aclmdlRICaptureBegin接口）或构建模型运行实例（请参见aclmdlRIBuildBegin接口）的场景下使用。

参数说明

参数名输入/输出说明
extendInfoPtr输入指向自定义扩展信息内存地址的指针，此处是Host内存。extendInfoPtr指向的内存中的内容应为使用UTF-8编码的JSON格式字符串。非UTF-8编码的JSON格式字符串在后续调用aclmdlRIDebugJsonPrint接口时可能导致未定义的行为。
infoSize输入自定义扩展信息内存大小，单位Byte。取值范围：(0, 4K]，当infoSize大于4K时，仅缓存前4K字节。

返回值说明

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




aclrtProfTrace

aclError aclrtProfTrace(void *userdata, int32_t length, aclrtStream stream)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

支持用户在网络指定位置下发自定义的Profiling打点。异步接口。

参数说明

参数名输入/输出说明
userdata输入自定义信息。
length输入userdata的长度，单位Byte。
length建议配置为18字节；如果未满18字节，将会自动在数据末尾补0到18字节；如果超过18字节，接口会校验报错返回。
stream输入指定执行打点任务的Stream。类型定义请参见aclrtStream。

返回值说明

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




aclsysGetVersionNum

aclError aclsysGetVersionNum(char *pkgName, int32_t *versionNum)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

根据软件包名称查询版本号，版本号是数值类型，通过计算各包安装目录下version.info文件中的version字段的主、次、补丁等版本信息的权重得出。

获取数值类型的版本号并进行比较，数值较大的表示版本发布时间较新，可用于了解版本发布的先后顺序，以及在代码中根据版本区分不同的接口调用逻辑等。

参数说明

参数名输入/输出说明
pkgName输入软件包名称。
CANN包名称与${INSTALL_DIR}/share/info下的目录名称保持一致。${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。
驱动包名称为driver。
固件包名称为firmware。
versionNum输出数值类型的版本号。

返回值说明

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




aclsysGetVersionStr

aclError aclsysGetVersionStr(char *pkgName, char *versionStr)

产品支持情况

产品是否支持
Ascend 950PR/Ascend 950DT√
Atlas A3 训练系列产品/Atlas A3 推理系列产品√
Atlas A2 训练系列产品/Atlas A2 推理系列产品√

功能说明

根据软件包名称查询版本号，版本号是字符串类型，与各包安装目录下version.info文件中的version保持一致。

参数说明

参数名输入/输出说明
pkgName输入软件包名称。
CANN包名称与${INSTALL_DIR}/share/info下的目录名称保持一致。${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。
驱动包名称为driver。
固件包名称为firmware。
versionStr输出版本号。
建议用户声明一个长度为ACL_PKG_VERSION_MAX_SIZE的字符数组，用于存放版本号。例如：char versionStr[ACL_PKG_VERSION_MAX_SIZE] = {0};
ACL_PKG_VERSION_MAX_SIZE宏的定义如下：
#define ACL_PKG_VERSION_MAX_SIZE 128

返回值说明

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

【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

http://www.jsqmd.com/news/782937/

相关文章：

  • 顶会论文模块复现与二次创新：二次创新：将 DETR 的查询式检测头蒸馏进 YOLOv11，打造混合式 Anchor-free 头
  • 模型诊断：从冲突集到命中集，构建高效故障定位系统
  • CANN/catlass Gemm/Block类模板概述
  • DeepEP V2 为什么值得做 MoE 的团队现在就关注？真正先拖慢吞吐的，不是专家数，而是 EP 通信还在抢 SM
  • 如何高效实现魔兽争霸3现代化兼容？WarcraftHelper实战指南
  • CANN/driver容器共享配置查询
  • CANN/cannbot-skills 模型审查专家代理
  • GD32中的DMA使用教程
  • HCOMM通信算子NPU环境测试
  • Kemptide (Phosphate Acceptor Peptide)；LRRASLG
  • 【算法】小白也能懂 · 第 2 节：数组双指针技巧（快慢指针、左右指针）
  • CANN/atvoss向量算子库概述
  • 别再盲目自学 CTF！零基础专属入门完整路线，看完直接上手实战
  • 面向对象设计原则在Java开发中的应用
  • CANN/metadef GetAddr函数API文档
  • 可解释AI在膝骨关节炎诊断中的应用：从黑盒模型到临床可信赖的决策伙伴
  • 医疗生成式AI的伦理治理：GREAT PLEA框架下的公平、可靠与问责实践
  • CANN/tensorflow AOE调优配置
  • CANN/asc-devkit AllocTensor API
  • 遥感图像分类可解释AI方法：定量评估与工程实践指南
  • 显卡驱动冲突终极解决方案：Display Driver Uninstaller深度使用指南
  • 第8天：常用数据结构之列表
  • AI安全新范式：从红蓝对抗到紫队协同的实战指南
  • 3个核心功能让你轻松掌握QtScrcpy：免费开源的Android投屏控制终极指南
  • 毕业论文查重网站终极横评：知网/维普/PaperPass/PaperYY谁最准？
  • CANN/pypto RMS归一化API文档
  • 马斯克投1200亿建芯片工厂，微美全息加速量子算力集群进入全球“AI军备竞赛”
  • CANN/hcomm组调用结束接口
  • 图形处理器——从显示到计算的蜕变
  • RAP中的派生变量%说明