tilelang-pass-analyzer

TileLang Pass 分析工具

⭐ 核心约束：分阶段信息获取

严格遵守以下信息获取优先级：

执行规则：

用户首次提问 Pass 功能
  ↓
1. 立即读取 reference 文件（pass-registry-*.md / pass-classification.md）
  ↓
2. 基于 reference 信息生成报告（足够回答 90% 的查询）
  ↓
3. 仅在用户追问"具体实现"、"源码细节"、"某个函数逻辑"时才读取源码

禁止行为：

• ❌ 首次回答就读取 src/transform/*.cc 源码文件
• ❌ 忽略 reference 文件中的已有信息
• ❌ 过度深入分析辅助工具类（首次回答时）
• ❌ 首次回答就并行读取 reference 和源码

---

核心工作流程

Step 1: 解析用户意图

根据用户输入判断查询类型：

---

Step 2: Pass 定位

精确匹配：

1. 读取 references/pass-registry-ascend.md 或 pass-registry-general.md
2. 根据名称获取：C++ 文件路径、Python 函数名、配置键
3. 定位到具体文件

模糊匹配策略：

1. 提取用户输入的关键词（去除 pass、transform 等通用词）
2. 在 registry 中搜索名称包含关键词的所有 pass
3. 返回候选列表（最多 5 个）：序号、名称、简述、分类
4. 提示用户选择序号或输入完整名称

分类查询：

1. 读取 references/pass-classification.md
2. 根据用户指定的分类（如"内存管理"、"同步"、"Ascend平台"）返回列表
3. 按子分类组织输出

---

Step 3: 代码分析（仅在用户追问深入时执行）

⚠️ 重要：首次提问时跳过此步骤，仅使用 reference 文件信息。

仅在用户追问以下问题时才执行此步骤：

• "某个函数的具体实现"
• "源码中的某个细节"
• "算法的具体逻辑"
• "某个配置项的作用"

按以下顺序分析 Pass 实现：

1. Python API 层

• 文件：tilelang/transform/__init__.py
• 提取：函数签名、docstring、参数

2. C++ 实现层

• 文件：src/transform/<pass_name>.cc
• 提取：
  • 文件头注释 /*! \file ... */
  • 主类名（通常继承 IRMutatorWithAnalyzer、StmtExprVisitor 等）
  • 核心方法名（如 Substitute、VisitStmt、VisitExpr）
  • 注册宏 TVM_REGISTER_PASS_CONFIG_OPTION 或 TVM_REGISTER_GLOBAL

3. 配置层

• 文件：tilelang/transform/pass_config.py
• 提取：配置键名、默认值、描述

分析方法：

- 快速浏览文件头注释，理解 pass 目标
- 找到主类的 Substitute 或 VisitXxx 方法，理解核心逻辑
- 分析算法流程：遍历 → 匹配 → 变换 → 输出
- 查看 common/ 目录下的辅助工具类

---

Step 4: 报告生成

根据查询类型选择模板：

通用风格要求：

✅ 由浅入深：先一句话总结，再逐步展开细节
✅ 伪代码精简：不超过 10 行，每个关键步骤标注函数名和备注
✅ IR 示例清晰：简化结构，标注变化点
✅ 核心函数标识：指出函数名，不引用完整代码片段
✅ 伪 IR 说明：首次使用时标注"本示例为伪 IR"，真实 TIR 格式见 ir-examples.md

---

伪代码编写规范

格式模板：

# 伪代码示例 (精简版)

输入: PrimFunc / IR Module
处理流程:
  1. 遍历 IR 结构 → VisitStmt()           # [备注: 深度优先遍历每个语句]
  2. 匹配目标模式 → MatchPattern()        # [备注: 检查是否为特定 op/buffer 类型]
  3. 执行变换操作 → TransformStmt()       # [备注: 生成新的 IR，保持语义等价]
输出: 变换后的 PrimFunc

# 关键点备注
- VisitStmt: 继承 IRMutatorWithAnalyzer，访问 Stmt 节点
- MatchPattern: 检查 buffer scope、op type 等属性
- TransformStmt: 根据规则生成新语句，可能涉及同步/地址映射等

编写规则：

• 每个关键步骤标注对应的 C++ 函数名
• 用 # [备注: ...] 说明该步骤的作用或决策依据
• 总行数不超过 10 行
• 输入/输出明确标注类型

---

IR 示例编写规范

参考 references/ir-examples.md 的格式。

基本格式：

**输入伪 IR：**
# 变换前状态（简要说明）
[简化 IR 结构]

**输出伪 IR：**
# 变换后状态（简要说明）
[简化 IR 结构，用 ← 标注变化点]

**变换要点：**
- [变化点1]
- [变化点2]

注意事项：

• 首次使用伪 IR 时，添加说明：本示例为伪 IR 格式，真实 TIR 结构见 ir-examples.md
• 只保留关键元素，不超过 10 行
• 用 ← 标注新增/修改，用 # [备注] 添加说明

---

报告模板

以下模板用于生成不同类型的 Pass 分析报告。

---

模板一：单 Pass 分析报告

# [Pass名称] 功能分析报告

## 一句话总结
> [核心功能概括，不超过 30 字]

## 功能详解

### 1. 作用与目的
[解决的问题和必要性]

### 2. 工作原理
输入: PrimFunc → 遍历 IR → 匹配模式 → 执行变换 → 输出: PrimFunc
核心函数: [函数名1]、[函数名2]

