Ascend C资料设计规范

设计目标

Ascend C资料是开发者使用昇腾NPU进行算子开发的唯一官方入口。资料质量直接影响开发者从"了解→上手→精通"全链路效率。

本设计文档从三个维度定义Ascend C资料的设计要求：

维度	核心问题	目标状态
可获取性（Discoverability）	开发者能否在3步内找到所需信息？	从"搜索→猜测→试错"变为"导航→定位→理解"
可读性（Readability）	找到后能否无歧义地理解？	从"反复推理+交叉验证"变为"一次读完即理解"
完备性（Completeness）	理解后信息是否足够完成开发任务？	从"文档只给一半，另一半靠踩坑"变为"按文档操作可直接完成"

此外，跨版本迁移场景（涉及跨代迁移兼容性指南和版本约束标注规范章节）同时涉及上述三个维度：开发者要能找到迁移信息（可获取性）、看懂迁移步骤（可读性）、迁移后功能不退化（完备性）。

资料体系架构

Ascend C资料体系由五份核心文档组成，通过交叉链接形成可导航的资料网络。

资料体系架构图如下所示：

资料体系架构图

核心导航逻辑：每个文档既是链接的发起方（首次提到其他文档负责的内容时，链接过去），也是链接的接收方（别的文档提到本文档负责的内容时，链接回来）。

五份文档定位与导航原则：

文档	负责说清什么	别的文档从这里获取什么	本文档链接出去的方向
入门教程	Ascend C概述、环境准备、快速上手实践（HelloWorld、首个算子）	其他文档可链接到入门教程作为零基础入口	编程概念深入→链接到编程指南；首次提到某个API→链接到API参考手册
编程指南	编程模型、编程范式、编译运行、硬件架构、高级编程的核心概念	其他文档遇到编程概念时链接回编程指南获取权威解释	首次提到某个API→链接到API参考手册；首次提到优化/实践→链接到算子实践参考；提到架构版本差异→链接到跨代迁移指南
API参考手册	每个接口的参数定义、使用约束、代码示例、API之间的关联关系	编程指南和算子实践参考提到某个API时链接到API参考手册获取接口详情	前置概念→链接回编程指南；API有跨版本差异→链接到跨代迁移指南
算子实践参考	算子怎么写、性能怎么优化、怎么调试、典型案例	编程指南点到为止的实践和优化内容链接到算子实践参考展开	首次用到某个API→链接到API参考手册；涉及编程概念→链接回编程指南；优化方案因架构版本不同→链接到跨代迁移指南
跨代迁移兼容性指南	API兼容策略、架构版本间有哪些变更、具体迁移步骤	任何文档涉及版本差异、API废弃/新增时链接到迁移指南获取迁移路径	概念定义→链接回编程指南；迁移后的新API→链接到API参考手册

补充说明：

样例库（asc-devkit/examples/）不属于Ascend C资料体系，但五份文档中的代码示例均可链接到样例库
技术附录（术语表、原理、语法限制）归入编程指南，作为共享知识基础设施
入门教程独立成册，目录位于 docs/zh/guide/入门教程/，包含概述、环境准备、快速入门（SIMD/SIMT）

可获取性（Discoverability）

三层导航体系

文档提供三层导航，覆盖不同使用场景：

导航层	形式	适用场景	设计要求
全局层	目录树+全文搜索	知道自己要找什么	目录≤5级深度；搜索覆盖代码/参数/概念名
决策层	决策树/对比表/选择指引	知道需求但不知道选哪个	每个多选岔路口必须有决策树或对比表
关联层	双向交叉链接+关联API段	找到A后需要了解关联的B	五份文档互链形成可导航网络

具体要求：

编程指南每个多路径章节（SIMD/SIMT选择、API层级选择）开头放决策树或对比表
API参考手册每个API族（Reduce系列、Matmul系列、DataCopy系列）开头放选择对照表
算子实践参考每个有多种实现方案的算子开头放方案差异表+选择建议
每个对照表给出明确的默认推荐（"不确定时优先使用X"）
包含"常见选错场景"说明（如"遇到XXX错误，可能是因为选了A而非B"）

五文档链接联动

五份核心文档通过链接形成可导航网络，链接方向遵循"谁提到别人负责的内容，谁就加链接"原则：

链接关系（10条链接规则）：

