Ascend C资料贡献指南

概述

Ascend C资料体系包含五份核心文档，开发者可以通过提交PR对资料进行改进和贡献：

文档	内容	文档目录
入门教程	Ascend C概述、环境准备、快速上手（HelloWorld、首个算子）	docs/zh/guide/getting_started
编程指南	编程模型、编程范式、编译运行、硬件架构、高级编程	docs/zh/guide/programming_guide
API参考手册	接口参数、约束、示例、API关联	docs/zh/api/
算子实践参考	算子实现、性能优化、调优案例	docs/zh/guide/operator_practice/
跨代迁移兼容性指南	API兼容策略、架构变更映射、迁移步骤	docs/zh/guide/cross_gen_migration_guide/

在阅读本文档前，请确保您已了解昇腾AI处理器硬件架构。零基础开发者推荐先阅读入门教程；已有基础的开发者推荐先阅读Ascend C编程指南。

---

贡献场景

文档纠错

如果您在资料中发现描述错误、参数值不准确、约束遗漏等问题：

1. 按照社区指引新建 Documentation | 文档反馈 类Issue，指出对应文档的问题
2. 在评论框中输入 /assign 或 /assign @yourself 将该Issue分配给您
3. 修复后提交PR

文档补充

如果您发现某些内容在资料中缺失或不够完整（如缺少示例、缺少约束说明、缺少关联API说明）：

1. 新建 Requirement | 需求建议 类Issue，描述需要补充的内容
2. 按照本指南的"编写规范"完成补充
3. 提交PR

性能优化案例贡献

如果您有Ascend C算子性能优化的实战经验愿意分享：

1. 参考 operator_practice/best_practices/ 目录下已有的调优案例结构
2. 按照本指南的"性能优化案例编写规范"编写文档
3. 提交PR

---

编写规范

Ascend C资料遵循《Ascend C资料设计规范》的三个维度要求：可获取性、可读性、完备性。以下是针对常见编写场景的具体规范。

通用规范

规则	要求	错误示例	正确示例
术语分层	高层章节用抽象名，低层章节首次出现硬件名时关联高层名	概述文档直接写"数据通过UB搬入VEC"	概述文档写"数据从外部存储搬入片上存储"，低层文档写"数据从Global Memory搬入UB（片上存储）"
易混概念区分	名称相近的概念必须用对比表区分，不能靠读者自行推断	只说"四步法"不区分 Tiling流程和TPipe流水	用表格区分：四步法=编程流程，TPipe四步=流水管理范式
约束前置醒目	硬件约束在概念首次出现时标注，不放在后续章节或仅靠编译报错暴露	32B对齐约束只在assert中出现	在参数说明前用独立段落标注"约束与限制"
首次引入加链接	提到其他文档负责的内容时，首次出现加链接，后续不重复	每次提到DataCopy都加链接	仅首次提到DataCopy时加链接到API参考手册
不逆序阅读	概念B依赖概念A时，A先出现或B处有明确引用链接	API页面直接用TPipe概念但未铺垫	API页面开头放"前置知识"段，链接到编程指南对应章节

入门教程编写规范

入门教程是零基础入口，面向初次接触Ascend C的开发者，帮助其快速建立全景认知并完成首个算子。

文件职责：

文件类型	职责	禁止
概述与学习路径	全景介绍：Ascend C是什么、学习路径推荐	深入技术细节（链接到编程指南）
环境准备	实操步骤：安装、配置、验证环境	重复编程指南中的编译运行详解
快速入门/异构系统与编程模型	入门概念：Host/Device、AI Core、SIMD/SIMT选型	深入编程模型原理（链接到编程指南）
快速入门/基于SIMD编程	实践：HelloWorld + 首个算子（Add）	重复编程指南的完整编程范式
快速入门/基于SIMT编程	实践：HelloWorld + 首个算子（Gather）	重复编程指南的完整编程范式

目录结构映射（与编程指南章节对应，不含技术附录）：

