CANN Runtime API 概述接口分类、头文件与库文件、同步机制及废弃接口迁移指南【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtimeCANNCompute Architecture for Neural NetworksRuntime 是昇腾 AI 处理器的运行时软件栈核心负责设备管理、Stream 管理、内存管理、Kernel 加载与执行、数据传输等底层能力。本文基于 docs/zh/api_ref/01_overview.md 整理 CANN Runtime API 的整体脉络如何识别各类 acl 接口、编译链接时依赖哪些头文件与动态库、同步与异步接口的正确使用方式以及各版本标记废弃的接口、返回码与枚举的替代方案。读完本文你将能正确配置开发环境、写出符合规范且可平滑升级的 Runtime 应用程序。一、CANN Runtime API 的基本概念与接口分类CANN Runtime API 采用统一的命名风格接口名以acl作为前缀格式为acl 接口类别缩写 操作动词与对象其中操作动词和对象均采用首字母大写。下文为描述方便统称为acl 接口。根据接口前缀的不同acl 接口划分为以下关键类别表 1关键接口类别接口名前缀描述acl基础接口包括初始化去初始化、日志、数据类型转换等。aclrt运行时管理类的接口包括设备管理、Stream管理、内存管理、Kernel加载与执行等。aclmdlRI模型运行实例管理接口。acltdt数据传输接口。aclmdlaclop模型和算子数据Dump接口。aclprofProfiling数据采集接口。acllog日志回调接口用于用户自定义模块记录日志。在仓库的 include/external/acl 目录中可以看到与此分类一一对应的头文件例如 acl_rt.h运行时管理、acl_tdt.h数据传输、acl_dump.hDump、acl_prof.hProfiling。这些头文件是用户在编写应用程序时直接引用的公共 API 定义而具体的实现则分布在仓库的 src/runtime 与 src/acl 等目录中。二、编译链接依赖的头文件与库文件说明安装固件、驱动及 CANN 软件包后编译、运行应用程序时才能引用到 acl 接口的头文件与库文件。acl 接口的头文件位于${INSTALL_DIR}/include/目录下库文件位于${INSTALL_DIR}/lib64/目录下。其中${INSTALL_DIR}为 CANN 软件安装后的文件存储路径以 root 用户安装为例默认存储路径为/usr/local/Ascend/cann。须知编译 acl 接口程序时请按照 include 的头文件依赖对应的库文件。如果引用多余的库文件例如libascendcl.a可能导致版本功能异常或后续版本升级时存在兼容性问题。表 2头文件列表定义接口的头文件用途对应的库文件acl/acl_rt.h用于定义初始化/去初始化、Device管理、Context管理、Stream管理、同步等待、内存管理等接口。libacl_rt.so说明为了兼容旧版本旧版本中支持使用libascendcl.so但后续版本这种方式会废弃建议使用libacl_rt.so防止后续版本出现兼容性问题。acl/acl_rt_api.h用于定义 C 扩展接口提供函数重载和模板封装仅适用于 C 程序。依赖 acl_rt.h。libacl_rt.soacl/acl_dump.h用于定义模型和算子Dump接口。libascend_dump.soacl/acl_prof.h用于定义Profiling数据采集接口。libmsprofiler.so说明为了兼容旧版本旧版本中支持使用libascendcl.so但后续版本这种方式会废弃建议使用libmsprofiler.so防止后续版本出现兼容性问题。base/acl_log.h用于定义日志回调接口支持用户自定义模块记录日志。libascendalog.soacl/acl_tdt.h用于定义Tensor数据传输接口。libacl_tdt_channel.soacl/acl_tdt_queue.h用于定义共享队列管理、共享Buffer管理接口。libacl_tdt_queue.so从源码构建层面可以印证各库文件的产出关系仓库中 src/acl/aclrt/CMakeLists.txt 标注了libacl_rt.so的构建目标src/acl/acl_tdt_channel/CMakeLists.txt 标注了libacl_tdt_channel.so的构建目标说明头文件与库文件在工程上是一一对应的模块产物。此外库文件与头文件的对应关系也在 src/acl 目录下的模块划分中体现如 acl_tdt_queue 对应共享队列与共享 Buffer 管理。在具体编程实践中你可以参考仓库 example 目录下的示例工程。例如快速入门示例 example/0_quickstart/0_hello_cann/main.cpp 展示了aclInit(NULL)等基础接口的调用方式example/0_quickstart/0_hello_cann/CMakeLists.txt 则展示了如何在 CMake 工程中链接所需的 acl 库。三、接口与参数的状态标识约定阅读本文档时会看到“支持”、“不支持”、“试验”、“预留”、“废弃”等接口或参数状态标识其含义约定如下支持表示支持某接口或参数。不支持表示不支持某接口或参数若使用该接口或参数将产生未定义行为例如接口返回报错、后续业务功能异常。预留表示接口或参数预留当前暂未实现或功能不完善不支持调用后续版本可能开放。试验表示接口或参数处于试验阶段接口定义、行为可能发生变更不建议应用于生产环境中。废弃后续版本待删除建议使用文档中的替换接口或参数。这一约定与头文件中的实际标注保持一致。例如 include/external/acl/acl_base_rt.h 中同时定义了ACL_ERROR_NONE已废弃与ACL_SUCCESS并给出deprecated注释include/external/acl/acl_rt.h 中aclrtSetExceptionInfoCallback同样以ACL_DEPRECATED_MESSAGE宏标注废弃并指向替代接口。四、同步与异步 API 说明4.1 显式同步接口CANN 支持以下几类显式同步调用此类接口后主机Host线程会阻塞直到相关的任务执行完成。设备同步例如aclrtSynchronizeDevice阻塞当前主机线程直到 Device 上所有显式或隐式创建的 Stream 都完成所有先前下发的任务。应尽量少使用该函数以免拖延主机运行。该接口的声明位于 include/external/acl/acl_rt.h与之配套的还有带超时能力的aclrtSynchronizeDeviceWithTimeout(int32_t timeout)。流同步例如aclrtSynchronizeStream阻塞当前主机线程直到指定的 Stream 中完成所有下发的任务。aclrtSynchronizeStream的声明位于 include/external/acl/acl_rt.h同样提供aclrtSynchronizeStreamWithTimeout变体。它比设备同步粒度更细是日常编程中最常用的同步手段。事件同步例如aclrtSynchronizeEvent阻塞当前主机线程直到指定的 Event 事件完成属于更细粒度的同步。aclrtSynchronizeEvent的声明位于 include/external/acl/acl_rt.h配套提供aclrtSynchronizeEventWithTimeout。Event 还可以通过aclrtStreamWaitEvent实现 Stream 之间的等待关系详见 07_event_management.md。4.2 异步接口的正确使用对于异步接口主机线程调用异步接口后仅代表下发任务不代表任务执行成功在任务未完成前异步接口已向主机线程返回成功。用户需要显式调用以上同步接口阻塞主机线程、等待任务完成否则可能会导致训练或推理等业务异常、Device 断链掉卡等未知情况。典型的正确写法是“异步下发 显式同步”的组合先通过aclrtMemcpyAsync、aclrtLaunchKernel等异步接口下发任务再按需调用aclrtSynchronizeEvent、aclrtSynchronizeStream或aclrtSynchronizeDevice等待任务完成。仓库示例中大量使用这一模式例如 example/1_basic_features/memory/4_d2h_async_memory_copy、example/2_advanced_features/kernel/0_launch_kernel 等目录下的示例代码。更多关于 Stream 与 Event 同步机制的选择与区别可参考 docs/zh/FAQ/Stream同步与Event同步的区别与选择.md。五、废弃接口与返回码列表为便于版本演进以下接口、返回码与枚举已在指定版本标记为废弃请按表格中的替换方案及时迁移。本文档所列信息以 include/external/acl 下的头文件标注ACL_DEPRECATED_MESSAGE宏与deprecated注释为源码级佐证。5.1 废弃接口aclGetDataBufferSize在 CANN 8.5.0 版本标记为废弃将在 2026年12月30日 之后的版本删除替换为 aclGetDataBufferSizeV2。头文件中该接口声明于 include/external/acl/acl_base_rt.haclGetDataBufferSizeV2的返回值类型为size_t。aclrtQueryEvent在 CANN 8.5.0 版本标记为废弃将在 2026年12月30日 之后的版本删除替换为 aclrtQueryEventStatus。新接口通过aclrtEventRecordedStatus*输出参数返回事件记录状态声明见 include/external/acl/acl_rt.h。aclrtGetVersion在 CANN 9.2.0 版本标记为废弃将在 2027年9月30日 之后的版本删除替换为 aclsysGetVersionNum 或 aclsysGetVersionStr。aclsysGetVersionNum(char* pkgName, int32_t* versionNum)返回数值型版本号aclsysGetVersionStr(char* pkgName, char* versionStr)返回字符串型版本号二者均声明于 include/external/acl/acl_rt.h。aclrtMemcpyAsyncWithCondition在 CANN 9.2.0 版本标记为废弃将在 2027年9月30日 之后的版本删除替换为 aclrtMemcpyAsync。aclrtSetExceptionInfoCallback在 CANN 9.2.0 版本标记为废弃将在 2027年9月30日 之后的版本删除替换为 aclrtExceptionInfoCallbackRegister 与 aclrtExceptionInfoCallbackUnregister 两个接口。头文件中的迁移提示见 include/external/acl/acl_rt.h。aclsysGetCANNVersion在 CANN 8.5.0 版本标记为废弃将在 2026年12月30日 之后的版本删除替换为 aclsysGetVersionStr 或 aclsysGetVersionNum。头文件中的废弃标注见 include/external/acl/acl_rt.h。aclmdlRIDebugPrint在 CANN 8.5.0 版本标记为废弃将在 2026年12月30日 之后的版本删除替换为 aclmdlRIDebugJsonPrint。5.2 废弃返回码以下返回码在 CANN 8.5.0 版本标记为废弃将在 2026年12月30日 之后的版本删除。各返回码的完整语义定义可参考 25-01_aclError.md。废弃返回码替换返回码ACL_ERROR_NONEACL_SUCCESSACL_ERROR_NOT_STATIC_AIPPACL_ERROR_GE_AIPP_NOT_EXISTACL_ERROR_STREAM_NOT_SUBSCRIBEACL_ERROR_RT_STREAM_NO_CB_REGACL_ERROR_THREAD_NOT_SUBSCRIBEACL_ERROR_RT_THREAD_SUBSCRIBEACL_ERROR_WAIT_CALLBACK_TIMEOUTACL_ERROR_RT_REPORT_TIMEOUTACL_ERROR_INVALID_DEVICEACL_ERROR_RT_INVALID_DEVICEIDACL_ERROR_GROUP_NOT_SETACL_ERROR_RT_GROUP_NOT_SETACL_ERROR_GROUP_NOT_CREATEACL_ERROR_RT_GROUP_NOT_CREATE以最常用的返回码为例include/external/acl/acl_base_rt.h 中同时保留ACL_ERROR_NONE与ACL_SUCCESS两个定义值均为 0并注明ACL_ERROR_NONE自 8.5.0 起废弃、2026/12/30 后移除新代码应统一使用ACL_SUCCESS。5.3 废弃枚举与结构体成员aclSysParamOpt 枚举见 25-02_Enumerations.mdACL_OPT_STRONG_CONSISTENCY枚举项在 CANN 9.2.0 版本标记为废弃将在 2027年9月30日 之后的版本删除替换为ACL_OPT_DETERMINISTIC枚举项配置值设为2。aclrtLaunchKernelAttrId 枚举见 25-02_Enumerations.mdACL_RT_LAUNCH_KERNEL_ATTR_LOCAL_MEMORY_SIZE枚举项在 CANN 9.0.0 版本标记为废弃将在 2027年3月30日 之后的版本删除替换为ACL_RT_LAUNCH_KERNEL_ATTR_DYN_UBUF_SIZE枚举项。头文件 include/external/acl/acl_rt.h 中两个枚举项的值同为 2并带有DEPRECATED注释。aclrtDevAttr 枚举见 25-02_Enumerations.mdACL_DEV_ATTR_LOCAL_MEM_PER_VECTOR_CORE在 CANN 9.0.0 版本标记为废弃将在 2027年3月30日 之后的版本删除替换为ACL_DEV_ATTR_UBUF_PER_VECTOR_CORE。ACL_DEV_ATTR_SUPER_POD_DEVIDE_ID注意旧拼写DEVIDE在 CANN 9.0.0 版本标记为废弃将在 2027年3月30日 之后的版本删除替换为拼写修正后的ACL_DEV_ATTR_SUPER_POD_DEVICE_ID。头文件 include/external/acl/acl_rt.h 中二者共用枚举值403U。aclrtAtomicOperationCapability 枚举见 25-02_Enumerations.mdACL_RT_ATOMIC_CAPABILITY_REDUCATION在 CANN 9.2.0 版本标记为废弃将在 2027年9月30日 之后的版本删除替换为拼写修正后的ACL_RT_ATOMIC_CAPABILITY_REDUCTION。头文件 include/external/acl/acl_rt.h 中二者值均为1U 2。aclrtBinaryLoadOptionType 枚举见 25-02_Enumerations.mdACL_RT_BINARY_LOAD_OPT_LAZY_MAGIC在 CANN 8.5.0 版本标记为废弃将在 2026年12月30日 之后的版本删除替换为ACL_RT_BINARY_LOAD_OPT_MAGIC。aclrtLaunchKernelAttrValue 联合体见 25-04_Structs.mdlocalMemorySize成员在 CANN 9.0.0 版本标记为废弃将在 2027年3月30日 之后的版本删除替换为dynUBufSize成员。六、迁移建议与开发要点按表核对链接库新建工程时严格对照 表 2 选择头文件与库文件避免引用libascendcl.so等已进入废弃通道的旧库防止后续升级出现兼容性问题。统一返回码判断新代码统一使用ACL_SUCCESS判断接口执行结果避免在旧返回码移除后产生编译或运行问题。关注废弃时间线当前仓库头文件中的废弃时间点分为 2026年12月30日 与 2027年3月30日、2027年9月30日 两批建议在对应版本发布前完成迁移。同步与异步搭配使用异步接口只负责下发任务务必配合显式同步接口设备同步 / 流同步 / 事件同步使用这是避免业务异常与 Device 掉链的基本要求。善用仓库示例example 目录提供了覆盖快速入门、基础特性、高级特性、内存进阶、可靠性、性能、典型场景等维度的完整示例工程可作为接口用法的权威参考各章节的详细 API 说明可继续查阅 docs/zh/api_ref 目录下的对应文档如 07_event_management.md、11-03_memory_copy_and_set.md、13_exception_handling.md 等。【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考