AscendC API 接口分类与学习指南

源码仓库: CANN/asc-devkit include/basic_api 目录

适用范围: AscendC Kernel 侧算子开发

---

目录

1. 架构概览
2. 接口分类总表
3. 核心计算类
4. 数据搬运类
5. 同步控制类
6. 内存与缓存管理类
7. 系统与调试类
8. SIMD VF API(reg_api)
9. 基础类型与框架类
10. 总结

---

一、架构概览

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 关键设计原则

1. 分层封装: 从硬件指令到高层 API 逐层封装，平衡性能与易用性
2. 流水线友好: 所有接口设计都考虑了 MTE/Vector/Cube 流水线并行
3. 类型安全: 使用 LocalTensor<T> 和 GlobalTensor<T> 确保类型安全
4. 可移植性: 通过 __NPU_ARCH__ 宏隔离不同芯片的差异