diff --git a/Matmul/00_项目规划_小步快跑.md b/Matmul/00_项目规划_小步快跑.md new file mode 100644 index 0000000..6bc1f3d --- /dev/null +++ b/Matmul/00_项目规划_小步快跑.md @@ -0,0 +1,161 @@ +# Matmul 算子分析 —— 项目规划（小步快跑式） + +> 目标芯片：昇腾 950PR（32 AIC / 64 AIV，1.65GHz，GM 128GB/1.6TB/s，L2 128MB/5.2TB/s，架构版本 351x / DAV_3510） +> 项目性质：中长期，多轮迭代、严谨逻辑推导、理论建模与验证 +> 关联工程：BMM 分析（同仓 `BMM/`，已迭代多轮）——本项目的 tiling/swizzle 方法论大量复用并深化 BMM 的 `ASW_Basic`（标准 Matmul tiling）分支 +> 本地工作目录：`/storage/Users/currentUser/WorkBuddy/昇腾NPU/Matmul算子分析/` +> 同步仓库：gitea `admin/matmul-analysis` → 根目录新建 `Matmul/` + +--- + +## 0. 三大任务（来自需求） + +1. **性能理论建模**：对 Matmul 在 NPU 上的执行做理论建模，真实反映硬件执行情况、力求准确评估算子性能。给定具体 case 与算子实现所需的 tiling & swizzle 方案和参数后，能给出该芯片硬件的 profile 性能分析评估。 +2. **最优软件实现方案**：结合 NPU 架构规格与算子数据流，通过有条理的分析和公式推导，给出任意 case 的 matmul 输入后的最优实现方案（核心是 tiling & swizzle 方案）。 +3. **源码对比与改进建议**：对比 Matmul 算子当前源码实现，给出软件改进点；结合 top case，针对 NPU 架构给出下一代硬件的具体改进建议。 + +三任务之间的依赖关系： + +``` +任务1（性能模型） + │ 提供"评判标准"：任何 tiling/swizzle 方案都能被评估 + ▼ +任务2（最优方案） + │ 用任务1的模型反向推导最优参数 + ▼ +任务3（源码对比/硬件建议） + 以任务1的模型 + 任务2的最优解为标尺，衡量源码差距 → 软件改进点 → 硬件改进点 +``` + +--- + +## 1. 情报信息清单 + +> 详细到文件级的情报清单见 `01_情报清单.md`。这里只做概览。 + +### 1.1 已就绪（本地知识库，可直接用于分析） + +| 类别 | 位置 | 状态 | +|---|---|---| +| 硬件架构白皮书全文 | `昇腾NPU知识库/00_硬件/昇腾950_NPU架构白皮书.pdf` + **新提取 `...白皮书.txt`（40 页全文，可 grep）** | ✅ 本轮完成提取 | +| 950PR/950DT 产品页与产品形态 | `昇腾NPU知识库/00_硬件/*.txt` `.md` | ✅ | +| 950PR 微架构解读（含数据通路 SVG） | gitea `昇腾950PR/昇腾950PR架构解读.md` | ✅ | +| CANN 官方文档全套 | `昇腾NPU知识库/CANN社区版9.2.0-beta.1`（5512 页）、`商用版9.0.0`（4483 页）、`8.5.0`（3100 页） | ✅ | +| **官方性能建模公式文档** | `昇腾NPU知识库/代码仓/cann-samples/Samples/2_Performance/matmul_story/docs/matmul_performance.md`（T_cube/T_mte2/T_mte1/T_fixp 完整公式）＋ `quant_matmul_mx_performance.md`、`weight_quant_matmul_mxfp8fp4_performance.md` | ✅ | +| **Matmul v3 完整源码** | `昇腾NPU知识库/代码仓/ops-nn/matmul/mat_mul_v3/`（182 文件：op_host tiling + op_kernel/arch35 60 文件） | ✅ | +| **blasLt matmul 完整 kernel** | `昇腾NPU知识库/代码仓/ops-blas/blasLt/matmul/`（engine/epilogue/fp32/mxfp4/mxfp8 共 25 文件） | ✅ | +| 矩阵乘模板库 catlass | `昇腾NPU知识库/代码仓/catlass/`（含 43_ascend950_basic_matmul 示例） | ✅ | +| 官方调优样例（.asc kernel） | `昇腾NPU知识库/代码仓/cann-samples/.../matmul_story/matmul_recipes/`（a16w16/a32w32/quant 各模板） | ✅ | +| 算子→代码映射索引 | `昇腾NPU知识库/CODE_INDEX.md`（matmul 32 个变体） | ✅ | + +### 1.2 待补充（列为后续小步，见 3.） + +1. **msProf 实测数据**：950PR 真机（Atlas 350 加速卡）或仿真环境的 profile 数据，用于校准/验证理论模型精度。当前环境无 NPU，需明确获取途径（真机、CANN 仿真、或官方公开性能数据）。 +2. **读写带宽单向值**：官方只公开 GM 总带宽 1.6TB/s，读写单向带宽需实测或依据 msProf 反推。 +3. **源码中部分分支的完整实现**：本地锚点基本齐全，但若分析发现个别文件缺失，用 `.tmp/gitcode_fetch.py` 从 gitcode 补拉。 +4. **竞品参照（可选）**：NVIDIA CUTLASS/TRT-LLM 的 GEMM 建模思路，用于方法论交叉验证（仅作对照，不对外引用内部资料）。 + +--- + +## 2. 与 BMM 分析的关系（复用与边界） + +BMM 分析已产出的可复用资产： +- `T_total = max(T_MMAD, T_MTE2, T_MTE1, T_FIXPIPE [, T_REDUCE])` 的建模骨架与公式 +- 硬件参数表（L0A/L0B/L0C/L1/UB/MTE 带宽/L2 替换机制） +- 分支体系（FoldBatchToMatMul / MergeBatch / IterBatch / StreamK / ASW_Basic） +- 长宽比、baseM/baseN、SingleCoreM/N、尾轮重切、UnitFlag 等关键结论 + +**边界**： +- BMM 的差异化难点在 **batch 维切分与分支决策**；Matmul 的差异化难点在 **单矩阵乘的 tiling 深度优化 + swizzle（SWAT/StreamK/SplitK）编排 + L2 复用 + 量化（MXFP4/MXFP8/HiF8）**。 +- 本项目聚焦 `[M,K]×[K,N]→[M,N]` 单矩阵乘，把 BMM 里 `ASW_Basic` 的"标准 Matmul tiling"作为起点向下钻，而不是重复 BMM 的分支决策。 + +--- + +## 3. 小步快跑规划（每步可交付、可验证） + +> 原则：每一步产出**独立可评审的文档/工具/结论**，先跑通主干再迭代细化；模型必须能被验证（有对标 case 或公式自洽性检验）。 + +### Phase 0 —— 情报准备与规划（本轮）✅ +- [x] 梳理情报清单、确认本地源码/文档完整性 +- [x] 提取 950 白皮书全文（可 grep） +- [x] 产出本规划文档 + 情报清单，同步 gitea `Matmul/` + +### Phase 1 —— 性能理论建模（任务 1） + +| 步 | 交付物 | 验证方式 | +|---|---|---| +| 1.1 硬件参数与数据通路模型 | `Matmul/1_性能模型/1.1_硬件参数与Roofline模型.md`：峰值算力、各级带宽、算术强度、Roofline | 与白皮书/官方公式数值自洽 | +| 1.2 单核流水线建模 | `1.2_单核流水线建模.md`：T_cube/T_mte2/T_mte1/T_fixp 完整推导 + baseM/baseN/baseK 影响分析 | 与官方 `matmul_performance.md` 公式对齐 | +| 1.3 多核并行 + swizzle 建模 | `1.3_多核并行与Swizzle建模.md`：核间切分、L2 命中率、SWAT 窗口、重复搬运量 | 公式闭合（重复搬运量与 SWAT 窗口关系） | +| 1.4 profile 评估器（工具） | `1.4/profile_model.py`（或 .mjs）：输入 case + tiling&swizzle 参数 → 输出各流水耗时与瓶颈判定 | 单测：已知 case 手算对照 | +| 1.5 模型校准与验证 | `1.5_模型验证报告.md`：用官方样例/已知数据校准，量化误差 | 误差 < 15%~20% 量级 | + +### Phase 2 —— 最优软件实现方案（任务 2） + +| 步 | 交付物 | 验证方式 | +|---|---|---| +| 2.1 分支与模板体系 | `2_最优方案/2.1_模板体系.md`：SWAT/StreamK/SplitK/DPSK 等模板的数据流与适用域 | 与源码策略优先级对照 | +| 2.2 baseM/baseN/baseK 最优推导 | `2.2_Tiling参数最优推导.md`：由瓶颈方程反解最优分块 | 用 1.4 评估器验证推导结论 | +| 2.3 swizzle 编排最优推导 | `2.3_Swizzle编排最优推导.md`：核分配顺序、L2 切分、尾轮重切 | 同上 | +| 2.4 任意 case 决策算法 | `2.4_最优方案决策.md`：case 输入 → 最优 tiling&swizzle 的完整决策流程 | 覆盖典型 case 集（方阵/瘦长/大K/量化） | + +### Phase 3 —— 源码对比与改进建议（任务 3） + +| 步 | 交付物 | 验证方式 | +|---|---|---| +| 3.1 源码 tiling/swizzle 逆向 | `3_源码对比/3.1_mat_mul_v3源码解析.md`（matmul_v3_*_tiling.cpp / block_scheduler_*.h） | 与源码逐行对照 | +| 3.2 理论与源码差异 → 软件改进点 | `3.2_软件改进点.md` | 每条改进点给理论依据 | +| 3.3 top case 与硬件改进建议 | `3.3_下一代硬件改进建议.md`（结合 top case） | 每条建议映射到架构瓶颈 | + +--- + +## 4. 目录结构约定 + +### 4.1 本地（`Matmul算子分析/`） + +``` +Matmul算子分析/ +├── req.txt # 需求原文 +├── 00_项目规划_小步快跑.md # 本规划 +├── 01_情报清单.md # 情报清单（文件级） +├── 1_性能模型/ # 任务1 +├── 2_最优方案/ # 任务2 +├── 3_源码对比/ # 任务3 +└── case库/ # 典型 case（shape/dtype 集合） +``` + +### 4.2 gitea（`Matmul/`） + +``` +Matmul/ +├── README.md # 项目总览 + 三大任务 + 目录索引 +├── 00_项目规划_小步快跑.md +├── 01_情报清单.md +├── 1_性能模型/ +├── 2_最优方案/ +└── 3_源码对比/ +``` + +### 4.3 文档规范 + +- 每篇分析文档 **markdown + html 双格式**交付（与 BMM 一致），html 用于易读性发布。 +- 文中引用外部资料只引用**有在线链接的公开内容**（昇腾官网 / gitcode / gitea 仓库内文件），不引用本地绝对路径。 +- 推导必须**逻辑连贯、公式完整、结论可被质疑**；每个"结论"都要写清假设与适用边界。 + +--- + +## 5. 关键风险与依赖 + +| 风险 | 影响 | 缓解 | +|---|---|---| +| 无真机/仿真，缺 msProf 实测 | 模型精度难以实证 | 先用官方公开样例数据校准；争取 Atlas 350 真机或 CANN 仿真环境 | +| GM 读写单向带宽无公开值 | 模型参数不确定 | 以总带宽 + 读写比例假设建参，标注可替换点，实测后回填 | +| 源码个别文件本地缺失 | 分析中断 | `.tmp/gitcode_fetch.py` 补拉，或 gitea 内同步源码锚点 | +| 硬件细节（L2 替换/MTE 微架构）文档不细 | 建模偏差 | 用 msProf 反推 + 白皮书交叉印证 | + +--- + +## 6. 下一步（下一轮迭代入口） + +1. 从 **Phase 1.1** 开始：输出硬件参数与 Roofline 模型（把 950PR 架构解读里的数值表 + 白皮书全文规格，整理成可复用的"硬件参数表"）。 +2. 同步产出 `case库/`：定义第一批典型 case（覆盖方阵/瘦长/大K/低精度），作为 1.4 评估器与 Phase 2 的公共输入。