ascendc-api-best-practices

name	ascendc-api-best-practices
description	Ascend C API 使用最佳实践。提供算术、归约、数据搬运、Buffer管理、精度转换等 API 的正确用法和限制说明。触发：用户询问具体 API 用法（如"DataCopy 怎么用"）、遇到 API 参数错误或限制报错（如 repeatTimes、对齐问题）、需要查看 API 最佳实践或避坑指南时。

Ascend C API 最佳实践

---

API 类别索引

API 类别	涵盖 API	核心文档	典型场景
算术运算	Add, Sub, Mul, Div, Adds, Muls	api-arithmetic.md	Softmax, LayerNorm, 广播优化
归约操作	ReduceMax, ReduceSum	api-reduce.md, api-reduce-pattern.md	Softmax, LayerNorm, ReduceMean
数据搬运	DataCopy, DataCopyPad	api-datacopy.md	非对齐处理、多维搬运
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	设备初始化、核数获取

---

场景索引

使用场景	相关文档	关键技巧
Softmax/LayerNorm	api-reduce.md, api-reduce-pattern.md, api-arithmetic.md	标量操作、广播优化、Buffer 复用
逐行处理（AR 模板）	api-arithmetic.md	Adds/Muls、节省 UB
多行广播（ARA 模板）	api-arithmetic.md	BinaryRepeatParams.src1RepStride=0、分批处理
非对齐数据	api-datacopy.md	DataCopyPad、32 字节对齐
混合精度	api-precision.md	FP16 输入 FP32 计算
流水线优化	api-pipeline.md, api-buffer.md	Double Buffer、事件同步
性能调优	api-buffer.md, api-repeat-limits.md	Double Buffer、repeatTimes 优化
遇到 API 限制	api-restrictions.md	替代方案、避坑指南

---

快速参考

完整的 API 参数速查表：api-quickref.md

---

⛔️ API 黑名单

禁止在生产代码中使用：

API	禁止原因	替代方案	文档
GlobalTensor::SetValue()	效率极低	DataCopyPad	api-datacopy.md
GlobalTensor::GetValue()	效率极低	DataCopyPad	api-datacopy.md
DataCopy(GM↔UB)	无法处理非对齐	DataCopyPad	api-datacopy.md

仅允许调试时使用：

// ✅ 调试：单点验证
AscendC::printf("debug: xGm[0]=%f\n", xGm.GetValue(0));