[AI][昇腾950] API 分类与总结

AscendC API 接口分类与学习指南源码仓库: CANN/asc-devkitinclude/basic_api目录适用范围: AscendC Kernel 侧算子开发目录架构概览接口分类总表核心计算类数据搬运类同步控制类内存与缓存管理类系统与调试类SIMD VF API(reg_api)基础类型与框架类总结一、架构概览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)GEMMkernel_operator_gemm_intf.h通用矩阵乘 (GEMM)Conv2Dkernel_operator_conv2d_intf.h2D 卷积计算FixPipekernel_operator_fixpipe_intf.h固定流水线数据后处理向量二元计算kernel_operator_vec_binary_intf.hAdd, Sub, Mul, Div 等向量标量计算kernel_operator_vec_binary_scalar_intf.h向量与标量运算双线性插值kernel_operator_vec_bilinearinterpolation_intf.h图像/特征图缩放数据搬运数据拷贝kernel_operator_data_copy_intf.hGM↔UB, UB↔UB 数据搬运同步控制同步kernel_operator_block_sync_intf.h多核同步 (SyncAll)确定性同步kernel_operator_determine_compute_sync_intf.h确定性计算同步内存与缓存缓存控制kernel_operator_cache_intf.hCache 模式设置原子操作kernel_operator_atomic_intf.h,kernel_operator_set_atomic_intf.h原子加、最大值等操作位模式矩阵乘kernel_operator_mm_bitmode_intf.h1-bit 矩阵乘加速系统与调试系统变量kernel_operator_sys_var_intf.h获取 BlockId, LoopCount 等Tensor Dumpkernel_operator_dump_tensor_intf.h调试用 Tensor 数据导出标量操作kernel_operator_scalar_intf.h标量寄存器读写限制约束kernel_operator_limits_intf.h硬件资源限制查询工具接口kernel_operator_utils_intf.h通用工具函数Proposalkernel_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 CMatmul高层矩阵乘全连接层、注意力机制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,Minkernel_operator_vec_binary_scalar_intf.h标量运算Adds,Muls,Maxskernel_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_tblock_idAscendC::GetBlockIdx();// 当前核编号uint32_tloop_countAscendC::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 大小constexpruint32_tub_sizeAscendC::GetUBSize();// 获取最大 Block 数constexpruint32_tmax_blocksAscendC::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,Reciprocalkernel_reg_compute_vec_binary_intf.h二元运算Vadd,Vsub,Vmul,Vdiv,Vmax,Vminkernel_reg_compute_vec_binary_scalar_intf.h标量二元Vadds,Vmulskernel_reg_compute_vec_ternary_scalar_intf.h三元标量Vaxpy(y a*x y)kernel_reg_compute_vec_cmpsel_intf.h比较选择Vcmpgt,Vcmpge,Vselectkernel_reg_compute_vec_reduce_intf.h归约运算Vreduce_sum,Vreduce_maxkernel_reg_compute_vec_fused_intf.h融合运算Vfma(融合乘加),Vaxpykernel_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.hUB↔寄存器数据拷贝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.hGather 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;// float16typedef...bfloat16_t;// bfloat16typedef...int4b_t;// int4typedef...uint1b_t;// uint1 (1-bit)// 枚举typedefenum{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 流水线并行类型安全: 使用LocalTensorT和GlobalTensorT确保类型安全可移植性: 通过__NPU_ARCH__宏隔离不同芯片的差异