### 3. IR 变换示例
变换前: [简化IR] → 变换后: [简化IR，←标注变化]
要点: [变化点1]、[变化点2]

### 4. 使用场景与触发条件
| 项目 | 说明 |
| 适用平台 | Ascend 专用 / 通用 |
| 启用配置 | `配置键` (默认值) |
| 触发时机 | 编译阶段 |

### 5. Pass 关系与工作流
如需了解本 Pass 在 Pipeline 中的位置、与其他 Pass 的依赖关系，请使用 **tilelang-pass-workflow-analyzer** skill。

## 代码位置
| 组件 | 路径 | 核心元素 |
| Python API | `路径` | `函数名()` |
| C++ 实现 | `路径` | `类名::方法` |
| 配置项 | `路径` | `配置键` |

---

模板二：双 Pass 对比报告

# [Pass1] 与 [Pass2] 对比分析报告

## 一句话总结
> [共同点和核心差异，不超过 40 字]

## 功能对比

### 1. 作用与目的对比
| 维度 | [Pass1] | [Pass2] |
| 核心目标 | [简述] | [简述] |
| 解决问题 | [简述] | [简述] |

### 2. 工作原理对比
| Pass | 输入 | 处理 | 输出 |
| [Pass1] | ... | [函数名] | ... |
| [Pass2] | ... | [函数名] | ... |
关键差异: [差异点1]、[差异点2]

### 3. IR 变换对比
| Pass | 变换前 | 变换后 |
| [Pass1] | [IR] | [IR，←变化] |
| [Pass2] | [IR] | [IR，←变化] |

### 4. 使用场景对比
| 维度 | [Pass1] | [Pass2] |
| 适用平台 | ... | ... |
| 启用配置 | `key1` | `key2` |

### 5. 关系分析
执行顺序: [PassA] → [PassB] (原因: ...)
数据依赖: [Pass1] 提供 [数据] → [Pass2]
协作方式: 共同完成 [目标]
冲突限制: [限制条件]

## 代码位置对比
| Pass | Python API | C++ 实现 | 配置项 |
| [Pass1] | `路径` | `路径` | `key1` |
| [Pass2] | `路径` | `路径` | `key2` |

---

模板三：双 Pass 联系报告

# [Pass1] 与 [Pass2] 关系分析报告

## 一句话总结
> [协作关系概括]

## 关系分析

### 1. 作用与目的的联系
共同目标: [共同服务的目标]
分工协作: [Pass1] 负责 [职责1]，[Pass2] 负责 [职责2]

### 2. 工作原理的联系
数据流: [Pass1] → 输出: [数据] → [Pass2] 输入
依赖关系: [Pass1] 提供 [内容]，[Pass2] 需要 [内容]

### 3. IR 变换联系
Pass1 输出: ... (提供给 Pass2) → Pass2 输入: ... (来自 Pass1)
整体效果: [组合后的效果]

### 4. 执行顺序与触发
执行顺序: ... → [Pass1] → ... → [Pass2] → ...
顺序原因: [必须按此顺序的原因]

### 5. 协作场景
典型场景: [具体协作场景]
协作效果: [对比单独使用的效果]

## 代码位置
| Pass | Python API | C++ 实现 | 配置项 |
| [Pass1] | `路径` | `路径` | `key1` |
| [Pass2] | `路径` | `路径` | `key2` |

---

模板四：分类查询报告

# Pass 分类查询报告：[分类名称]

## 分类概述
> [该类 Pass 的共同特征]

## Pass 列表

### [子分类1]
| Pass 名称 | 功能简述 | 配置项 |
| [Pass1] | [描述] | `配置键` |
| [Pass2] | [描述] | `配置键` |

### [子分类2]
...

## 典型使用场景
场景1: [描述] → 推荐组合: [PassA]+[PassB]

---

模板五：模糊匹配候选列表

# Pass 匹配结果

根据关键词 "**[用户输入]**" 找到以下候选 Pass：

| 序号 | Pass 名称 | 功能简述 | 所属分类 |
| 1 | [Pass1] | [描述] | [分类] |
| 2 | [Pass2] | [描述] | [分类] |
| 3 | [Pass3] | [描述] | [分类] |

请选择你想了解的 Pass（输入序号 1-3 或完整名称）：

---

Reference 文件使用指南

本 skill 包含以下 reference 文件，按需查阅：

| 文件 | 用途 | 使用时机 | | pass-registry-ascend.md | Ascend Pass 名称→路径 | 精确匹配 Ascend pass | | pass-registry-general.md | 通用 Pass 名称→路径 | 精确匹配通用 pass | | pass-classification.md | Pass 分类索引 | 分类查询 | | ir-examples.md | IR 变换示例 | 编写 IR 示例 |

---

注意事项

1. ⭐ 分阶段信息获取：首次回答只读 reference，追问细节才读源码
2. 伪 IR 格式说明：首次使用时添加说明，后续无需重复
3. 模糊匹配：最多返回 5 个候选，按相关性排序
4. 双 Pass 报告：对比报告每节对比，联系报告每节分析关系
5. 代码位置：尽量提供行号，核心元素指函数名、类名、配置键
6. 分析深度：不深入分析辅助工具类，聚焦主类和核心方法
7. Pass 工作流查询：
   • 当用户询问 Pass 执行顺序、依赖关系、Pipeline 架构时，引导使用 tilelang-pass-workflow-analyzer skill
   • 本 skill 专注于单个 Pass 的功能分析，不深入分析 Pass 之间的关系