企业官网建设流程全解析

PyPTO Pass 业务流分析报告撰写指南：从模板到源码级依赖验证

【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto

导读

PyPTO（Parallel Tensor/Tile Operation 编程范式）的编译流程本质上是数十个 Pass 按照既定策略依次作用于 IR（中间表示）的过程。当需要理解某个业务场景（如冗余算子消除、切图合图、动态 shape 处理等）中"哪些 Pass 参与、按什么顺序执行、彼此如何依赖、数据与状态如何流转"时，仅靠阅读零散代码很难形成全局视图。本文以仓库内 pass-workflow-report-template.md 为骨架，结合 SKILL.md 定义的分析流程与framework/src/passes/下的真实源码，完整讲解如何撰写一份"业务概述—Pass 清单—执行流程—依赖关系—数据流转—状态变化—价值与场景"的 Pass 业务流分析报告。读完本文，你将掌握一套可直接复用的业务流分析方法论，并能对照源码验证报告中每一个依赖结论。

1. 为什么需要 Pass 业务流分析

PyPTO 把设备侧程序的优化与代码生成拆解为一系列职责单一、可独立开关的 Pass。从源码结构看，这些 Pass 按图类型划分为四个阶段（定义见 pass_type.h）：

• Tensor Graph Pass（TYPE_TENSOR_GRAPH）：作用在张量图上，负责格式推导、自动类型转换、冗余 reshape 消除等；
• Tile Graph Pass（TYPE_TILE_GRAPH）：作用在 tile 图上，负责图切分、buffer 合并、子图生成等；
• Block Graph Pass（TYPE_BLOCK_GRAPH）：作用在块图上，负责同步插入、内存复用、代码生成预处理等；
• Execute Graph Pass：面向最终执行图，负责动态属性静态化、循环轴处理等。

单个 Pass 内部逻辑容易读懂，但一个真实业务（例如"一次完整的图编译"）往往串联几十个 Pass，理解整体执行顺序、模块间数据依赖与状态传递才是难点。业务流分析报告正是把这种"纵向编译流水"转化为"横向业务视图"的标准载体：它回答三个问题——该业务涉及哪些 Pass？它们按什么顺序执行？它们之间流转了什么数据与状态？

2. 分析流程总览：三步产出报告

根据 SKILL.md 的定义，业务流分析遵循"定位文档 → 解析设计 → 源码验证 → 生成报告"的流程，可归纳为三步：

1. 定位业务流程文档：在用户指定目录及 docs 文档目录中查找与业务场景（如冗余 op 消除、切图合图、动态参数处理）相关的设计文档；
2. 解析业务流程设计：提取业务名称/目标/触发条件/适用范围，列出参与 Pass，根据 pass_manager.cpp 中的默认执行策略确定执行顺序，根据 Pass 源码所在目录判定其所处阶段；
3. 结合源代码验证：在 framework/src/passes 中查找相关 Pass 源码，验证文档描述与代码实现的一致性，并补充文档未详述的实现细节。

最后按照报告模板组织成文。模板中涉及的分析要点（业务概述、Pass 清单、执行流程、依赖关系、数据流转、状态变化、业务价值、典型场景、注意事项、相关文件）与下方各章节一一对应。

3. 报告骨架一：业务概述与 Pass 清单

报告开头用一张信息卡交代业务背景，字段包括业务名称、业务目标、触发条件与适用范围。例如分析"默认策略编译"这一业务时：

• 业务目标：将输入 Function 的 IR 依次经过格式推导、图切分、同步插入等 Pass，输出可直接进入代码生成的图；
• 触发条件：调用PassManager::RunPass且策略名为PVC2_OOO；
• 适用范围：AICore 侧默认图编译路径。

随后用表格列出全部参与 Pass（模板第 2 章），表格字段为序号、Pass 名称、阶段、主要功能。阶段划分可依据 pass_type.h 的PassType枚举，也可依据 pass_manager.cpp 中头文件按阶段分组的注释（// tensor graph pass、// tile graph pass、// execute graph pass）。Pass 的规范名称（如InferTensorFormat、GraphPartition、InsertSync）来自 pass_type.h 中的kPassNameStringMap，分析时应统一使用该映射中的字符串，保证报告与日志、配置中的名称一致。

4. 报告骨架二：执行流程与整体流程图

4.1 以默认策略为锚点确定执行顺序

报告中的执行顺序不能凭空推断，而应以 pass_manager.cpp 中注册的默认策略为权威依据：

void PassManager::RegDefaultStrategy() { RegisterStrategy("PVC2_OOO", BuildPvc2OooPassEntries()); RegisterStrategy("FunctionUnroll", BuildPassEntries({PassName::LOOP_UNROLL})); RegisterStrategy("ExecuteGraph", BuildPassEntries({PassName::DYN_ATTR_TO_STATIC, PassName::LOOPAXES_PROC})); }

