ascendc-api-best-practices
Ascend C API 使用最佳实践。提供算术、归约、数据搬运、Buffer管理、精度转换、通信接口等 API 的正确用法和限制说明。触发：用户询问具体 API 用法（如"DataCopy 怎么用"、"ReadNbi 怎么用"）、遇到 API 参数错误或限制报错（如 repeatTimes、对齐问题）、需要查看 API 最佳实践或避坑指南时。
SKILL.mdops/ascendc-api-best-practices/SKILL.md
GitHubAscend C API 最佳实践
API 类别索引
| API 类别 | 涵盖 API | 核心文档 | 典型场景 |
|---|---|---|---|
| 算术运算 | Add, Sub, Mul, Div, Adds, Muls | api-arithmetic.md | Softmax, LayerNorm, 广播优化 |
| 跨代际迁移（Subnormal 与超越函数） | Exp, Ln, Sqrt, Rsqrt, Div, Reciprocal | api-cross-gen-migration.md | DAV_2201→DAV_3510 迁移精度对齐、高精度/高性能模式选择 |
| 归约操作 | ReduceMax, ReduceSum | api-reduce.md, api-reduce-pattern.md | Softmax, LayerNorm, ReduceMean |
| 归并排序 | Sort, Concat, MrgSort, Extract | api-mrgsort.md | Sort, ArgSort, TopK |
| 数据搬运 | DataCopy, DataCopyPad | api-datacopy.md | 非对齐处理、多维搬运 |
| LoadData / Cube 加载 | LoadData2D, LoadData2DV2, LoadData2DMx | api-loaddata.md | L1 → L0 加载、Cube GEMM、MX 块量化格式 |
| Transpose / 重排 | TransDataTo5HD, Gather | api-transpose.md | 小通道 transpose、permute |
| 数据过滤/解交织 | GatherMask | api-gathermask.md | RoPE 奇偶拆分、列分量分离、非均匀间隔自定义 mask |
| Matmul 高阶 API（Cube） | MatmulImpl, MatmulConfig, IterateAll | api-matmul.md | MatMul, BatchMatMul, MatMulBias；限 Atlas A2/A3 系列（DAV_2201）平台 |
| GMM 高阶 API | GMMBaseParams, GMMArray, per-token dequant 管线 | api-gmm.md | GroupedMatmul, A8W8/A4W4 量化反量化；限 Atlas A2/A3 系列（DAV_2201）平台 |
| Buffer 管理 | TBuf, TQue | api-buffer.md | Double Buffer、内存规划 |
| 精度转换 | Cast | api-precision.md | FP16/FP32 混合精度 |
| 流水线同步 | EnQue, DeQue, SetFlag | api-pipeline.md | 多级流水线、事件同步 |
| Compare 256B对齐 | Compare | api-restrictions.md | Padding 策略 |
| repeatTime 限制 | repeatTimes ≤ 255 | api-repeat-limits.md | 分批处理 |
| API 限制 | - | api-restrictions.md | 禁用 API、编译期限制 |
| Host Runtime | aclrtSetDevice, aclrtGetDeviceInfo | api-host-runtime.md | 设备初始化、核数获取 |
| 点对点通信 | Hcomm, ReadNbi, WriteNbi, Drain | api-hcomm.md | 跨卡点对点搬运、URMA 队列语义 |
| 跨核同步 | CrossCoreSetFlag, CrossCoreWaitFlag, SyncAll | api-crosscore-sync.md | AIC↔AIV 通知、flagId 硬件规则 |
| HCCL Host | HcclCommInitRootInfoConfig, HcclChannelAcquire, HcclEngineCtxCreate | api-hccl-host.md | 通信域/channel/engine ctx 管理 |
| DMA 原子操作 | SetAtomicAdd, SetAtomicMax, DisableDmaAtomic | api-atomic.md | 多核/多 rank 部分和累加、split-K 累加 |
场景索引
| 使用场景 | 相关文档 | 关键技巧 |
|---|---|---|
| Softmax/LayerNorm | api-reduce.md, api-reduce-pattern.md, api-arithmetic.md | 标量操作、广播优化、Buffer 复用 |
| 逐行处理（AR 模板） | api-arithmetic.md | Adds/Muls、节省 UB |
| MatMul/BatchMatMul（Ascend C 高阶 API，Atlas A2/A3 系列） | api-matmul.md | MatmulConfig 选择、enUnitFlag、IterateAll、TilingHeader stack 加载 |
| GroupedMatmul / GMM（Ascend C 高阶 API，Atlas A2/A3 系列） | api-gmm.md | GMMArray 分组索引、AIC/AIV 分职、per-token dequant 管线 |
| Transpose / 重排 | api-transpose.md | 2维度 转置性能 |
| 多行广播（ARA 模板） | api-arithmetic.md | BinaryRepeatParams.src1RepStride=0、分批处理 |
| 半精度加减法（FP16/BF16 Add/Sub） | api-arithmetic.md, api-precision.md | 默认升精度（除非 spec 明确同量级）、in-place 复用 |
| 非对齐数据 | api-datacopy.md | DataCopyPad、32 字节对齐 |
| 混合精度 | api-precision.md | FP16 输入 FP32 计算 |
| Subnormal 精度丢失（DAV_3510 跨代迁移） | api-cross-gen-migration.md | FTZ 语义、PRECISION_1ULP_FTZ_FALSE、eps 规避 |
| Fixpipe 跨代参数（L0C 回写） | api-cross-gen-fixpipe.md | DAV_2201→DAV_3510 回写参数切换：FixpipeParamsArch3510 字段与单位差异 |
| 流水线优化 | api-pipeline.md, api-buffer.md | Double Buffer、事件同步 |
| 性能调优 | api-buffer.md, api-repeat-limits.md | Double Buffer、repeatTimes 优化 |
| 遇到 API 限制 | api-restrictions.md | 替代方案、避坑指南 |
| 通算融合（MC2） | api-hcomm.md, api-crosscore-sync.md | Hcomm/CrossCore 原语层 API；编排层（核分工、flag 流水、UB 隔离、通信并行度）请参考对应框架/领域技能文档 |
| 多卡通信 | api-hccl-host.md | HCCL 建链、engine ctx 下发、资源生命周期 |
| RoPE 奇偶拆分 | api-gathermask.md | pattern 1/2、Normal/Counter 均可、零拷贝偏移；限 Atlas A2/A3 系列（DAV_2201）平台 |
| Interleaved 列分离 | api-gathermask.md | 官方：Normal 模式、stride=8；实测：tile≥2048、外层循环；限 Atlas A2/A3 系列（DAV_2201）平台 |
| 非均匀间隔自定义 mask | api-gathermask.md | 用户自定义 LocalTensor mask、类型匹配 |
快速参考
完整的 API 参数速查表：api-quickref.md
⛔️ API 黑名单
禁止在生产代码中使用：
| API | 禁止原因 | 替代方案 | 文档 |
|---|---|---|---|
GlobalTensor::SetValue() |
效率极低 | DataCopyPad |
api-datacopy.md |
GlobalTensor::GetValue() |
效率极低 | DataCopyPad |
api-datacopy.md |
限制使用的 API：
| API | 限制条件 | 说明 | 文档 |
|---|---|---|---|
DataCopy(GM↔UB) |
仅当搬运数据严格 32 字节对齐时允许使用 | 非对齐场景必须使用 DataCopyPad |
api-datacopy.md |
仅允许调试时使用：
// ✅ 调试：单点验证
AscendC::printf("debug: xGm[0]=%f\n", xGm.GetValue(0));