---
title: 通用说明和约束
description: "Ascend C API所在头文件目录为："
url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/API/ascendcopapi/atlasascendc_api_07_0004.html
sourcePath: /source/zh/canncommercial/900/API/ascendcopapi/atlasascendc_api_07_0004.html
indexId: 1dfffa7e025edb20fb8a58805be6cb09ac94177e35578ec119444f1abe01437e76
---
# 通用说明和约束

#### 所需头文件和库文件

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 | Atlas 350 加速卡，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 | Atlas 350 加速卡，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 | Atlas 350 加速卡，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 | Atlas 350 加速卡，Global Memory。 Atlas 训练系列产品 ，L1 Buffer。 Atlas 推理系列产品 AI Core，L1 Buffer。 Atlas A2 训练系列产品 / Atlas A2 推理系列产品 ，Global Memory。 Atlas A3 训练系列产品 / Atlas A3 推理系列产品 ，Global Memory。 |
| C2PIPE2GM | Atlas 350 加速卡，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高维切分计算的地址重叠，地址重叠时计算结果可能不满足预期。