PTO 虚拟指令集架构手册附录 B：单条指令契约模板详解与实战指南

• 算子库
• 人工智能
• CANN

导读

本文围绕 docs/mkdocs/src/manual/appendix-b-instruction-contract-template_zh.md（PTO 虚拟指令集架构手册的附录 B），系统讲解 PTO 单条指令文档的规范结构：它定义了从# <INSTR>到## Examples的 10 个必需章节及其顺序，并为每个章节给出了 MUST / SHOULD 级规范性要求。本文不仅完整复现模板正文，还结合 docs/isa/ 下的真实指令页面（如TADD、TPARTADD）、include/pto/common/pto_instr.hpp、docs/isa/manifest.yaml 与 docs/tools/ 下的生成/校验工具，说明如何把模板落到可复制、可检查、可评审的指令文档中，帮助读者掌握"写一条符合 PTO 契约的指令文档"的完整方法。

1. 模板的定位：PTO 指令文档的"标准章法"

1.1 为什么需要指令契约模板

PTO 是一个以"片级（Tile 级）操作"为核心的虚拟指令集架构（Virtual ISA, VISA）。整个指令集包含同步、逐元素运算、归约/扩展、内存操作、矩阵乘、数据搬运、复杂操作等多达十余个指令族（详见 附录 D：指令族矩阵，总计 138 条指令）。

指令数量越多，文档风格漂移的风险越大：有的页面讲语义、有的页面只给示例、有的页面混入后端实现细节。附录 B 的目的（对应原文档 B.1 节）正是：

本模板定义 PTO 单条指令文档的标准章节结构。新增指令页面与现有页面重构应使用此模板。

也就是说，模板同时服务于两个场景：

1. 新增指令：写一条新指令（如TMATMUL_MX_HIF4）的文档时，直接按模板铺开；
2. 现有页面重构：对 docs/isa/ 下已有的指令页面做规范化整理时，以模板为对齐基准。

1.2 模板在 PTO 文档体系中的位置

从 docs/mkdocs/src/manual/index_zh.md 可以看到，附录 B 是《PTO 虚拟指令集架构手册》的第 13 个文档（推荐阅读顺序第 13 项），属于整套手册的附录部分。手册的权威来源优先级（见 index 0.5 节）为：

