first commit

2026-08-20 17:20:09 +08:00
commit 8049b6f58d
14 changed files with 1649 additions and 0 deletions
@@ -0,0 +1,107 @@
+# 阶段 0：环境准备 ✅
+
+> 2026-08-13 完成。记录 IREE 环境搭建过程，方便复现。
+
+## 1. 安装方式
+
+- **venv**（不用 conda，见下），位置：`.venv/`（项目根目录）
+- **PyPI 镜像**：清华源（pypi.org 实测仅 ~17-82KB/s，太慢；清华源 ~1.1MB/s）
+  - 配置写在 `.venv/pip.conf`：`index-url = https://pypi.tuna.tsinghua.edu.cn/simple`
+
+## 2. 安装的包
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install --upgrade pip
+.venv/bin/pip install iree-base-compiler iree-base-runtime
+```
+
+| 包 | 版本 | 说明 |
+|---|---|---|
+| `iree-base-compiler` | 3.11.0 | 编译器（含 `iree-compile`、`iree-opt` 等） |
+| `iree-base-runtime` | 3.11.0 | 运行时（含 `iree-run-module`、`iree-dump-module` 等） |
+
+### ⚠️ 包名要点（重要，坑）
+
+IREE 在 2024-11 前后重构了 Python 包：
+- 老的 `iree-compiler` / `iree-runtime`（日期版本号）已**停在 20241104.1068**，不再更新
+- 新的用**语义化版本号**，包名是 `iree-base-compiler` / `iree-base-runtime`（当前 3.11.0）
+- 没有 `iree-tools` 这个包，CLI 工具直接随 base 包分发
+
+## 3. 工具链
+
+`iree-compile` / `iree-run-module` / `iree-dump-module` / `iree-opt` / `iree-import-onnx` /
+`iree-benchmark-module` 等，都在 `.venv/bin/` 下。
+
+- 编译器版本：`IREE compiler 3.11.0rc20260316`，LLVM 23.0.0git
+- 注意：`iree-run-module` 是 C 工具，**不吃 `--version`**（报 `flag not recognized`），这是正常的
+
+## 4. 最小端到端验证
+
+文件：`examples/matmul.mlir`（linalg 矩阵乘 2x4 @ 4x2 → 2x2）
+
+```bash
+# 编译
+iree-compile --iree-hal-target-backends=llvm-cpu examples/matmul.mlir -o examples/matmul.vmfb
+# 运行
+iree-run-module --module=examples/matmul.vmfb --function=matmul \
+  --input=2x4xf32=1,2,3,4,5,6,7,8 --input=4x2xf32=1,2,3,4,5,6,7,8
+# 输出
+2x2xf32=[50 60][114 140]   # 与手算一致 ✓
+```
+
+### 编译时的提示
+
+`iree-compile` 会提示「未指定 CPU 目标」，建议加 `--iree-llvmcpu-target-cpu=host`
+（针对本机 CPU 生成最优代码）或 `=generic`（通用、可移植）。学习阶段可用默认值，不影响正确性。
+
+## 5. 硬件 / 后续
+
+- CPU：16 核 x86_64
+- GPU：NVIDIA RTX 4070 Ti SUPER（驱动 580.173.02）
+  - **CUDA backend 尚未配置**：base runtime 默认只有 CPU（local-task）。CUDA/Vulkan 后端后续需要：
+    - 编译器侧：`iree-compile --iree-hal-target-backends=cuda`（base 包可能不含 CUDA 代码生成，需确认）
+    - 运行时侧：CUDA HAL driver（可能需源码编译或插件）
+  - 学习阶段先用 CPU 即可，阶段 6 深入 codegen 时再按需补 GPU 后端
+- 无 Vulkan（未装 vulkaninfo），后续要用 Vulkan 后端需先装 Vulkan 驱动/loader
+
+## 6. 常用命令速查
+
+```bash
+# 激活环境
+source .venv/bin/activate
+# 编译（CPU）
+iree-compile --iree-hal-target-backends=llvm-cpu in.mlir -o out.vmfb
+# 运行
+iree-run-module --module=out.vmfb --function=<fn> --input=<shape>xtype=vals
+# 看编译后的模块结构 / 反汇编
+iree-dump-module --module=out.vmfb
+# 看完整 lowering 管线（学习核心工具）
+iree-compile --mlir-print-ir-after-all in.mlir -o out.vmfb
+```
+
+## 7. 源码（读 vs 构建）
+
+区分三件事：
+
+| 目的 | 需要什么 | 状态 |
+|---|---|---|
+| 跑 IREE、看 pipeline | pip 二进制包 | ✅ 已装 |
+| 读 IREE 源码 | `git clone`（只读） | ✅ 已 clone |
+| 改代码 + 断点调试 | 源码构建 | ⬜ 暂缓（阶段 8 / 需要 CUDA 时） |
+
+**已 clone**（只读、浅克隆、不拉子模块）：
+
+```bash
+cd src && git clone --depth 1 --single-branch https://github.com/iree-org/iree.git
+# 位置: src/iree/（约 211MB）
+```
+
+关键目录：
+- `compiler/src/iree/compiler/Dialect/` —— Flow / Stream / HAL / VM / VMVX / LinalgExt / TensorExt / Encoding / Util
+- `compiler/src/iree/compiler/Codegen/` —— LLVMCPU / LLVMGPU / Common / Dialect
+- `runtime/src/iree/` —— hal / vm / task / async / base
+
+**从源码构建（暂缓，先了解成本）**：需 clang + ninja，几十 GB 磁盘、~1 小时编译；
+只 debug 编译器可只构建 `iree-compile` 目标。学习阶段用 `--mlir-print-ir-after-all` 看 pipeline 即可，
+不必构建。到阶段 8 实践（写自定义 pass）或要 CUDA 后端时再构建。