通用说明和约束

所需头文件和库文件

Ascend C API所在头文件目录为：

基础API：${INSTALL_DIR}/include/ascendc/basic_api/interface
高阶API：（注意，如下目录头文件中包含的接口如果未在资料中声明，属于间接调用接口，开发者无需关注）
- ${INSTALL_DIR}/include/ascendc/highlevel_api/lib
- ${INSTALL_DIR}/include/tiling

${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。

使用Ascend C API依赖的库文件说明如下：

基础API：不涉及
高阶API：因高阶API配套Host Tiling接口，需要链接libtiling_api.a。

为方便开发者使用，Ascend C基础API和高阶API均支持通过包含kernel_operator.h文件来调用相应接口。如无特殊说明，包含该头文件即可满足接口调用需求。若API文档中有特殊说明，则应遵循API的具体说明。

#include "kernel_operator.h"

逻辑位置和物理存储的映射关系

Ascend C API的操作数通常为GlobalTensor和LocalTensor，Tensor数据的存储位置均使用逻辑位置（TPosition）来表达，从而隐藏了硬件架构的差异。TPosition类型包括：VECIN、VECOUT、VECCALC、A1、A2、B1、B2、CO1、CO2等，其与物理内存的映射关系如下表所示。

表1 TPosition与物理内存映射关系
TPosition	物理内存
GM	Global Memory
VECIN	Unified Buffer
VECCALC	Unified Buffer
VECOUT	Unified Buffer
A1	L1 Buffer
A2	L0A Buffer
B1	L1 Buffer
B2	L0B Buffer
C1	Ascend 950PR/Ascend 950DT，L1 Buffer。 Atlas 训练系列产品，Unified Buffer。 Atlas 推理系列产品AI Core，Unified Buffer。 Atlas A2 训练系列产品/Atlas A2 推理系列产品，L1 Buffer。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，L1 Buffer。 Atlas 200I/500 A2 推理产品，Unified Buffer。
C2	Ascend 950PR/Ascend 950DT，BiasTable Buffer。 Atlas 训练系列产品，L0C Buffer。 Atlas 推理系列产品AI Core，L0C Buffer。 Atlas A2 训练系列产品/Atlas A2 推理系列产品，BiasTable Buffer。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，BiasTable Buffer。 Atlas 200I/500 A2 推理产品，BiasTable Buffer。
CO1	L0C Buffer
CO2	Ascend 950PR/Ascend 950DT，Global Memory。 Atlas 训练系列产品，Unified Buffer。 Atlas 推理系列产品AI Core，Unified Buffer。 Atlas A2 训练系列产品/Atlas A2 推理系列产品，Global Memory。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，Global Memory。 Atlas 200I/500 A2 推理产品，Global Memory。
TSCM	L1 Buffer
SPM	Ascend 950PR/Ascend 950DT，Global Memory。 Atlas 训练系列产品，L1 Buffer。 Atlas 推理系列产品AI Core，L1 Buffer。 Atlas A2 训练系列产品/Atlas A2 推理系列产品，Global Memory。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，Global Memory。
C2PIPE2GM	Ascend 950PR/Ascend 950DT，Fixpipe Buffer。 Atlas A2 训练系列产品/Atlas A2 推理系列产品，Fixpipe Buffer。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，Fixpipe Buffer。

通用地址对齐约束

AI Core上的存储单元用于存储矢量计算、矩阵计算的源操作数和目的操作数，各类存储单元的对齐要求如表2所示，因此Ascend C API操作数的起始地址对齐要求应与这些存储单元的对齐要求保持一致。需要注意的是，如果接口中已明确说明操作数起始地址对齐要求，则以具体API中的说明为准。

表2 不同存储单元的对齐要求
存储单元	对齐要求
Global Memory	无对齐要求。
Unified Buffer	32Byte对齐。
L1 Buffer	32Byte对齐。
L0A Buffer/L0B Buffer	512Byte对齐。
L0C Buffer	64Byte对齐。
BiasTable Buffer	64Byte对齐。
Fixpipe Buffer	64Byte对齐。

通用地址重叠约束

使用基础API的Tensor高维切分计算接口时，为了节省地址空间，开发者可以定义一个Tensor，供源操作数与目的操作数同时使用（即地址重叠）。使用时需要注意以下约束：

单次迭代内：源操作数与目的操作数必须100%完全重叠，不支持部分重叠。
多次迭代间：不支持前序迭代的目的操作数与后序迭代的源操作数重叠。例如，第N次迭代的目的操作数是第N+1次的源操作数（如下图所示）。在这种情况下，第N次迭代可能会改写覆盖源操作数的数值，导致无法得到预期结果。特别地，对于部分双目计算类的API（Add、Sub、Mul、Max、Min、AddRelu、SubRelu），当数据类型为half、int32_t、float时，支持前序迭代的目的操作数与后序迭代的源操作数重叠：仅针对目的操作数和第二个源操作数重叠的情况，且src1RepStride或者dstRepStride必须为0。

图1 地址重叠示例（不支持）

本节所述地址重叠通用约束适用于一般情况，API参考中如有额外特殊说明的，则以具体API中的说明为准。

API中没有描述地址重叠约束的，视为不支持Tensor高维切分计算的地址重叠，地址重叠时计算结果可能不满足预期。

父主题： SIMD API