1. docs/isa/*_zh.md：逐条指令语义与约束（单条指令的"正文"）；
2. include/pto/common/pto_instr.hpp：公共 API 形态与重载契约（单条指令的"接口"）；
3. 本手册：分层模型、架构契约与一致性策略（单条指令的"组织规范"）。

因此，附录 B 模板是连接"逐条指令语义页"与"手册级契约"的桥梁：第 6 章 指令族与契约 的 6.6 节明确要求"逐条指令页面 SHOULD 按附录 B 模板组织"，并列出 Syntax、Operands、Semantics、Constraints、Diagnostics、Implementation-defined behavior、Compatibility notes 七项核心章节。

2. B.2 必需章节顺序（完整清单）

原文档规定，每条指令页面必须按以下顺序组织章节：

两点需要注意：

• 顺序本身是契约的一部分。章节顺序体现了"范围 → 形态 → 操作数 → 语义 → 约束 → 诊断 → 边界 → 兼容 → 示例"的叙事逻辑：先交代指令是什么，再给可写的形式，再解释它做什么、受什么限制、出错怎么办、哪些是后端自由发挥、版本演进如何、最后给可直接复制的例子。
• 若某章节当前无内容（例如新增指令尚无 Compatibility 记录），也应保留章节标题，避免读者误以为遗漏，也便于后续增量补充。

3. B.3 各章节规范性要求详解

3.1 Scope（范围）

原文档要求：

• MUST 标识指令族与设计意图；
• MUST 说明本页定义的是架构语义还是后端补充约束。

这里的"指令族"指的是 docs/isa/manifest.yaml 中的category字段，如Elementwise (Tile-Tile)、Matrix Multiply、Memory (GM <-> Tile)、Complex等。写 Scope 时的实操建议：

• 首句点明指令族归属，例如"本指令属于逐元素（Tile-Tile）运算族"；
• 再写设计意图（例如"计算两个 Tile 的逐元素和"）；
• 若本页同时记录了后端特有行为（如 A2/A3 与 A5 的 dtype 差异），必须在 Scope 中显式区分：哪部分是架构语义（所有后端一致）、哪部分是后端补充约束（仅特定画像适用）。

3.2 Syntax（语法）

原文档要求：

• MUST 给出 PTO-AS 形式与公共 API 签名参考；
• SHOULD 先给出一条规范形态，再给可选变体。

在 docs/isa/ 的现有页面中，C++ 公共 API 声明统一位于 include/pto/common/pto_instr.hpp。以 TADD_zh.md 为例：

template <typename TileDataDst, typename TileDataSrc0, typename TileDataSrc1, typename... WaitEvents> PTO_INST RecordEvent TADD(TileDataDst &dst, TileDataSrc0 &src0, TileDataSrc1 &src1, WaitEvents &... events);

从中可以看到 PTO 指令 API 的两个统一特征：

• 返回RecordEvent：指令可返回事件对象，用于后续wait_flag(...)/WaitAllEvents(...)同步，体现指令对内存与向量流水线顺序的影响；
• 变长WaitEvents &... events参数：允许调用方把前置同步事件作为参数传入，这是 PTO 显式同步模型的接口形态（可参考 docs/coding/Event.md 的事件模型）。

Syntax 章节的"规范形态优先"原则，在头文件中也可见一斑：例如 pto_instr.hpp 中TASSIGN同时提供运行时地址重载与编译期地址重载（TASSIGN<Addr>(tile)），文档应把最常用的运行时形态作为规范形态，把编译期形态作为可选变体。

3.3 Operands（操作数）

原文档要求：每个操作数/结果 MUST 定义：

• 角色（dst、src0、src1等）；
• 类型类别；
• 域/形状预期；
• 位置/布局要求（如存在）。

docs/isa/manifest.yaml为每条指令都维护了operands契约列表，例如：

• TADD：["dst", "src0", "src1"]
• TPARTADD：["dst", "src0", "src1"]
• TINTERLEAVE：["dst1", "dst0", "src1", "src0"]（双输出指令）
• TPARTARGMAX：["dstVal", "src0Val", "src1Val", "dstIdx", "src0Idx", "src1Idx"]（值+索引双结果）
• TALLOC：["pipe", "gmTensor"]（通信类指令，操作数是管道与全局张量而非 Tile）

写 Operands 章节时，建议以表格或列表逐条展开：

同时注意：操作数位置语义需要与 docs/isa/conventions.md 中的术语保持一致——Tile 使用GetValidRow()/GetValidCol()表达有效区域，GM 通过pto::GlobalTensor<...>访问。

3.4 Semantics（语义）

原文档要求：

• MUST 定义有效域迭代模型（以哪个操作数的有效域为迭代域）；
• MUST 定义域内输出语义；
• MUST 明确域外行为（已定义或未指定）。

这是整份模板中最容易出现歧义的章节。PTO 的"有效区域优先规则"（见 第 6 章 6.4 节）规定：除非具体指令另有定义，语义仅在操作有效域内定义，域外结果为未指定。

以 TADD_zh.md 为正面示例，其语义章节清晰覆盖了三点：

• 迭代模型：使用dst.GetValidRow()/dst.GetValidCol()作为迭代域；
• 域内语义：对有效域内每个元素(i, j)，dst[i,j] = src0[i,j] + src1[i,j]；
• 域外行为：src0、src1、dst的运行时有效行列数必须完全一致，不匹配时触发断言失败（此时"域外"由约束兜底，不产生静默错误）。

对于有部分有效域语义的指令（如 TPARTADD_zh.md），语义章节需要更精细地定义三态：

• 两个输入都有效 → 求和；
• 仅src0有效 → 复制src0；
• 仅src1有效 → 复制src1；
• 其余未列出的有效性组合 → 实现定义。

这正是原文档"MUST 明确域外行为（已定义或未指定）"的直接体现。

3.5 Constraints（约束）

原文档要求：

• MUST 列出合法性维度：dtype、layout、location、shape、模式属性；
• MUST 区分架构层要求与后端画像限制。

PTO 的约束分层与 第 8 章 虚拟 ISA 与 IR 的两级验证模型对应：

1. 结构验证器（IR 层）：验证操作 schema、元数、类型类别与必需属性，与目标无关；
2. 目标合法性验证器（后端层）：验证选定后端画像下的dtype/layout/location/shape组合，对不支持组合输出确定性诊断。

在指令页面上，Constraints 章节应同时写出这两类内容。以 TADD_zh.md 为例，其约束按后端画像分组列出：

• A2A3：dst/src0/src1数据类型必须相同且为int32_t、int16_t、half、float之一；布局必须全部行主序（TileData::isRowMajor）；
• A5：数据类型范围更宽（额外支持uint32_t、int64_t、uint64_t、uint16_t、bfloat16_t、uint8_t、int8_t）；布局同样必须行主序；
• CPU_SIM：三个操作数 dtype 必须相同，但不额外限制行主序，各操作数按自身布局计算偏移。

这种"按画像分节"的写法直接落实了"区分架构层要求与后端画像限制"的 MUST 要求——同一指令在不同后端（A2A3 / A5 / CPU_SIM）支持面不同，正是 第 11 章 后端画像与一致性 所定义的能力门控在文档侧的体现。

3.6 Diagnostics（诊断）

原文档要求：

• MUST 定义确定性拒绝条件；
• SHOULD 提供常见失败类别的期望/实际示例。

诊断章节应与 附录 C：诊断分类体系 对齐。附录 C 定义了五类主诊断前缀：

附录 C 还给出了推荐消息字段：错误类别（稳定标识）、操作名与操作数位置、期望契约摘要、实际违规值/形状/类型/模式、定位信息。附录 C 的示例格式可以直接作为模板中 Diagnostics 章节的"期望 vs 实际"样例：

LEGAL_UNSUPPORTED_TUPLE: tmatmul operand src1 has unsupported tuple expected: layout in {fractal_a, fractal_b}, dtype in {fp16, bf16} actual: layout=row_major, dtype=int8 context: backend_profile=A3, op_loc=line 42

因此，在指令页 Diagnostics 章节中，建议为每条可确定性拒绝的约束（如 TADD 的 dtype 不匹配、有效区域不匹配）配置一条LEGAL_*或STRUCT_*类别的期望/实际示例。

3.7 Implementation-defined behavior（实现定义行为）

原文档要求：

• MUST枚举全部实现定义点；
• MUST指向后端特定细节文档位置。

实现定义行为是"架构给后端留的自由度"，与"架构定义行为"相对。PTO 的降层不变量（第 8 章 8.5 节）明确规定：降层 MUST NOT 将实现定义行为静默改写为架构定义行为。因此在文档中显式枚举实现定义点，正是防止后端擅自扩大或缩小语义范围的手段。

典型实现定义点举例：

• TPARTADD_zh.md 中"两个输入的有效性模式未明确列出的组合"；
• 有效区域之外的元素内容（除非指令显式说明为清零或保留，否则为未指定，见 conventions.md 的 Valid Region Semantics）；
• Tile 物理形状与有效形状不一致时的 padding 写入行为（如 TSCATTER 的 padding 语义）。

"指向后端特定细节文档位置"一项，在仓库中的对应物包括 include/README.md（CPU 模拟器支持子集说明）以及 docs/mkdocs/src/manual/11-backend-profiles-and-conformance_zh.md（后端画像记录实现定义行为边界）。写入模板时应给出这些链接，而不是把后端细节复制进每条指令页。

3.8 Compatibility（兼容性）

原文档要求：

• 发生行为变更时 MUST 提供版本/迁移说明；
• SHOULD 标注增量变更（additive）或破坏性变更（breaking）类别。

兼容性策略在手册层面有更完整的定义（第 8 章 8.7 节、第 9 章 9.6 节）：

• 优先采用增量 AS 演进；
• 破坏性 AS 契约变更 MUST 包含版本与迁移说明；
• 未知必需字段 MUST 验证失败；
• 已弃用结构 SHOULD 至少在一个兼容窗口内可解析。

指令页的 Compatibility 章节应记录该指令自身的变更史，例如：某 dtype 组合从 A5 画像的"不支持"变为"支持"属于增量变更；某操作数语义从"未指定"变为"已定义"属于破坏性变更。若指令从未发生过行为变更，可注明"自引入以来无行为变更"，同时保留章节位置。

4. B.4 模板正文（可直接复制）

以下是原文档提供的完整模板正文，新增指令页面时直接复制并填充：

# <INSTR> ## Scope ## Syntax ## Operands ## Semantics ## Constraints ## Diagnostics ## Implementation-defined behavior ## Compatibility ## Examples

使用说明：

• <INSTR>替换为指令名（如TADD），且必须与 docs/isa/manifest.yaml 中的instruction字段、include/pto/common/pto_instr.hpp 中的 API 名完全一致，这是源同步检查的前提（详见第 6 节）；
• 若某个章节确实无内容（如新指令无 Compatibility 记录），保留空章节标题，但不应删除，以维持 10 节结构完整；
• 模板中的英文章节名是契约的一部分，建议保持原文，便于跨语言页面（docs/isa/*.md与docs/isa/*_zh.md）对齐。

5. 模板实战：以 TADD 为例逐节对照

为了让模板更具操作性，这里以仓库中已经存在的 TADD_zh.md 为例，说明模板各章节在真实页面中如何落地。注意：现有页面与模板的章节命名存在差异（如模板的Scope对应页面中的"简介"，模板的Syntax对应"C++ 内建接口"，模板的Semantics对应"数学语义"），这是历史页面尚未完全重构的表现，也正说明"现有页面重构应使用此模板"。

三个值得展开的实战细节：

1. Auto 与 Manual 两种编程形态都要给示例。PTO 支持自动模式（TADD(dst, src0, src1)直接对 Tile 运算）与手动模式（先TASSIGN把 Tile 绑定到片上地址，再执行指令）。模板的 Examples 章节应覆盖两种形态，手动形态示例：

#include <pto/pto-inst.hpp> using namespace pto; void example_manual() { using TileT = Tile<TileType::Vec, float, 16, 16>; TileT src0, src1, dst; TASSIGN(src0, 0x1000); TASSIGN(src1, 0x2000); TASSIGN(dst, 0x3000); TADD(dst, src0, src1); }

2. 混用静态与动态有效形状的示例能体现模板对"域/形状预期"的要求。Tile<TileType::Vec, int32_t, 16, 16, BLayout::RowMajor, -1, -1>表示动态有效形状，16, 16表示静态有效形状；二者混用是合法的，前提是运行时有效区域一致。这类边界示例应写入 Examples 或 Constraints 章节。

3. 公共包含头为<pto/pto-inst.hpp>，声明位于pto/common/pto_instr.hpp。所有示例都应通过公共包含头引入，而不是直接 include 内部声明头。

6. 模板与仓库工具链的联动：源同步与自动化检查

模板不只是写作规范，它还通过仓库中的清单与工具形成闭环。附录 B 与以下三处保持源同步（这也是 第 6 章 6.7 节的明确要求）：

1. docs/isa/manifest.yaml：每条指令的分类、摘要、图示模板、操作数契约清单；
2. include/pto/common/pto_instr.hpp：指令公共 API 的唯一声明处（约 134 个唯一指令 API）；
3. docs/tools/ 下的生成与校验工具。

6.1 自动生成：附录 D 指令族矩阵

gen_virtual_manual_matrix.py 从docs/isa/manifest.yaml与pto_instr.hpp读取数据，自动生成附录 D：指令族矩阵。该脚本：

• 用正则PTO_INST\s+(?:void|RecordEvent)\s+([A-Z][A-Z0-9_]+)\s*\(从头文件抽取全部指令 API；
• 按 manifest 的category分组统计（同步、手动/资源绑定、逐元素、Tile-标量、轴归约/扩展、内存、矩阵乘、数据搬运/布局、复杂指令、核间通信等）；
• 报告头文件与 manifest 的差异（如当前 manifest 有但头文件缺失：TMATMUL_MX_HIF4、TPREFETCH_ASYNC、TQUANT_DN、TQUANT_HIF4）；
• 为每条指令生成"分类 | 指令 | 图示模板 | 操作数契约 | 语义页面"矩阵行，语义页面直接指向docs/isa/<INSTR>_zh.md。

这意味着：写指令页面前，应先确认该指令已登记在 manifest 中，且 API 已声明在头文件中，否则矩阵生成与一致性检查都会报错。

6.2 自动校验：ISA 一致性检查

check_isa_consistency.py 提供了一组可执行的一致性断言，其检查项与模板直接相关：

• 头文件指令清单 vs manifest 清单是否互相覆盖；
• manifest vsdocs/isa/英文页面是否互相覆盖；
• 中英文页面是否存在交叉链接（中文页不得引用英文页，反之亦然）；
• manifest vs 每条指令的 SVG 示意图是否齐备；
• 生成的索引文件是否同步（gen_isa_indexes.py --check）。

从脚本源码还可以看到，现有指令页面的"语法"部分要求包含### IR Level 1 (SSA)与### IR Level 2 (DPS)两个小节——这是模板Syntax章节在 PTO 三层表示（虚拟 ISA 语义 → PTO IR 结构化形态 → 字节码序列化形态，见 第 9 章）下的具体落地：指令既要有 PTO-AS 文本形式，也要有 IR 级语法描述。

6.3 编写/重构指令文档的推荐流程

结合模板与工具链，推荐流程如下：

1. 登记：在 docs/isa/manifest.yaml 中新增instruction条目（含 category、summary_en/summary_zh、diagram_template、operands、notes）；
2. 声明：在 include/pto/common/pto_instr.hpp 中声明指令 API（PTO_INST void/RecordEvent <INSTR>(...)）；
3. 写页：按附录 B 模板撰写docs/isa/<INSTR>.md与docs/isa/<INSTR>_zh.md，覆盖 10 个必需章节；
4. 配图：确保docs/figures/isa/<INSTR>.svg存在并在页面中引用（一致性检查要求页面必须包含 SVG 链接）；
5. 生成与校验：运行 gen_virtual_manual_matrix.py 刷新附录 D，运行 check_isa_consistency.py 验证覆盖与同步状态，运行 gen_isa_indexes.py 刷新指令索引。

7. 写作自检清单

提交一条指令文档前，对照模板逐项自检：

• # <INSTR>标题与 manifest 的instruction字段、头文件 API 名一致；
• 10 个必需章节齐全且顺序正确（Scope → Syntax → Operands → Semantics → Constraints → Diagnostics → Implementation-defined behavior → Compatibility → Examples）；
• Scope 说明了指令族归属，并区分架构语义与后端补充约束；
• Syntax 给出了规范形态（先规范、后变体），引用了 pto_instr.hpp 中的签名；
• Operands 对每个操作数给出了角色、类型类别、域/形状预期、位置/布局要求；
• Semantics 定义了迭代模型、域内语义、域外行为（已定义或未指定）；
• Constraints 覆盖 dtype/layout/location/shape/模式属性五个维度，并区分架构层要求与后端画像限制；
• Diagnostics 的拒绝条件可确定性复现，且提供了期望 vs 实际示例（可参考附录 C 的类别前缀与消息格式）；
• Implementation-defined behavior 枚举了全部实现定义点，并链接到后端细节文档；
• Compatibility 记录了行为变更的版本/迁移说明，并标注增量或破坏性类别；
• Examples 同时覆盖 Auto 与 Manual 形态，公共包含头为<pto/pto-inst.hpp>；
• 中英文页面无交叉链接，SVG 示意图已引用；
• 已通过 check_isa_consistency.py 校验，附录 D 矩阵已刷新。

8. 关联文档导航

• 模板原文（英）：appendix-b-instruction-contract-template.md
• 指令族与契约总述：第 6 章 指令族与契约
• 诊断分类体系：附录 C：诊断分类体系
• 指令族矩阵（由 manifest 自动生成）：附录 D：指令族矩阵
• 虚拟 ISA 与 IR 分层模型：第 8 章 虚拟 ISA 与 IR
• 字节码与工具链：第 9 章 字节码与工具链
• 后端画像与一致性：第 11 章 后端画像与一致性
• 指令语义权威来源：docs/isa/ 下的*_zh.md页面（如 TADD_zh.md、TPARTADD_zh.md）
• 指令清单与操作数契约：docs/isa/manifest.yaml
• 指令公共 API：include/pto/common/pto_instr.hpp
• 一致性校验工具：docs/tools/check_isa_consistency.py、docs/tools/gen_virtual_manual_matrix.py、docs/tools/gen_isa_indexes.py

• 算子库
• 人工智能
• CANN