其中PVC2_OOO是主策略，在 pass_manager.cpp 的BuildPvc2OooPassEntries()中按序定义了 48 个 Pass：从INFER_TENSOR_FORMAT（格式推导）开始，经REMOVE_REDUNDANT_RESHAPE、AUTO_CAST、EXPAND_FUNCTION（Tensor Graph 阶段），到GRAPH_PARTITION、N_BUFFER_MERGE、L1_COPY_IN_REUSE_MERGE（Tile Graph 阶段），再到OOO_SCHEDULE、INSERT_SYNC、GLOBAL_MEMORY_REUSE、CODEGEN_PREPROC（Block/Execute 阶段）结束。分析具体业务时，可先确认该业务走的是主策略还是仅其中若干 Pass，再据此裁剪流程。

4.2 用 mermaid 绘制整体流程图

模板第 3.1 章提供了可直接复用的 mermaidgraph TD骨架，将各 Pass 按执行顺序串联，并用subgraph将同阶段 Pass 分组。下面给出一个以PVC2_OOO策略前中后段为代表的示意（完整报告应列出该业务实际涉及的全部 Pass）：

值得注意的两点源码事实：

• 顺序不是一成不变的，pass_manager.cpp 的GetStrategyPasses会根据当前 NPU 架构（Platform::Instance().GetSoc().GetNPUArch()）过滤掉不支持当前架构的 Pass，因此报告应注明"默认策略下、当前架构为 XXX 时"这一前提；
• 阶段可提前终止：ShouldTerminateAtStage（pass_manager.cpp）允许在ExpandFunction（Tensor Graph 阶段末）或SubgraphToFunction（Tile Graph 阶段末）处按编译阶段选项提前结束流水，报告中的流程图应区分"完整流水"与"阶段截断流水"两种形态。

5. 报告骨架三：依赖关系分析

5.1 三类依赖的表达

模板第 4 章要求分别列出前置依赖、数据流与状态依赖，典型表达方式：

• 前置依赖：[Pass2] 依赖 [Pass1] 的输出；
• 数据流：[数据A]：Pass1 → Pass2；
• 状态依赖：[Pass1] 设置的状态被 [Pass4] 使用。

5.2 源码中的依赖校验机制

依赖关系并非只在报告里存在，框架在注册策略时就会校验。核心实现在 pass_dependency.cpp，机制分两类：

前置依赖（Pre-Dependency）：某 Pass 必须在若干 Pass 之后执行，注册于RegisterPreDependencies()（pass_dependency.cpp）：

registerDependency(PassName::EXPAND_FUNCTION, {PassName::AUTO_CAST, PassName::INFER_MEMORY_CONFLICT}); registerDependency(PassName::GRAPH_PARTITION, {PassName::DUPLICATE_OP, PassName::SPLIT_LARGE_FANOUT_TENSOR, PassName::SPLIT_RESHAPE, PassName::PROCESS_ATOMIC, PassName::BUILD_TREE_FROM_REDUCE}); registerDependency(PassName::SUBGRAPH_TO_FUNCTION, {PassName::GRAPH_PARTITION, PassName::REPLACE_TENSOR, PassName::PRE_GRAPH_PROCESS, PassName::INFER_DYN_SHAPE}); registerDependency(PassName::INSERT_SYNC, {PassName::OOO_SCHEDULE, PassName::COPY_OUT_RESOLVE});

例如SUBGRAPH_TO_FUNCTION依赖GRAPH_PARTITION、REPLACE_TENSOR、PRE_GRAPH_PROCESS、INFER_DYN_SHAPE四个前置 Pass——这恰好印证了"切图合图"业务中，子图生成必须发生在图切分、动态 shape 推断之后。

顺序依赖（Sequence-Dependency）：某 Pass 之后必须紧跟一段有序 Pass 序列，注册于RegisterSequenceDependencies()（pass_dependency.cpp）：

registerDependency(PassName::GRAPH_PARTITION, {PassName::GRAPH_PARTITION, PassName::REDUCE_COPY_MERGE, PassName::N_BUFFER_MERGE, PassName::L1_COPY_IN_REUSE_MERGE, PassName::INTRA_SUBGRAPH_ADAPTER, PassName::GENERATE_MOVE_OP});

这表示GRAPH_PARTITION之后应顺序跟随后续的 copy 合并、buffer 合并等切图配套 Pass。校验入口是 pass_dependency.h 中声明的CheckStrategyDependency，它在 pass_manager.cpp 的RegisterStrategy中被调用；若策略中缺少必要前置 Pass 或顺序错乱，会输出形如In strategy %s, %s is missing dependencies...的警告日志（pass_dependency.cpp）。撰写报告时，可把源码中已注册的依赖对直接作为"依赖关系"章节的事实依据，并标注其源码位置。

6. 报告骨架四：数据流转与状态变化

6.1 数据流转表

模板第 5.1 章用"数据项—来源 Pass—变化描述—目标 Pass"四列刻画数据流转。分析方法是：对每个 Pass，考察其RunOnFunction（定义于 pass.h）对Function中的 IR 做了何种变换，以及产出的数据（如新 op、新子图、buffer 分配信息）被后续哪个 Pass 消费。以PVC2_OOO策略为例，可抽象出如下典型数据流：