链接规则	发起方	链接到	触发时机	说明
L0	入门教程	编程指南	入门教程点到编程概念需深入时	入门教程只给快速上手，概念深入链接到编程指南
L1	编程指南	API参考手册	首次引入新API名称	概念讲解中API名首次出现处加链接
L2	编程指南	算子实践参考	首次引入实践/优化话题	编程指南点到为止，链接到实践参考展开
L3	编程指南	跨代迁移指南	提及架构版本差异/废弃API时	详见跨代迁移兼容性指南
L4	算子实践参考	API参考手册	实践案例中首次使用API	算子样例代码中API首次出现处链接到接口详情
L5	算子实践参考	编程指南	首次引入编程概念	实践中涉及编程模型概念时链接到权威解释
L6	算子实践参考	跨代迁移指南	提及跨架构优化差异时	性能优化方案因架构版本不同时链接
L7	API参考手册	编程指南	首次引入编程概念	"前置知识"段链接到概念介绍章节
L8	API参考手册	跨代迁移指南	标注API版本差异/废弃信息时	API页标注版本范围并链接
L9	跨代迁移指南	API参考手册	迁移目标使用新API时	遗留API→新API映射表中链接到新API详情
L10	跨代迁移指南	编程指南	迁移涉及编程概念变更时	架构变更映射中链接到概念解释

链接规则：

同一概念/API首次出现时加链接，后续重复出现不重复链接
API参考页面的概念引用就近行内链接（非集中在页面底部）
注意方向：算子实践参考→API参考手册（查接口详情），API参考手册不需要反向链接到算子实践参考
跨代迁移指南同时是链接发起方和接收方：向外链接到编程指南（概念变更）和API参考手册（新API详情）；接收其他文档涉及版本差异时指向它的链接
所有资料涉及的完整代码样例引用到样例库

术语统一入口

建立统一术语对照表（独立附录文件），所有文档共享：

对照内容	形式	位置
术语对照表	四列映射：抽象概念↔硬件单元↔编程模型↔接口名	独立附录文件，概述章链接引用
产品型号对照表	产品名↔芯片名↔架构代号	编程指南概述章
同义词索引	同一概念的多种叫法→权威解释页	附录或索引页

具体要求：

任何文档中出现的代号/缩写，首次出现时括号注释全称并链接到对照表
同一概念在不同文档中允许用不同层级的名称，但必须在术语对照表中建立等价关系
典型必须映射的术语组：DMA/MTE/DataCopy（同一搬运功能三层名）、Local Memory/L1/__cbuf__（同一存储三层名）

文件职责聚焦

每个文件有明确的单一职责，概述文件定位为导航页：

文件类型	职责	禁止
概述/总览文件	导航：主题列表+1-2句概述+子章节链接	展开技术细节、大量代码
概念介绍文件	解释：概念定义+原理+约束+关系	重复其他文件已有内容（改为引用）
操作指南文件	步骤：代码片段+操作步骤+注意事项	概念定义（链接到概念文件）
API参考页	参考：原型+参数+约束+示例+关联API	编程模型解释（链接到编程指南）
迁移指导文件	步骤：变更清单+映射表+验证步骤	编程模型解释（链接到编程指南）、重复已有迁移内容（改为引用）

具体要求：

概述文件篇幅：导航表格/链接占比≥60%
如果一个文件超过3个不相关主题，拆分为多个子文件
同一内容的详细描述只出现一次（权威版本），其余位置用"详见X章节"引用
硬件架构描述统一到一份文件，不允许SIMD版/SIMT版各描述一半

可读性（Readability）

按抽象层级使用术语

文档按章节的抽象层级使用对应术语，首次跨界时必须关联：

章节层级	使用术语	首次跨界处理
高层（抽象硬件架构、概述）	抽象名：Global Memory、Local Memory、计算单元	不突兀混入UB、L0A等底层名
低层（编程模型、数据搬运）	硬件名：UB、L1 Buffer、L0A/B/C	首次出现时括号关联：`UB（即抽象架构中Local Memory的一部分）`
API层（API参考手册）	API名：DataCopy、LocalTensor	首次出现时关联硬件名：`DataCopy（触发MTE数据搬运单元指令）`

反面案例（禁止）：抽象硬件架构文档直接写"数据通过UB搬入VEC运算"，跳过抽象层。

易混概念显式区分

名称相近、层级易混淆的概念必须用对比表或关系图显式区分：

必须区分的概念组：

概念组	区分维度	区分形式
SPMD vs SIMD vs SIMT	SPMD=编程模型、SIMD=指令执行模式、SIMT=线程执行模式	层级关系图
四步法(Tiling→搬→算→搬) vs TPipe四步(Alloc→EnQue→...)	编程流程vs流水管理范式	对比表
DMA vs MTE vs DataCopy	三层名同一件事	术语映射表
MemBase(基础API) vs RegBase(VF融合API)	计算位置不同(UB vs寄存器)、Load/Store次数不同	对比表+场景推荐
Block vs CTA	Ascend C编程单元vs CUDA等价概念	竞品映射表
`LocalTensor` vs `GlobalTensor` vs `TBuf`	计算用/外部用/临时用缓冲区	对照表+场景推荐
`__ubuf__` vs `__cbuf__` vs `__gm__`	UB空间/L1空间/GM空间地址限定符	对照表
`asc_`前缀vs `Ascend C::`前缀vs `cce::`前缀	C API / C++ API / Intrinsics	命名规则表