入门教程目录	对应编程指南章节	入门教程定位
getting_started/	编程模型/编程模型概述	概述与学习路径
environment_setup.md	编译与运行	快速环境搭建，详细编译说明链接到编程指南
quick_start/heterogeneous_system_and_programming_model.md	编程模型/异构系统 + 编程模型/编程模型概述	入门级概念+SIMD/SIMT选型，深入链接到编程指南
quick_start/simd_programming/	编程模型/AI-Core-SIMD编程	HelloWorld+Add算子快速上手
quick_start/simt_programming/	编程模型/AI-Core-SIMT编程	HelloWorld+Gather算子快速上手

链接方向：

• 首次提到编程概念深入 → 链接到编程指南对应章节
• 首次提到某个API名称 → 链接到API参考手册
• 不需要链接到算子实践参考或跨代迁移指南（入门阶段不涉及）

编程指南编写规范

编程指南是概念权威源，其他文档遇到编程概念问题都链接回编程指南。

文件职责：

文件类型	职责	禁止
概述/总览文件	导航页：列出子主题+一句话概述+链接	展开技术细节
概念介绍文件	定义概念、解释原理、给出约束	重复其他文件内容（改为引用）
操作指南文件	代码片段+操作步骤+注意事项	重复概念定义（链接到概念文件）

编程指南到其他文档的链接方向：

• 首次提到某个API名称 → 链接到API参考手册
• 首次提到优化/实践话题 → 链接到算子实践参考
• 提到架构版本差异 → 链接到跨代迁移指南

API参考页面编写规范

API参考手册是接口详情权威源，每个API页面必须包含以下要素（按顺序）：

序号	节标题	是否必须	说明
1	产品支持情况	✅ 必须	说明API在各产品系列上的支持状态
2	功能说明	✅ 必须	涵盖功能作用、用户价值、基本用法
3	函数原型	✅ 必须	列出所有重载原型，每个原型一个代码块
4	参数说明	✅ 必须	参数名须与函数原型严格一致；模板参数与入参须分两个表格说明
5	数据类型	条件必须	若不同芯片支持的数据类型相同，无需单独章节描述差异，可随参数说明一并描述
6	返回值说明	✅ 必须	列出返回值的单位和具体取值含义
7	流水类型	条件必须	列出API的流水类型
8	约束说明	✅ 必须	约束须全面且合理
9	关键特性说明	条件必须	矩阵/向量计算类API如涉及关键硬件特性（HF32、GEMV、UnitFlag等），须有对应特性说明节；简单API可省略
10	调用示例	✅ 必须	代码片段示例 + 链接到样例库（如有对应样例，如果接口没有对应样例可省略链接）

各个结构的详细写作规范请阅读Ascend C API写作规范。

---

算子实践参考编写规范

算子实践参考是实践案例源，负责展开编程指南点到为止的实践和优化内容。

文档结构模板：

# <算子名> 算子实践参考

## 前置说明
阅读本文档前，您需要了解：xxx概念（链接到编程指南）、xxx API（链接到API参考）。

## 算子实现
### 基础版本
（代码片段 + 说明 + 链接到样例库完整示例）

### 进阶版本
（如适用：性能优化版本、多数据类型版本等）

## 性能优化
（如适用：列出针对此算子的优化手段，链接到对应优化专题）

## 常见问题
（如适用：开发过程中容易踩的坑）

关键要求：

• 有多种实现方案（如MemBase vs RegBase）的算子，开头放方案差异表+选择建议
• 代码中首次出现的API加链接到API参考手册，后续不重复
• 优化方案如果因架构版本不同，标注 [适用版本：仅xxx] 并链接到跨代迁移指南

跨代迁移页面编写规范

跨代迁移指南是兼容性权威源，负责说明架构版本间的差异和迁移路径。

迁移映射条目格式：

## <遗留API名> → <新API名>

### 变更说明
（一句话说明为什么变更、什么时候变更的）

### 参数差异对照

| 参数 | 旧接口 | 新接口 | 差异说明 |
|------|--------|--------|---------|
| ... | ... | ... | ... |

