iree-opt 功能分类

基于 iree-opt --help 输出整理，约 400+ 个 pass 和 50+ 个 pass pipeline。

使用方法

运行单个 pass

iree-opt --pass-name input.mlir

例如运行 cse（公共子表达式消除）：

iree-opt --cse input.mlir

运行多个 pass

用 --pass-pipeline 指定完整的 pipeline，pass 之间用空格分隔：

iree-opt --pass-pipeline="cse canonicalize inline" input.mlir

嵌套 pipeline（带参数）

某些 pass 需要传参，用括号包裹：

iree-opt --pass-pipeline="builtin.module(canonicalize{max-iterations=10} cse)" input.mlir

或者逐 pass 调用（每个 pass 独立运行）：

iree-opt --cse --canonicalize input.mlir

查看 IR 变化

调试时最常用，打印每个 pass 前后的 IR：

# 打印所有 pass 之后的 IR
iree-opt --mlir-print-ir-after-all --pass-pipeline="cse canonicalize" input.mlir

# 只看特定 pass 前后的 IR
iree-opt --mlir-print-ir-before="cse" --mlir-print-ir-after="cse" --cse input.mlir

# 仅在 IR 发生变化时打印
iree-opt --mlir-print-ir-after-all --mlir-print-ir-after-change --pass-pipeline="..." input.mlir

实际示例

# 1. 只看某个 IREE pass 做了什么
iree-opt --iree-flow-canonicalize input.mlir

# 2. 组合多个 IREE pass
iree-opt --pass-pipeline="builtin.module(iree-flow-canonicalize cse iree-util-fold-globals)" input.mlir

# 3. 运行完整的 flow transformation pipeline
iree-opt --iree-flow-transformation-pipeline input.mlir

# 4. 运行 dispatch creation pipeline（形成 dispatch 区域）
iree-opt --iree-dispatch-creation-pipeline input.mlir

# 5. 查看每个 pass 的统计信息
iree-opt --mlir-pass-statistics --pass-pipeline="builtin.module(cse canonicalize inline)" input.mlir

# 6. 每个 pass 后验证 IR 正确性
iree-opt --verify-each --pass-pipeline="builtin.module(cse canonicalize)" input.mlir

查看有哪些 pass

# 列出所有已注册的 pass
iree-opt --list-passes

# 列出所有已注册的 dialect
iree-opt --show-dialects

注意事项

1. --pass-pipeline 需要顶层操作：大多数 pipeline 需要用 builtin.module(...) 包裹，因为 pass 是作用在 module 上的。
2. pass 执行顺序很重要：IREE 的 pipeline 有严格的前后依赖关系，单个调试时可以只跑某个 pass 看效果，但完整编译需要用官方 pipeline。
3. -o 指定输出文件：默认输出到 stdout，用 -o output.mlir 保存到文件。

一、IREE 核心 Dialect Pass

1.1 Flow Dialect（流变换）

1.2 Dispatch Creation（Dispatch 区域形成）

1.3 Stream Dialect（流/调度）

1.4 HAL Dialect（硬件抽象层）

1.5 Util Dialect（工具）

1.6 VM Dialect（虚拟机）

1.7 I/O Parameters

二、IREE Codegen Pass（代码生成）

2.1 Codegen 通用

2.2 GPU Codegen

2.3 LLVMCPU Codegen

2.4 LLVMGPU Codegen

2.5 SPIR-V Codegen

2.6 VMVX Codegen

2.7 ROCm/AMDGPU Codegen

三、IREE 全局优化 Pass

四、IREE 预处理 Pass

五、IREE 输入转换 Pass（前端）

5.1 StableHLO 输入

5.2 Torch 输入

5.3 TOSA 输入

5.4 其他输入

六、IREE 终 lowering Pass（到 LLVM/VM）

七、IREE 扩展 Dialect Pass

7.1 iree_linalg_ext

7.2 iree_gpu

7.3 iree_pcf（并行控制流）

7.4 iree_vector_ext

7.5 iree_tensor_ext

八、MLIR Upstream Pass

8.1 Affine Dialect

8.2 Bufferization

8.3 Linalg Dialect

8.4 Vector Dialect

Vector 相关 pass 主要整合在 iree-codegen 中。

8.5 GPU Dialect

8.6 SCF / CF / Control Flow

8.7 MemRef Dialect

8.8 Transform Dialect

8.9 其他 MLIR Upstream

九、Target Attach 和 Backend Pass

十、调试 / 测试 / 分析 Pass

十一、LLVM 后端 Pass

来自 LLVM 基础设施的大量优化选项，包括：

• Cost model: --cost-kind, --intrinsic-cost-strategy
• Inlining: --inlining-threshold, --max-iterations
• InstCombine: --instcombine-* 系列
• GVN: --enable-gvn-hoist/sink/memoryssa
• Loop 优化: 循环向量化、展开、交织、尾折叠
• Profile/PGO: --pgo-*, --sample-profile-*, --instrprof-*
• LTO/ThinLTO: --lto-embed-bitcode, --thinlto-assume-merged
• 代码发射: NEON 风格、Arm 属性、x86 分支对齐、RISC-V 属性
• 安全: --bounds-checking-single-trap, --hwasan-*

