# 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之后的版本执行移除。

### 接口

- [aclGetDataBufferSize](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-03_Operation_APIs.md#aclGetDataBufferSize_deprecated)接口
  
  此接口后续版本会废弃，请使用[aclGetDataBufferSizeV2](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-03_Operation_APIs.md#aclGetDataBufferSizeV2)接口。

- [aclrtQueryEvent](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/07_event_management.md#aclrtQueryEvent_deprecated)接口
  
  此接口后续版本会废弃，请使用[aclrtQueryEventStatus](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/07_event_management.md#aclrtQueryEventStatus)接口。

- [aclrtGetVersion](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/24_other_APIs.md#aclrtGetVersion_deprecated)接口
  
  此接口后续版本会废弃，请使用[aclsysGetVersionNum](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/24_other_APIs.md#aclsysGetVersionNum)接口或[aclsysGetVersionStr](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/24_other_APIs.md#aclsysGetVersionStr)接口。

- [aclrtMemcpyAsyncWithCondition](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/11-03_memory_copy_and_set.md#aclrtMemcpyAsyncWithCondition_deprecated)接口
  
  此接口后续版本会废弃，请使用[aclrtMemcpyAsync](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/11-03_memory_copy_and_set.md#aclrtMemcpyAsync)接口。

- [aclrtSetExceptionInfoCallback](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/13_exception_handling.md#aclrtSetExceptionInfoCallback_deprecated)接口
  
  此接口后续版本会废弃，请使用[aclrtExceptionInfoCallbackRegister](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/13_exception_handling.md#aclrtExceptionInfoCallbackRegister)接口或[aclrtExceptionInfoCallbackUnregister](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/13_exception_handling.md#aclrtExceptionInfoCallbackUnregister)。

### 返回码

- [ACL_ERROR_NONE](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码
  
  此返回码后续版本会废弃，请使用[ACL_SUCCESS](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码。

- [ACL_ERROR_NOT_STATIC_AIPP](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)
  
  此返回码后续版本会废弃，请使用[ACL_ERROR_GE_AIPP_NOT_EXIST](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码。

- [ACL_ERROR_STREAM_NOT_SUBSCRIBE](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)
  
  此返回码后续版本会废弃，请使用[ACL_ERROR_RT_STREAM_NO_CB_REG](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码。

- [ACL_ERROR_THREAD_NOT_SUBSCRIBE](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)
  
  此返回码后续版本会废弃，请使用[ACL_ERROR_RT_THREAD_SUBSCRIBE](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码。

- [ACL_ERROR_WAIT_CALLBACK_TIMEOUT](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)
  
  此返回码后续版本会废弃，请使用[ACL_ERROR_RT_REPORT_TIMEOUT](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码。

- [ACL_ERROR_INVALID_DEVICE](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)
  
  此返回码后续版本会废弃，请使用[ACL_ERROR_RT_INVALID_DEVICEID](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码。

- [ACL_ERROR_GROUP_NOT_SET](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)
  
  此返回码后续版本会废弃，请使用[ACL_ERROR_RT_GROUP_NOT_SET](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码。

- [ACL_ERROR_GROUP_NOT_CREATE](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)
  
  此返回码后续版本会废弃，请使用[ACL_ERROR_RT_GROUP_NOT_CREATE](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-01_aclError.md#aclError)返回码。

### 枚举

- [aclSysParamOpt](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/920/API/runtimeapi/docs/zh/api_ref/25-02_Enumerations.md#aclsysparamopt)枚举中的`ACL_OPT_STRONG_CONSISTENCY`枚举项
  
  此枚举中的`ACL_OPT_STRONG_CONSISTENCY`枚举项后续版本会废弃，请使用`ACL_OPT_DETERMINISTIC`替代。