6.2 状态变化与状态机图

模板第 6 章要求用stateDiagram-v2表达 IR 在流水中的状态演化，并配"状态名称—初始值—设置 Pass—变化条件—使用 Pass"表格。模板提供的状态机骨架（Initial → Processing → Validated → Optimized）是通用占位，实际报告中应替换为与业务真实对应的状态。一个可参考的改写示例：

状态表的填写要点是"初始值"写 Pass 执行前 IR 的形态，"变化条件"写触发状态跃迁的 Pass 名称（即"设置 Pass"），"使用 Pass"写读取该状态的下游 Pass，从而与第 5 章的依赖关系形成闭环。

7. 报告骨架五：各 Pass 详细说明

模板第 7 章要求对每个 Pass 给出功能、输入、输出、关键逻辑、与其他 Pass 的关系五个要素。撰写时建议从以下源码点提取素材：

• 输入/输出：查看 pass.h 中Run与PreCheck/PostCheck的签名，Pass 的输入输出本质上是Function&（承载 IR），不同 Pass 的差异在于读写 IR 的哪些属性；
• 关键逻辑：定位各 Pass 在 framework/src/passes/tensor_graph_pass、framework/src/passes/tile_graph_pass、framework/src/passes/block_graph_pass 下的实现文件，描述其核心变换（如GraphPartition的切分策略、InsertSync的同步点选取）；
• 与其他 Pass 的关系：直接引用 pass_dependency.cpp 中已注册的依赖条目，避免臆造依赖；
• 架构适配：说明该 Pass 是否通过GetSupportedArches()（pass.h）限制了可运行的 NPU 架构，这决定了它在某架构下是否会被跳过。

例如SubgraphToFunction的条目可写为：功能——将切图后的子图封装为独立 Function；输入——经过GraphPartition、ReplaceTensor、PreGraphProcess、InferDynShape处理后的 tile 图；输出——封装完成的子图 Function；关键逻辑——完成子图到 Function 的边界收敛；与其他 Pass 的关系——前置依赖四个 Pass（见 pass_dependency.cpp），其执行位置同时是ShouldTerminateAtStage定义的 Tile Graph 阶段终止点（pass_manager.cpp）。

8. 报告骨架六：业务价值、典型场景与注意事项

• 业务价值（模板第 8 章）：从性能提升（如CommonOperationEliminate消除公共子表达式、NBufferMerge减少 buffer 拷贝）、资源优化（如GLOBAL_MEMORY_REUSE复用全局内存）、功能增强（如INFER_DYN_SHAPE支持动态 shape 业务）三个维度总结。注意：价值表述应以源码实现的功能为准，禁止虚构性能数据。
• 典型应用场景（模板第 9 章）：结合 SKILL 中列举的业务场景类型给出 2～3 个实例，如"冗余 op 消除业务：RemoveRedundantReshape→RemoveRedundantOp→CommonOperationEliminate的消冗链路""切图合图业务：GraphPartition及其顺序依赖链""动态参数处理业务：PreGraphProcess→InferDynShape→SubgraphToFunction"。
• 注意事项（模板第 10 章）：至少覆盖以下四点——① 执行顺序以 pass_manager.cpp 的策略注册为准，且会被架构过滤（pass_manager.cpp）和阶段截断（ShouldTerminateAtStage）影响；② 依赖结论应引用 pass_dependency.cpp 的注册数据，文档与代码不一致时以代码为准并在报告中标注；③ Pass 可被ResetAllPasses()（pass_manager.cpp）重置，跨策略复用的 Pass 状态不可假设持续保留；④ 报告中的 Pass 名称统一使用 pass_type.h 的PassNameStr映射，与日志和配置保持一致。

9. 相关文件索引

撰写报告时可快速查阅以下文件：

• 报告模板：.agents/skills/pypto-pass-workflow-analyzer/references/pass-workflow-report-template.md
• 分析流程说明：.agents/skills/pypto-pass-workflow-analyzer/SKILL.md
• Pass 类型与名称定义：framework/src/passes/pass_interface/pass_type.h
• Pass 基类接口：framework/src/passes/pass_interface/pass.h
• 策略注册与执行入口：framework/src/passes/pass_mgr/pass_manager.cpp、framework/src/passes/pass_mgr/pass_manager.h
• 依赖校验实现：framework/src/passes/pass_mgr/pass_dependency.cpp、framework/src/passes/pass_mgr/pass_dependency.h
• Pass 注册机制：framework/src/passes/pass_mgr/pass_registry.cpp
• 各阶段 Pass 实现目录：framework/src/passes/tensor_graph_pass、framework/src/passes/tile_graph_pass、framework/src/passes/block_graph_pass

【免费下载链接】pyptoPyPTO（发音: pai p-t-o）：Parallel Tensor/Tile Operation编程范式。项目地址: https://gitcode.com/cann/pypto