十二、Pass Pipelines（Pipeline 总览）

12.1 全局 Pipeline

12.2 输入 Pipeline

12.3 Flow / Dispatch Pipeline

12.4 全局优化 Pipeline

12.5 HAL Pipeline

12.6 Stream Pipeline

12.7 Codegen Pipeline

LLVMCPU Pipeline

LLVMGPU Pipeline

SPIR-V Pipeline

VMVX Pipeline

12.8 预处理 Pipeline

十三、MLIR/编译器通用选项

打印/调试

Pass 执行控制

目标/后端配置

十四、如何追踪 Pass 执行顺序

想逐个阅读 pass 了解其在干什么，有以下几种方法：

方法一：命令行打印 IR 变化（推荐入门用）

用 --mlir-print-ir-before-all 和 --mlir-print-ir-after-all 可以看到每个 pass 前后的 IR 变化：

# 查看每个 pass 前后的 IR（输出量很大）
iree-opt input.mlir \
  --iree-transformation-pipeline \
  --mlir-print-ir-before-all \
  --mlir-print-ir-after-all \
  --mlir-print-ir-after-change 2>&1 | less

# 只看某个特定 pass 前后的 IR
iree-opt input.mlir \
  --iree-transformation-pipeline \
  --mlir-print-ir-before=canonicalize \
  --mlir-print-ir-after=canonicalize 2>&1 | less

# 打印 pass 统计信息（了解每个 pass 做了多少事）
iree-opt input.mlir \
  --iree-transformation-pipeline \
  --mlir-pass-statistics 2>&1

# 打印 pass 执行时间
iree-opt input.mlir \
  --iree-transformation-pipeline \
  --mlir-timing 2>&1

输出中每个 pass 前会打印 // *** IR Dump Before <pass-name> ***，你可以按此关键字浏览。

方法二：使用 --dump-pass-pipeline 预览完整 pipeline

# 打印 iree-transformation-pipeline 包含的所有 pass
iree-opt --dump-pass-pipeline --pass-pipeline="builtin.module(iree-transformation-pipeline)" 2>&1

# 打印某个子 pipeline 的 pass
iree-opt --dump-pass-pipeline --pass-pipeline="builtin.module(iree-flow-transformation-pipeline)" 2>&1

这会输出 pipeline 中每个 pass 的名称和参数，但不会显示 IR 内容。

方法三：阅读源码中的 Pipeline 定义（最权威）

IREE 的完整 pass 执行顺序定义在源码中。核心文件：

主 pipeline 入口： compiler/src/iree/compiler/Pipelines/Pipelines.cpp

从源码可看到 pass 的执行顺序（phase）为：

Input → ABI → Preprocessing → GlobalOptimization
  → DispatchCreation → Flow → Stream
    → HAL → VM

每个 phase 内部又调用各自的 build pipeline 函数：

逐步追踪建议：

1. 从 Pipelines.cpp 的 buildIREEVMTransformPassPipeline 函数入手，了解整体顺序
2. 进入感兴趣的 phase（如 Flow），找到对应的 buildFlowTransformPassPipeline
3. 阅读该函数中逐个添加的 pass，理解每个 pass 的输入/输出 IR 形态

方法四：结合使用——逐个 pass 学习工作流

# 1. 先用 --dump-pass-pipeline 列出所有 pass
iree-opt --dump-pass-pipeline --pass-pipeline="builtin.module(iree-flow-transformation-pipeline)" 2>&1 > passes_list.txt

# 2. 准备一个简单的测试 IR（如一个 matmul）
# test.mlir

# 3. 对每个 pass，单独查看其前后的 IR 变化
iree-opt test.mlir --pass-pipeline="builtin.module(iree-flow-transformation-pipeline)" \
  --mlir-print-ir-before-all --mlir-print-ir-after-all 2>&1 | \
  grep -A 100 "IR Dump Before canonicalize"

# 4. 用 --verify-each 确保每个 pass 后 IR 仍然合法
iree-opt test.mlir --pass-pipeline="builtin.module(iree-flow-transformation-pipeline)" \
  --verify-each --mlir-print-ir-after-all 2>&1

学习建议

1. 从高层开始：先理解 Input → Flow → Dispatch → Stream → HAL → VM 每个阶段的职责
2. 选一个简单 pipeline：如 iree-vm-transformation-pipeline，pass 较少，容易理解
3. 准备小 IR：用极简的 .mlir 文件（几行到几十行），避免输出爆炸
4. 逐个 pass 看：用 --mlir-print-ir-before=xxx --mlir-print-ir-after=xxx 聚焦单个 pass
5. 读源码确认：对看不懂的 pass，到对应 Transforms/ 目录找 Passes.cpp 看具体实现