### 约束差异
（列出对齐、数据类型、元素数量等方面的差异）

### 迁移代码示例
（展示旧写法和新写法的对比）

### 迁移验证
（迁移后如何验证功能和性能）

关键要求：

• 每个映射条目必须链接到新旧API的API参考手册详情页
• 概念变更必须链接回编程指南对应章节
• 使用统一的 [适用版本：xxx] 标注格式

---

代码示例编写规范

代码片段要求

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

示例中的关键字注释

__aicore__ inline void ExampleKernel(__gm__ uint8_t* x) {  // __aicore__=核函数（Kernel）修饰符, __gm__=Global Memory地址空间
    // ...
}

---

性能优化案例编写规范

参考 operator_practice/best_practices/ 目录下的已有案例（如FlashAttention、Matmul系列）。推荐结构：

# <算子名> 性能调优案例

## 问题背景
（此算子在实际场景中的性能瓶颈是什么）

## 优化思路
（从哪些维度优化：Tiling、内存访问、流水编排、计算指令选择等）

## 优化实现
### 基线版本
（未优化的代码片段）

### 优化版本
（优化后的代码片段，逐项说明每处改动的原因）

## 性能对比

| 指标 | 基线 | 优化后 | 提升幅度 |
|------|------|--------|---------|
| 带宽利用率 | ... | ... | ... |
| 计算吞吐 | ... | ... | ... |

## 适用范围
[适用版本：xxx]（如果优化方案因架构版本不同）

---

提交PR前的自检清单

提交资料PR前，请逐项检查：

内容正确性：

• 所有硬件参数值（容量、粒度、范围）与硬件规格保持一致
• "固定值"等绝对性描述已经核实（很多"固定值"实际由配置参数决定）
• 数据通路描述与实际路径一致（不与其他文档矛盾）

约束完备性：

• 每个API的支持数据类型列表完整
• 地址对齐要求已明确（字节数和方向）
• 元素数量范围（最小值、最大值、对齐粒度）已说明
• API组合限制（互斥、必需搭配）已标注
• 跨版本差异已用 [适用版本：xxx] 标注

链接规范：

• 首次提到其他文档负责的API/概念时已加链接
• 同一概念/API后续重复出现不重复加链接
• API页面的"前置知识"段已链接到编程指南
• 涉及版本差异时已链接到跨代迁移指南

可读性：

• 术语使用与章节抽象层级匹配（高层用抽象名，低层首次出现时关联）
• 易混概念用对比表区分（不用纯文字暗示）
• 代码片段精简聚焦，有文字说明，有样例库链接
• Ascend C特有关键字有行内注释

示例质量：

• 每个API至少有1个最小可运行示例
• 示例可复制编译运行
• 覆盖多数据类型/多参数组合（不只有单一用法）

---

资料体系与链接关系

五份文档之间通过交叉链接形成导航网络，遵循"谁提到别人负责的内容，谁就加链接"原则：

入门教程 ──编程概念深入──→ 编程指南
         ──首次引入API──→ API参考手册

编程指南 ──首次引入API──→ API参考手册
        ──首次引入优化──→ 算子实践参考
        ──版本差异────→ 跨代迁移指南

API参考手册 ──前置概念──→ 编程指南
            ──版本差异──→ 跨代迁移指南

算子实践参考 ──首次使用API──→ API参考手册
            ──编程概念────→ 编程指南
            ──跨架构优化──→ 跨代迁移指南

跨代迁移指南 ──概念定义──→ 编程指南
            ──新API详情──→ API参考手册

样例库（asc-devkit/examples/）不属于资料体系，但五份文档中的代码示例均可链接到样例库。

---

更多信息

• 社区行为准则和CLA协议签署：cann-community
• Issue和PR流程：参见提交Issue/处理Issue任务
• API代码贡献指南：
  • 高阶API：asc_adv_api_contributing.md
  • 基础API：asc_basic_api_contributing.md
  • C API：asc_c_api_contributing.md