算子库人工智能CANN【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址https://gitcode.com/cann/pto-isa点击查看免费下载导读本文围绕 docs/mkdocs/src/manual/appendix-b-instruction-contract-template_zh.mdPTO 虚拟指令集架构手册的附录 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 单条指令文档的标准章节结构。新增指令页面与现有页面重构应使用此模板。也就是说模板同时服务于两个场景新增指令写一条新指令如TMATMUL_MX_HIF4的文档时直接按模板铺开现有页面重构对 docs/isa/ 下已有的指令页面做规范化整理时以模板为对齐基准。1.2 模板在 PTO 文档体系中的位置从 docs/mkdocs/src/manual/index_zh.md 可以看到附录 B 是《PTO 虚拟指令集架构手册》的第 13 个文档推荐阅读顺序第 13 项属于整套手册的附录部分。手册的权威来源优先级见 index 0.5 节为docs/isa/*_zh.md逐条指令语义与约束单条指令的正文include/pto/common/pto_instr.hpp公共 API 形态与重载契约单条指令的接口本手册分层模型、架构契约与一致性策略单条指令的组织规范。因此附录 B 模板是连接逐条指令语义页与手册级契约的桥梁第 6 章 指令族与契约 的 6.6 节明确要求逐条指令页面 SHOULD 按附录 B 模板组织并列出 Syntax、Operands、Semantics、Constraints、Diagnostics、Implementation-defined behavior、Compatibility notes 七项核心章节。2. B.2 必需章节顺序完整清单原文档规定每条指令页面必须按以下顺序组织章节序号章节标题一句话定位1# INSTR页面 H1 标题即指令名如TADD2## Scope范围指令族归属与设计意图3## Syntax语法PTO-AS 形式与公共 API 签名4## Operands操作数角色 / 类型 / 域 / 布局5## Semantics语义有效域迭代模型与输出语义6## Constraints约束合法性维度与后端画像限制7## Diagnostics诊断确定性拒绝条件与示例8## Implementation-defined behavior实现定义行为全部实现定义点9## Compatibility兼容性版本与迁移说明10## Examples示例可运行代码片段两点需要注意顺序本身是契约的一部分。章节顺序体现了范围 → 形态 → 操作数 → 语义 → 约束 → 诊断 → 边界 → 兼容 → 示例的叙事逻辑先交代指令是什么再给可写的形式再解释它做什么、受什么限制、出错怎么办、哪些是后端自由发挥、版本演进如何、最后给可直接复制的例子。若某章节当前无内容例如新增指令尚无 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同时提供运行时地址重载与编译期地址重载TASSIGNAddr(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 章节时建议以表格或列表逐条展开操作数角色类型类别域/形状预期位置/布局要求dst目标TileTileType::Vec, T, R, C有效域(valid_row, valid_col)行主序如 A2A3/A5 要求同时注意操作数位置语义需要与 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 的两级验证模型对应结构验证器IR 层验证操作 schema、元数、类型类别与必需属性与目标无关目标合法性验证器后端层验证选定后端画像下的dtype/layout/location/shape组合对不支持组合输出确定性诊断。在指令页面上Constraints 章节应同时写出这两类内容。以 TADD_zh.md 为例其约束按后端画像分组列出A2A3dst/src0/src1数据类型必须相同且为int32_t、int16_t、half、float之一布局必须全部行主序TileData::isRowMajorA5数据类型范围更宽额外支持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 定义了五类主诊断前缀前缀用途典型场景PARSE_*PTO-AS 文本错误token 形态、文法违规、字面量/属性非法STRUCT_*IR 结构违规操作数元数错误、必需属性缺失、类型类别不兼容LEGAL_*后端/画像合法性失败不支持的 dtype/layout/location/shape 组合、模式组合、指令变体ORDER_*同步/顺序错误缺失必需依赖边、非法同步形式、顺序契约违反BCODE_*交换/序列化失败不支持的字节码版本、section/record 畸形、未知操作码附录 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: layoutrow_major, dtypeint8 context: backend_profileA3, op_locline 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 SemanticsTile 物理形状与有效形状不一致时的 padding 写入行为如 TSCATTER 的 padding 语义。指向后端特定细节文档位置一项在仓库中的对应物包括 include/README.mdCPU 模拟器支持子集说明以及 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对应数学语义这是历史页面尚未完全重构的表现也正说明现有页面重构应使用此模板。模板章节TADD 页面实际内容对应模板要求Scope简介两个 Tile 的逐元素加法标识指令族逐元素与设计意图SyntaxC 内建接口签名PTO_INST RecordEvent TADD(...)公共 API 签名参考PTO-AS 形式待补Operands隐含于签名与约束中dst/src0/src1角色、类型、域、布局Semantics数学语义公式 有效区域迭代模型域内语义与域外行为断言失败兜底Constraints按 A2A3 / A5 / CPU_SIM 分组的实现检查 有效区域要求dtype/layout/location/shape 维度区分架构层与后端画像Diagnostics未单列约束中的断言失败即确定性拒绝条件确定性拒绝条件 期望/实际示例Implementation-defined behavior未单列域外元素为未指定枚举实现定义点并指向后端文档Compatibility未单列版本/迁移说明Examples自动Auto/ 混用静态与动态有效形状 / 手动Manual三组示例可运行示例三个值得展开的实战细节Auto 与 Manual 两种编程形态都要给示例。PTO 支持自动模式TADD(dst, src0, src1)直接对 Tile 运算与手动模式先TASSIGN把 Tile 绑定到片上地址再执行指令。模板的 Examples 章节应覆盖两种形态手动形态示例#include pto/pto-inst.hpp using namespace pto; void example_manual() { using TileT TileTileType::Vec, float, 16, 16; TileT src0, src1, dst; TASSIGN(src0, 0x1000); TASSIGN(src1, 0x2000); TASSIGN(dst, 0x3000); TADD(dst, src0, src1); }混用静态与动态有效形状的示例能体现模板对域/形状预期的要求。TileTileType::Vec, int32_t, 16, 16, BLayout::RowMajor, -1, -1表示动态有效形状16, 16表示静态有效形状二者混用是合法的前提是运行时有效区域一致。这类边界示例应写入 Examples 或 Constraints 章节。公共包含头为pto/pto-inst.hpp声明位于pto/common/pto_instr.hpp。所有示例都应通过公共包含头引入而不是直接 include 内部声明头。6. 模板与仓库工具链的联动源同步与自动化检查模板不只是写作规范它还通过仓库中的清单与工具形成闭环。附录 B 与以下三处保持源同步这也是 第 6 章 6.7 节的明确要求docs/isa/manifest.yaml每条指令的分类、摘要、图示模板、操作数契约清单include/pto/common/pto_instr.hpp指令公共 API 的唯一声明处约 134 个唯一指令 APIdocs/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 编写/重构指令文档的推荐流程结合模板与工具链推荐流程如下登记在 docs/isa/manifest.yaml 中新增instruction条目含 category、summary_en/summary_zh、diagram_template、operands、notes声明在 include/pto/common/pto_instr.hpp 中声明指令 APIPTO_INST void/RecordEvent INSTR(...)写页按附录 B 模板撰写docs/isa/INSTR.md与docs/isa/INSTR_zh.md覆盖 10 个必需章节配图确保docs/figures/isa/INSTR.svg存在并在页面中引用一致性检查要求页面必须包含 SVG 链接生成与校验运行 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 → ExamplesScope 说明了指令族归属并区分架构语义与后端补充约束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指令公共 APIinclude/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【免费下载链接】pto-isaParallel Tile Operation (PTO) is a virtual instruction set architecture designed by Ascend CANN, focusing on tile-level operations. This repository offers high-performance, cross-platform tile operations across Ascend platforms.项目地址https://gitcode.com/cann/pto-isa点击查看免费下载相关推荐Flipper Zero Unleashed10 分钟跑通你的第一个 FAP 插件Flipper Zero Unleashed10 分钟跑通你的第一个 FAP 插件 上周帮一个朋友折腾 Flipper Zero Unleashed 固件他固件嵌入式物联网智能硬件PTO 虚拟 ISA 手册解析Ascend CANN Tile 级指令集架构契约、执行模型与一致性体系PTO 虚拟 ISA 手册解析Ascend CANN Tile 级指令集架构契约、执行模型与一致性体系 导读PTOParallel Tile Operat算子库人工智能CANN猫抓 cat-catch 使用指南网页视频嗅探与 M3U8 一键合并下载猫抓 cat catch 使用指南网页视频嗅探与 M3U8 一键合并下载 想把一条微博视频存下来离线看复制链接拿到的往往是一个带 Expires 时效参数的音视频上一篇GraalVM Native Image 中的 JDK Flight RecorderJFR使用指南构建、配置与事件采集下一篇go2rtc让任意摄像机变成低延迟流媒体源转码与多协议分发一次搞定创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考