具体要求：

在首次出现混淆可能的位置就给出区分，不延后
禁止用一个概念的代码示例暗示等价于另一概念

约束前置且醒目

所有硬件级/平台级约束在概念首次定义处醒目标注，不依赖后续章节或运行时报错暴露：

约束信息要素：

约束类型：地址对齐/数据类型限制/元素数量范围/格式限制/只读语义/时序要求
约束值：具体数值或范围（如"32字节对齐"、"half类型≥128元素"）
违反后果：编译报错/运行时越界/结果错误/性能下降

格式要求：独立段落，集中列出（不分散在各参数说明小字中）

放置位置：

API参考页：函数原型之后、参数说明之前，独立的"约束与限制"段落
编程指南：概念引入时同步给出约束，而非后续补充

参数语义图解化

复杂参数（涉及内存布局、维度映射、stride计算）用图解代替纯文字：

参数类型	图解形式
stride/offset类	内存布局对照图（标注每步偏移）
维度映射类	维度变换映射图（如[K,N]→[N,K]转置）
格式类(ND/NZ)	两种格式的内存排布对比图
mask类	元素对应位掩码图
数据流类	输入→处理→输出流图

判断标准：一个参数用纯文字需要3句以上才能解释清楚→必须配图。图解与文字描述必须一致。

代码片段精简聚焦

每种编程范式/关键流程提供精简代码片段+完整样例链接：

要求	说明
精简聚焦	只展示当前讲解相关代码，用 `// ... 其他初始化` 省略无关部分
可理解	每个片段配2-3行文字说明"这段代码做了什么"
可追踪	片段末尾链接到样例库完整示例
关键字注释	Ascend C特有关键字（`__aicore__`、`__ubuf__`、`__simd_vf__`等）必须行内注释
参数覆盖	覆盖常用参数组合，不仅展示单一用法

前置知识显式铺垫

每个概念/API首次出现时提供前置知识铺垫，确保不逆序阅读：

API参考页开头放"前置知识"段：使用此API前需要了解的概念（链接到编程指南）
算子实践参考开头放"前置说明"段：阅读本文档需要的知识基础和前置样例链接
编程指南章节按学习路径排列：基础概念→编程模型→编程范式→性能优化（不按功能模块平铺）
概念B依赖概念A时，A先出现或在B处有明确引用链接

Host侧与Kernel侧明确分离

API文档中Host侧和Kernel侧必须明确标注和分离：

每个API页面标注适用侧：Host侧/Kernel侧/Host+Kernel
Host侧API（Tiling计算、workspace分配）与Kernel侧API（计算接口、数据搬运）分节展示
编程指南中有Host/Kernel分工全景图
涉及跨侧数据传递的概念（workspace/Tiling），提供端到端调用链路图

SIMT章节业界参考

仅适用于SIMT编程模型章节。SIMT核心概念参考业界的说明方式，提供概念映射表（Block↔CTA、Warp↔Warp、Lane↔Thread、__aicore__↔__global__）和关键差异说明。

完备性（Completeness）

硬件参数与数据通路校验

文档中的硬件参数值（容量、粒度、范围、数据通路路径）必须与芯片规格说明书交叉验证：

必须校验的内容：

每个硬件参数值（容量、大小、粒度、范围）有规格说明书佐证
"固定值""always""统一为"等绝对性描述经规格核实——很多"固定值"实际由配置参数决定
数据通路描述与实际搬运路径一致（不同文档对同一通路不得矛盾）
不同芯片版本的参数差异已标注

约束信息零遗漏

所有隐式约束在文档中显式记录，不依赖运行时assert或编译错误暴露：

约束类别	覆盖要求	常见遗漏
数据类型限制	每个API列出支持的完整数据类型列表	half类型最小元素数、bf16支持缺失
地址对齐	明确对齐字节数和对齐方向	32B对齐仅写在assert中
元素数量范围	明确最小值、最大值、对齐粒度	"8元素"约束未文档化
格式限制	ND/NZ/FRACTAL等格式支持情况	格式切换的偏移计算差异
使用模式限制	直调/工程模式/调试模式的差异	PipeBarrier仅特定模式可用
多核/多实例限制	kernel内只读、核间同步要求	配置参数只读语义未说明
API组合限制	互斥API/必需搭配API	文档推荐的组合实际不支持

操作要求：约束信息从规格说明书和assert代码中提取，集中展示在首次定义处。

