Star0
0
代码
代码
Issues
Pull Requests
Actions
项目讨论
Wiki
分析
Star0
0
cann-robotcann-robot【PR】: docs/zh目录下统一修改产品名称，并将现有中文md文件名和png图片名修改为英文名
f27ca703创建于 11 天前历史提交

1. 概述

本章节介绍 CANN Runtime API 的基本概念、头文件与库文件说明、同步/异步接口说明及废弃接口列表。

头文件和库文件说明

接口分类

通常接口名以acl作为前缀，命名风格为：acl+接口类别缩写+*，其中，*表示操作动词和对象，均采用首字母大写。下文为了描述方便，将本文中的接口统称为acl接口。

表 1 关键接口类别

接口名前缀 描述
acl 基础接口，包括初始化&去初始化、日志、数据类型转换等。
aclrt 运行时管理类的接口，包括设备管理、Stream管理、内存管理、Kernel加载与执行等。
aclmdlRI 模型运行实例管理接口。
acltdt 数据传输接口。
aclmdl&aclop 模型和算子数据Dump接口。
aclprof Profiling数据采集接口。
acllog 日志回调接口，用于用户自定义模块记录日志。

调用接口依赖的头文件和库文件说明

安装固件、驱动及CANN软件包后，编译、运行应用程序时才能引用到acl接口的头文件、库文件。

您需要根据实际使用的acl接口来include依赖的文件，各头文件的用途如下表所示。

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.so
acl/acl_dump.h 用于定义模型和算子Dump接口。 libascend_dump.so
acl/acl_prof.h 用于定义Profiling数据采集接口。 libmsprofiler.so
说明：为了兼容旧版本，旧版本中支持使用libascendcl.so，但后续版本这种方式会废弃，建议使用libmsprofiler.so，防止后续版本出现兼容性问题。
base/acl_log.h 用于定义日志回调接口，支持用户自定义模块记录日志。 libascendalog.so
acl/acl_tdt.h 用于定义Tensor数据传输接口。 libacl_tdt_channel.so
acl/acl_tdt_queue.h 用于定义共享队列管理、共享Buffer管理接口。 libacl_tdt_queue.so

表达约定

本文档中存在“支持”、“不支持”、“试验”、“预留”、“废弃”等接口或参数状态的标识，这类标识的含义如下：

  • “支持”：表示支持某接口或参数。

  • “不支持”：表示不支持某接口或参数，若使用该接口或参数，将产生未定义行为，例如接口返回报错、后续业务功能异常。

  • “预留”：表示接口或参数预留，当前暂未实现或功能不完善，不支持调用，后续版本可能开放。

  • “试验”：表示接口或参数处理试验阶段，接口定义、行为可能发生变更，不建议应用于生产环境中。

  • “废弃”：后续版本待删除，建议使用文档中的替换接口或参数。

同步和异步API说明

CANN支持以下几类显式同步，调用此类接口后，主机线程会阻塞直到相关的任务执行完成。

  • 设备同步：例如aclrtSynchronizeDevice

    阻塞当前主机线程直到Device上所有显式或隐式创建的Stream都完成所有先前下发的任务。应该尽量少使用该函数，以免拖延主机运行。

  • 流同步：例如aclrtSynchronizeStream

    阻塞当前主机线程直到指定的Stream中完成所有下发的任务。

  • 事件同步：例如aclrtSynchronizeEvent

    阻塞当前主机线程直到指定的Event事件完成。属于更细粒度的同步。

对于异步接口，主机线程调用异步接口后仅代表下发任务，不代表任务执行成功，在任务未完成前，异步接口已向主机线程返回成功。用户需要显式调用以上同步接口阻塞主机线程，等待任务完成，否则可能会导致训练或推理等业务异常、Device断链掉卡等未知情况。

废弃项列表

Runtime API中的废弃项（例如接口、返回码等），自指定版本在文档中声明废弃后，默认在声明满1年之后的版本删除对应代码与相关文档。举例：某接口在9.1.0（2026年6月）版本的文档中声明废弃，则计划在2027年6月30日之后的版本删除。

接口

返回码

枚举

  • aclSysParamOpt枚举中的ACL_OPT_STRONG_CONSISTENCY枚举项

    ACL_OPT_STRONG_CONSISTENCY枚举项在CANN 9.2.0版本标记为废弃，将在2027年9月30日之后的版本删除，请替换为：ACL_OPT_DETERMINISTIC枚举项。配置值设为2。

  • aclrtLaunchKernelAttrId枚举中的ACL_RT_LAUNCH_KERNEL_ATTR_LOCAL_MEMORY_SIZE枚举项

    ACL_RT_LAUNCH_KERNEL_ATTR_LOCAL_MEMORY_SIZE枚举项在CANN 9.0.0版本标记为废弃，将在2027年3月30日之后的版本删除，请替换为：ACL_RT_LAUNCH_KERNEL_ATTR_DYN_UBUF_SIZE枚举项。

  • aclrtDevAttr枚举中的ACL_DEV_ATTR_LOCAL_MEM_PER_VECTOR_CORE枚举项

    ACL_DEV_ATTR_LOCAL_MEM_PER_VECTOR_CORE枚举项在CANN 9.0.0版本标记为废弃，将在2027年3月30日之后的版本删除，请替换为：ACL_DEV_ATTR_UBUF_PER_VECTOR_CORE枚举项。

  • aclrtDevAttr枚举中的ACL_DEV_ATTR_SUPER_POD_DEVIDE_ID枚举项

    ACL_DEV_ATTR_SUPER_POD_DEVIDE_ID枚举项在CANN 9.0.0版本标记为废弃，将在2027年3月30日之后的版本删除，请替换为：ACL_DEV_ATTR_SUPER_POD_DEVICE_ID枚举项。

  • aclrtAtomicOperationCapability枚举中的ACL_RT_ATOMIC_CAPABILITY_REDUCATION枚举项

    ACL_RT_ATOMIC_CAPABILITY_REDUCATION枚举项在CANN 9.2.0版本标记为废弃，将在2027年9月30日之后的版本删除，请替换为：ACL_RT_ATOMIC_CAPABILITY_REDUCTION枚举项。

  • aclrtBinaryLoadOptionType枚举中的ACL_RT_BINARY_LOAD_OPT_LAZY_MAGIC枚举项

    ACL_RT_BINARY_LOAD_OPT_LAZY_MAGIC枚举项在CANN 8.5.0版本标记为废弃，将在2026年12月30日之后的版本删除，请替换为：ACL_RT_BINARY_LOAD_OPT_MAGIC枚举项。

  • aclrtLaunchKernelAttrValue联合体中的localMemorySize成员

    aclrtLaunchKernelAttrValue.localMemorySize成员在CANN 9.0.0版本标记为废弃，将在2027年3月30日之后的版本删除，请替换为：aclrtLaunchKernelAttrValue.dynUBufSize成员。