通用说明和约束

需要包含的头文件

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软件安装后文件存储路径。若安装的Ascend-cann-toolkit软件包，以root安装举例，则安装后文件存储路径为：/usr/local/Ascend/ascend-toolkit/latest。

为方便开发者使用，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	Atlas 训练系列产品，Unified Buffer。 Atlas 推理系列产品AI Core，Unified Buffer。 Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件，L1 Buffer。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，L1 Buffer。 Atlas 200I/500 A2 推理产品，Unified Buffer。
C2	Atlas 训练系列产品，L0C Buffer。 Atlas 推理系列产品AI Core，L0C Buffer。 Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件，BiasTable Buffer。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，BiasTable Buffer。 Atlas 200I/500 A2 推理产品，BiasTable Buffer。
CO1	L0C Buffer
CO2	Atlas 训练系列产品，Unified Buffer。 Atlas 推理系列产品AI Core，Unified Buffer。 Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件，Global Memory。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，Global Memory。 Atlas 200I/500 A2 推理产品，Global Memory。
TSCM	L1 Buffer
SPM	Atlas 训练系列产品，L1 Buffer。 Atlas 推理系列产品AI Core，L1 Buffer。 Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件，Global Memory。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，Global Memory。
C2PIPE2GM	Atlas A2 训练系列产品/Atlas 800I A2 推理产品/A200I A2 Box 异构组件，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对齐。

通用地址重叠约束

使用基础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高维切分计算的地址重叠，地址重叠时计算结果可能不满足预期。