示例分层覆盖

每个API/编程范式提供示例：

示例层级定义：

层级	定位	篇幅	要求
Minimal	最小可运行示例	<30行核心代码	单一功能、复制即编译运行
Standard	典型用法示例	50-150行	覆盖核心参数组合
Advanced	进阶示例	>150行	与其他API组合使用、性能优化技巧

各文档的具体要求：

API参考手册：每个API至少1个最小可运行示例（Minimal），并在示例中覆盖常用参数组合
编程指南：每个编程范式至少1个Minimal示例+样例库完整示例链接
算子实践参考：每个算子实践案例至少1个典型用法示例以及1个进阶用法示例
示例可直接复制编译运行（含CMakeLists.txt引用、数据生成说明、预期输出）

API关联与组合使用说明

每个API页面包含关联API段，说明同一版本内API之间的组合使用关系和禁忌。跨版本的迁移关系归5.5节负责。

包含内容：互斥API（独立警告框）+ 功能相近API选择指引

要求：

互斥组合用独立警告框标注（如"BatchMatmul与SetQuantVector组合不支持"）
功能相近API族提供选择决策树
API参考手册中提供API关系总览图（高阶API→底层API封装层次）

跨代迁移覆盖完备

跨代迁移兼容性指南必须覆盖完整的迁移路径，确保开发者在架构升级时不因文档缺失而受阻：

必须覆盖的迁移要素：

迁移要素	覆盖要求	如果不覆盖会怎样
架构变更清单	列出两个架构版本间所有影响编程的差异项	仅列出API级差异，忽略约束/性能差异
API兼容策略	明确哪些API跨版本可用、哪些废弃、哪些新增	废弃API未标注替代方案
逐API迁移映射表	遗留API→新API一一对应，含参数差异和约束差异	仅给出新API名未给出参数映射
迁移后验证步骤	迁移完成后如何验证功能正确性和性能基线	缺性能回归验证说明
编译选项变更	不同架构版本的编译参数差异	未说明宏定义/编译选项变更

操作要求：

跨代迁移指南的每个迁移映射条目（遗留API→新API）必须链接到API参考手册中对应的新旧API详情页
架构变更描述中涉及的编程概念变更（如新增执行模式、内存模型差异）必须链接回编程指南的对应概念章节
迁移实践中的优化技巧应链接到算子实践参考的对应优化章节
API参考手册中，每个API页面如果存在跨版本差异（废弃/新增/行为变更），必须在该页面标注并链接到跨代迁移指南对应条目

版本约束标注规范

五份文档中涉及版本差异的内容必须统一标注格式，确保开发者一眼识别适用范围：

标注格式：[适用版本：xxx]+> **注意**：xxx

标注场景	格式	示例
API页面标注适用版本	`[适用版本：2201+]`/`[适用版本：3510+]`/`[适用版本：全版本]`	`DataCopy → [适用版本：全版本]`
API已废弃	`> 已废弃（vX.X起），替代方案见→迁移指南`	`asc_mmad → 已废弃，替代见迁移指南`
约束因版本不同	`> 版本差异：2201要求32B对齐；3510要求512B对齐`	`src_stride → 版本差异见迁移指南`
性能优化方案因版本不同	`[适用版本：仅2201]`/`[适用版本：仅3510]`	`IBShare → [适用版本：仅2201]`

操作要求：

编程指南中涉及版本差异的硬件参数/约束，在参数值旁用[适用版本：xxx]标注
API参考手册每个API页面顶部用[适用版本：xxx]标注，废弃API用> **已废弃**醒目标注
算子实践参考中版本特定的优化方案，在标题或开头用[适用版本：仅xxx]标注
跨代迁移指南中每个条目使用统一格式，不自行发明新格式

三维度交叉设计

部分设计要求横跨多个维度，需同时满足：

设计要求	可获取性	可读性	完备性	具体操作
术语对照表	统一入口	按层用词	硬件校验	四列映射表（独立附录文件）
决策树/对比表	三层导航	易混区分	API关联	每个多选岔路口提供
代码示例	链接样例库	精简聚焦	分层覆盖	API页1个Minimal示例；指南片段+链接
约束框	—	前置醒目	零遗漏	约束信息在首次定义处
参数图解	—	图解化	约束可视化	stride/layout/mask类必须配图
Host/Kernel分离	找到对应侧	侧别清晰	端到端链路	标签+分节+链路图
版本约束标注	一眼识别版本范围	版本差异不混淆	迁移路径零遗漏	统一格式标注，五份文档一致
跨代迁移映射	遗留API→新API可达	迁移步骤可理解	变更清单零遗漏	逐API映射表+验证步骤+链接到API参考手册