[AI][昇腾950] API 分类与总结
·
AscendC API 接口分类与学习指南
源码仓库: CANN/asc-devkit
include/basic_api目录
适用范围: AscendC Kernel 侧算子开发
目录
一、架构概览
AscendC 基础API 是 AscendC 算子开发的最底层的对外接口集合，它封装了昇腾 AI Core 硬件的具体实现，为上层 kernel_operator.h 提供基础接口支撑。
┌─────────────────────────────────────────────────────────────────────┐
│ basic_api 架构层次 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 用户算子代码 │
│ │ │
│ ▼ │
│ kernel_operator.h (高层统一接口) │
│ │ │
│ ▼ │
│ basic_api (底层硬件接口封装) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 核心计算 (Cube/Vector/Conv2D/GEMM) │ │
│ │ • 数据搬运 (DataCopy/Copy) │ │
│ │ • 同步控制 (PipeBarrier/SyncAll) │ │
│ │ • 内存管理 (Cache/SwapMem/Atomic) │ │
│ │ • 寄存器计算 (reg_compute/) │ │
│ │ • 系统调试 (DumpTensor/SysVar) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 硬件指令 (Cube Unit / Vector Unit / Scalar Unit / MTE) │
│ │
└─────────────────────────────────────────────────────────────────────┘
目录结构
include/basic_api/
├── core_mng/ # 核心管理
│ └── roc/ # ROC (运行时控制)
├── op_frame/ # 算子框架
│ └── elemwise_frame.h # 逐元素操作框架
├── reg_compute/ # 寄存器级计算接口 (22个文件)
│ ├── kernel_reg_compute_intf.h # 总入口
│ ├── kernel_reg_compute_vec_*.h # 向量计算
│ ├── kernel_reg_compute_copy_*.h # 拷贝
│ └── ...
├── kernel_base_types.h # 基础类型定义
├── kernel_common.h # 通用定义
├── kernel_operator_intf.h # 算子接口总入口 (聚合头文件)
├── kernel_operator_*.h # 各功能算子接口 (~20个文件)
└── kernel_cube_intf.h # Cube 单元接口
二、接口分类总表
| 大类 | 子类 | 核心头文件 | 功能描述 |
|---|---|---|---|
| 核心计算 | Cube 矩阵计算 | kernel_cube_intf.h, kernel_operator_mm_intf.h |
矩阵乘法 (Matmul) |
| GEMM | kernel_operator_gemm_intf.h |
通用矩阵乘 (GEMM) | |
| Conv2D | kernel_operator_conv2d_intf.h |
2D 卷积计算 | |
| FixPipe | kernel_operator_fixpipe_intf.h |
固定流水线数据后处理 | |
| 向量二元计算 | kernel_operator_vec_binary_intf.h |
Add, Sub, Mul, Div 等 | |
| 向量标量计算 | kernel_operator_vec_binary_scalar_intf.h |
向量与标量运算 | |
| 双线性插值 | kernel_operator_vec_bilinearinterpolation_intf.h |
图像/特征图缩放 | |
| 数据搬运 | 数据拷贝 | kernel_operator_data_copy_intf.h |
GM↔UB, UB↔UB 数据搬运 |
| 同步控制 | 同步 | kernel_operator_block_sync_intf.h |
多核同步 (SyncAll) |
| 确定性同步 | kernel_operator_determine_compute_sync_intf.h |
确定性计算同步 | |
| 内存与缓存 | 缓存控制 | kernel_operator_cache_intf.h |
Cache 模式设置 |
| 原子操作 | kernel_operator_atomic_intf.h, kernel_operator_set_atomic_intf.h |
原子加、最大值等操作 | |
| 位模式矩阵乘 | kernel_operator_mm_bitmode_intf.h |
1-bit 矩阵乘加速 | |
| 系统与调试 | 系统变量 | kernel_operator_sys_var_intf.h |
获取 BlockId, LoopCount 等 |
| Tensor Dump | kernel_operator_dump_tensor_intf.h |
调试用 Tensor 数据导出 | |
| 标量操作 | kernel_operator_scalar_intf.h |
标量寄存器读写 | |
| 限制约束 | kernel_operator_limits_intf.h |
硬件资源限制查询 | |
| 工具接口 | kernel_operator_utils_intf.h |
通用工具函数 | |
| Proposal | kernel_operator_proposal_intf.h |
目标检测后处理 (NMS等) | |
| 寄存器计算 | 寄存器向量计算 | reg_compute/kernel_reg_compute_vec_*.h |
寄存器级向量计算 (一元/二元/三元/归约/融合) |
| 寄存器拷贝 | reg_compute/kernel_reg_compute_copy_*.h |
寄存器数据拷贝 | |
| 寄存器管理 | reg_compute/kernel_reg_compute_*reg_*.h |
地址/掩码寄存器操作 | |
| 寄存器其他 | reg_compute/kernel_reg_compute_*.h |
打包、直方图、内存屏障等 |
三、核心计算类
核心计算类接口直接映射到 AI Core 的计算单元 (Cube Unit, Vector Unit)。
3.1 Cube 矩阵计算 (kernel_cube_intf.h)
Cube 单元是昇腾 AI Core 专用的矩阵乘加速单元。
// 典型接口模式
// Mmad: 矩阵乘加
AscendC::Mmad(z_local, x_local, y_local, mmad_params);
// Matmul: 高层矩阵乘
AscendC::Matmul(tC1, tA1, tB1, tC0, mmad_params);
| 接口 | 功能 | 适用场景 |
|---|---|---|
Mmad |
矩阵乘加 | C = A × B + C |
Matmul |
高层矩阵乘 | 全连接层、注意力机制 |
3.2 矩阵乘接口 (kernel_operator_mm_intf.h)
// 矩阵乘入口
// 支持 M/N/K 维度的分块计算
3.3 GEMM 接口 (kernel_operator_gemm_intf.h)
通用矩阵乘接口，支持更灵活的矩阵格式和计算模式。
// C = alpha * A * B + beta * C
// 支持: 转置, 分块, 多种数据类型
3.4 Conv2D 接口 (kernel_operator_conv2d_intf.h)
2D 卷积计算专用接口，支持 im2col + GEMM 加速路径。
3.5 向量计算接口
| 头文件 | 功能 | 示例操作 |
|---|---|---|
kernel_operator_vec_binary_intf.h |
二元运算 | Add, Sub, Mul, Div, Max, Min |
kernel_operator_vec_binary_scalar_intf.h |
标量运算 | Adds, Muls, Maxs |
kernel_operator_vec_bilinearinterpolation_intf.h |
双线性插值 | 图像缩放、特征图上采样 |
3.6 FixPipe 接口 (kernel_operator_fixpipe_intf.h)
FixPipe 是 Cube 计算后的数据后处理流水线，支持类型转换和量化。
// 典型用途: Cube 输出 (float32) → 量化 (int8/float16)
AscendC::Fixpipe(output_tensor, input_tensor, fixpipe_params);
四、数据搬运类
4.1 数据拷贝 (kernel_operator_data_copy_intf.h)
这是最常用的数据搬运接口，支持 GM↔UB、UB↔L1 等多种路径。
// GM → UB (数据加载)
AscendC::DataCopy(ub_tensor, gm_tensor, data_copy_params);
// UB → GM (数据存储)
AscendC::DataCopy(gm_tensor, ub_tensor, data_copy_params);
五、同步控制类
5.1 同步 (kernel_operator_block_sync_intf.h)
多核 (Block) 间的同步机制。
// 全核同步
AscendC::SyncAll();
// 软同步， 适配于 1980, 1951 等系列， 在昇腾910B. C 950 不要使用此函数
AscendC::SyncAll(condition);
5.2 确定性计算同步 (kernel_operator_determine_compute_sync_intf.h)
确保计算结果的确定性，用于要求可重现的场景。
六、内存与缓存管理类
6.1 缓存控制 (kernel_operator_cache_intf.h)
控制 L1 Cache 和 L2 Cache 的读写模式。
// 设置缓存模式
AscendC::SetCacheMode(cache_params);
AscendC::SetScalarCacheMode(mode); // 标量缓存模式
6.2 原子操作 (kernel_operator_atomic_intf.h)
支持多核并发的原子操作。
// 原子加
AscendC::AtomicAdd(gm_addr, value);
// 原子最大值
AscendC::AtomicMax(gm_addr, value);
6.3 位模式矩阵乘 (kernel_operator_mm_bitmode_intf.h)
1-bit 量化矩阵乘加速，用于超大规模语言模型的推理加速。
七、系统与调试类
7.1 系统变量 (kernel_operator_sys_var_intf.h)
获取运行时系统信息。
uint32_t block_id = AscendC::GetBlockIdx(); // 当前核编号
uint32_t loop_count = AscendC::GetLoopCount(); // 循环计数
7.2 Tensor Dump (kernel_operator_dump_tensor_intf.h)
调试用 Tensor 数据导出。
// 导出 LocalTensor 数据用于调试
AscendC::DumpTensor(tensor, "tensor_name", element_count);
7.3 标量操作 (kernel_operator_scalar_intf.h)
标量寄存器的读写操作，用于控制流和地址计算。
7.4 硬件限制 (kernel_operator_limits_intf.h)
查询硬件资源限制。
// 获取 UB 大小
constexpr uint32_t ub_size = AscendC::GetUBSize();
// 获取最大 Block 数
constexpr uint32_t max_blocks = AscendC::GetMaxBlockNum();
八、SIMD VF 下的 API (reg_api)
reg_compute 目录包含寄存器级（Register Level）计算接口，是比 kernel_operator_vec_* 更底层的向量计算接口。
8.1 架构关系
┌──────────────────────────────────────────────────────┐
│ 向量计算接口层次 │
├──────────────────────────────────────────────────────┤
│ │
│ memory base api : kernel_operator_vec_binary_intf.h │
│ (LocalTensor 级别 ) │
│ │ │
│ ▼ │
│ 底层: reg_compute/kernel_reg_compute_vec_binary.h │
│ (寄存器级别, 手动管理同步和流水线) │
│ │ │
│ ▼ │
│ 硬件: Vector Unit 指令 │
│ │
└──────────────────────────────────────────────────────┘
8.2 寄存器向量计算
| 头文件 | 功能 | 典型操作 |
|---|---|---|
kernel_reg_compute_vec_unary_intf.h |
一元运算 | Abs, Sqrt, Exp, Log, Reciprocal |
kernel_reg_compute_vec_binary_intf.h |
二元运算 | Vadd, Vsub, Vmul, Vdiv, Vmax, Vmin |
kernel_reg_compute_vec_binary_scalar_intf.h |
标量二元 | Vadds, Vmuls |
kernel_reg_compute_vec_ternary_scalar_intf.h |
三元标量 | Vaxpy (y = a*x + y) |
kernel_reg_compute_vec_cmpsel_intf.h |
比较选择 | Vcmpgt, Vcmpge, Vselect |
kernel_reg_compute_vec_reduce_intf.h |
归约运算 | Vreduce_sum, Vreduce_max |
kernel_reg_compute_vec_fused_intf.h |
融合运算 | Vfma (融合乘加), Vaxpy |
kernel_reg_compute_vec_arange_intf.h |
范围生成 | Varange (生成等差数列) |
kernel_reg_compute_vec_duplicate_intf.h |
向量复制 | Vdup (广播标量到向量) |
kernel_reg_compute_vec_vconv_intf.h |
类型转换 | Vcast (float↔int, float16↔float32) |
8.3 寄存器数据搬运
| 头文件 | 功能 |
|---|---|
kernel_reg_compute_copy_intf.h |
寄存器间数据拷贝 |
kernel_reg_compute_datacopy_intf.h |
UB↔寄存器数据拷贝 |
8.4 寄存器管理
| 头文件 | 功能 |
|---|---|
kernel_reg_compute_addrreg_intf.h |
地址寄存器操作 |
kernel_reg_compute_maskreg_intf.h |
掩码寄存器操作 |
kernel_reg_compute_membar_intf.h |
内存屏障 (Memory Barrier) |
8.5 寄存器其他
| 头文件 | 功能 |
|---|---|
kernel_reg_compute_gather_mask_intf.h |
Gather Mask (按掩码收集) |
kernel_reg_compute_histograms_intf.h |
直方图计算 |
kernel_reg_compute_pack_intf.h |
数据打包 (Pack/Unpack) |
kernel_reg_compute_struct_intf.h |
寄存器结构体定义 |
kernel_reg_compute_utils.h |
寄存器计算工具函数 |
九、基础类型与框架类
9.1 基础类型 (kernel_base_types.h)
定义 AscendC 的基础数据类型和枚举。
// 常见类型
typedef ... half_t; // float16
typedef ... bfloat16_t; // bfloat16
typedef ... int4b_t; // int4
typedef ... uint1b_t; // uint1 (1-bit)
// 枚举
typedef enum {
TPosition::GM,
TPosition::VECIN,
TPosition::VECOUT,
TPosition::VECCALC,
TPosition::TSCALC,
} TPosition;
9.2 通用定义 (kernel_common.h)
通用宏、常量定义。
9.3 逐元素框架 (op_frame/elemwise_frame.h)
逐元素算子的通用框架，简化 Add/Sub/Mul 等算子的开发。
// 框架自动处理: 数据搬运 → 计算 → 存储
// 开发者只需实现核心计算逻辑
十、总结
10.1 接口层次总结
┌─────────────────────────────────────────────────────────────────────┐
│ basic_api 接口层次 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 3: Memory Base API (kernel_operator_*.h) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • LocalTensor 级别的 API │ │
│ │ • 自动流水线管理 │ │
│ │ • 自动同步 │ │
│ │ → 适合绝大多数算子开发 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Layer 2: 寄存器计算接口 (reg_api/) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 寄存器级别的 API │ │
│ │ • 手动流水线管理 │ │
│ │ • 手动同步 │ │
│ │ → 适合极致性能优化场景 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Layer 1: 硬件接口 (kernel_cube_intf.h, core_mng/) │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ • 直接映射硬件指令 │ │
│ │ • 无封装 │ │
│ │ → 仅供内部或极特殊场景使用 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
10.2 开发建议
| 场景 | 推荐接口 | 理由 |
|---|---|---|
| 常规算子开发 (Add/Mul/Conv) | Layer 3: kernel_operator_*.h |
接口友好，自动管理流水线 |
| 极致性能优化 | Layer 2: reg_compute/ |
手动控制寄存器，榨干硬件性能 |
| 调试 | DumpTensor, SysVar |
查看中间数据和系统状态 |
| 多核并行 | block_sync, atomic |
确保正确性和数据一致性 |
10.3 关键设计原则
- 分层封装: 从硬件指令到高层 API 逐层封装，平衡性能与易用性
- 流水线友好: 所有接口设计都考虑了 MTE/Vector/Cube 流水线并行
- 类型安全: 使用
LocalTensor<T>和GlobalTensor<T>确保类型安全 - 可移植性: 通过
__NPU_ARCH__宏隔离不同芯片的差异
鲲鹏昇腾开发者社区是面向全社会开放的“联接全球计算开发者，聚合华为+生态”的社区，内容涵盖鲲鹏、昇腾资源，帮助开发者快速获取所需的知识、经验、软件、工具、算力，支撑开发者易学、好用、成功，成为核心开发者。
更多推荐
1
0- 0
已为社区贡献15条内容
所有评论(0)