# Matmul 算子分析 —— 情报信息清单

> 状态说明：✅ 已就绪（本地可读） | 🔶 待补充 | 📍 位置标注
> 根路径简写：`KB = /storage/Users/currentUser/WorkBuddy/昇腾NPU/昇腾NPU知识库/`

---

## 1. 硬件架构规格

| 情报 | 位置 | 状态 | 备注 |
|---|---|---|---|
| 昇腾950 NPU 架构白皮书（PDF 原版） | `KB/00_硬件/昇腾950_NPU架构白皮书.pdf` | ✅ | 40 页，6.3MB |
| 白皮书全文文本（可 grep） | `KB/00_硬件/昇腾950_NPU架构白皮书.txt` | ✅ **本轮新增** | 27976 字符，由 pdf-parse 提取 |
| Ascend 950PR 产品页 | `KB/00_硬件/Ascend_950PR_产品页.txt` | ✅ | 1784 TFLOPS / 128GB / 1.6TB/s / 灵衢2.0 2TB/s |
| Ascend 950DT 产品页 | `KB/00_硬件/Ascend_950DT_产品页.txt` | ✅ | 144GB / 4TB/s |
| 产品形态说明 | `KB/00_硬件/昇腾产品形态说明.md` | ✅ | 950PR=Atlas 350 加速卡 |
| 950PR 微架构解读（含数据通路 SVG） | gitea `昇腾950PR/昇腾950PR架构解读.md` | ✅ | 已提炼出 351x 架构关键数值表与数据通路变化 |

**关键硬件参数（已确认，供建模引用）**：

| 参数 | 数值 |
|---|---|
| AIC / AIV | 32 / 64（满配），28 / 56（衍生） |
| 主频 | 1.65GHz |
| Cube BF16 / TF32 / FP8 / MXFP4 | 432 / 216 / 865 / 1730 TFLOPS |
| GM 容量 / 带宽 | 128GB / 1.6TB/s（读写共享总带宽） |
| L2 容量 / 带宽 | 128MB / 5.2TB/s |
| L1 / L0A / L0B / L0C / UB | 512KB / 64KB / 64KB / 256KB（每 AIC）；512KB（每 AIV） |
| MTE1 / MTE3 | 256 BPC ≈ 422.4GB/s（单 AIC） |

---

## 2. 官方性能建模文档（任务 1 的核心公式来源）

| 文档 | 位置 | 状态 | 关键内容 |
|---|---|---|---|
| 非量化 matmul 性能优化指南 | `KB/代码仓/cann-samples/Samples/2_Performance/matmul_story/docs/matmul_performance.md` | ✅ | T_cube/T_mte2/T_mte1/T_fixp 完整公式、MTE2 vs MMAD / MTE1 vs MMAD / FIXPIPE vs MMAD 的 Bound 判定、SWAT/StreamK/UnitFlag/Double Buffer/尾轮均衡 |
| 量化 matmul（MX）性能 | `.../matmul_story/docs/quant_matmul_mx_performance.md` | ✅ | MXFP8/MXFP4 数据通路、scale 复用 |
| 权重量化 matmul 性能 | `.../matmul_story/docs/weight_quant_matmul_mxfp8fp4_performance.md` | ✅ | weightNz、MXFP8FP4 |
| mxfp4 tutorials | `.../matmul_story/docs/quant_matmul_mxfp4_tutorials.md` | ✅ | — |
| 官方调优样例源码 | `.../matmul_story/matmul_recipes/examples/`（matmul_a16w16 / a32w32 / quant_matmul_int8 / mxfp4 / mxfp8 / hifp8 / weight mxfp8fp4） | ✅ | .asc 模板 kernel（swat/streamk 等） |

---

## 3. Matmul 算子源码

### 3.1 mat_mul_v3（ops-nn，最常用 matmul，aclnnMatmul 后端）📍 完整

| 模块 | 位置 | 关键文件 |
|---|---|---|
| Host Tiling | `KB/代码仓/ops-nn/matmul/mat_mul_v3/op_host/op_tiling/arch35/` | `matmul_v3_tiling_advanced.cpp`、`matmul_v3_basic_aswt_tiling.cpp`、`matmul_v3_basic_streamk_tiling.cpp`、`matmul_v3_asw_tiling.cpp`、`matmul_v3_tiling_helper.cpp`、`matmul_v3_tiling_key.cpp` |
| Kernel（核内） | `KB/代码仓/ops-nn/matmul/mat_mul_v3/op_kernel/arch35/` | `mat_mul_v3.cpp`、`mat_mul_asw_kernel.h`、`mat_mul_bl1_full_load.h`、`mat_mul_al1_full_load.h`、`mat_mul_full_load.h`、`mat_mul_fixpipe*.h`、`mat_mul_stream_k_kernel.h`、`mat_mul_streamk_split_k.h`、`mat_mul_basic_split_k.h`、`mat_mul_pingpong_basic*.h`、`block_scheduler_{aswt,mul,multi_mul,streamk}.h` |
| API 入口 | `.../op_host/op_api/aclnn_matmul.cpp` 等 | aclnnMatmul/aclnnAddmm/aclnnMm |
| 分型配置 | `.../op_host/config/` | 各芯片 runtime_kb.json（tiling 调参表） |

### 3.2 ops-blas blasLt matmul（aclnn 底层 GEMM，含量化）📍 完整

| 模块 | 位置 | 关键文件 |
|---|---|---|
| Engine | `KB/代码仓/ops-blas/blasLt/matmul/engine/` | `matmul_engine.cpp/.h` |
| fp32 | `.../fp32/arch35/` | `matmul_fp32_host.cpp`、`matmul_fp32_kernel.cpp` |
| mxfp4 | `.../mxfp4/arch35/` | `matmul_mxfp4_host.cpp`、`matmul_mxfp4_kernel.cpp` |
| mxfp8 | `.../mxfp8/arch35/` | `matmul_mxfp8_host.cpp`、`matmul_mxfp8_kernel.cpp` |
| epilogue | `.../epilogue/arch35/` | `epilogue_alpha_beta_*` |
| tiling 公共 | `.../common/` | `quant_matmul_mx_tiling_swat_host.h`、`quant_matmul_tiling_data.h` |
| gemm（blas/gemm） | `KB/代码仓/ops-blas/blas/gemm/arch35/` | `gemm_kernel.cpp/.h`、`gemm_tiling_data.h` |

### 3.3 catlass（华为开源矩阵乘模板库，类 CUTLASS）📍

| 内容 | 位置 |
|---|---|
| 头文件 | `KB/代码仓/catlass/include/catlass/` |
| 示例 | `KB/代码仓/catlass/examples/00_basic_matmul`、`06_optimized_matmul`、`43_ascend950_basic_matmul`（950 专属示例） |

### 3.4 其他相关算子（对照参考）

- `ops-nn/matmul/` 下 32 个 matmul 变体（quant_matmul*、batch_mat_mul_v3、gemm_v3 等）——索引见 `KB/CODE_INDEX.md`
- BMM 源码锚点：`KB/代码仓/ops-nn/matmul/batch_mat_mul_v3/`（与 BMM 分析对应）

---

## 4. CANN 文档（开发/API/性能优化）

| 类别 | 位置（社区版 9.2.0-beta.1 为主） | 状态 |
|---|---|---|
| AscendC 算子开发 | `KB/CANN社区版9.2.0-beta.1/01_AscendC算子开发/` | ✅ |
| AscendC API 参考 | `KB/CANN社区版9.2.0-beta.1/02_API参考/AscendC_API/` | ✅ |
| 算子库 aclnn | `KB/CANN社区版9.2.0-beta.1/02_API参考/算子库aclnn/` | ✅ |
| 性能优化 / msProf | `KB/CANN社区版9.2.0-beta.1/03_性能优化/` | ✅ |
| 编译器（毕昇 + PTO 虚拟指令集） | `KB/CANN社区版9.2.0-beta.1/08_编译器/` | ✅ |
| 加速库 ATB | `KB/CANN社区版9.2.0-beta.1/07_加速库/` | ✅ |
| 商用版 9.0.0 / 8.5.0 | `KB/CANN商用版9.0.0/`、`KB/CANN商用版8.5.0/` | ✅ 备用对照 |

---

## 5. 待补充情报（列为后续行动）

| 情报 | 为什么需要 | 获取途径 | 优先级 |
|---|---|---|---|
| msProf 实测 profile（op_summary 等） | 校准/验证理论模型精度 | Atlas 350 真机、CANN 仿真、或官方公开性能数据 | 高 |
| GM 读写单向带宽 | 读写竞争建模需要分读写 | msProf `main_mem_read_bw/write_bw` 反推 | 高 |
| 950PR 上 matmul 的官方基准性能数据（TFLOPS 实测） | 模型验证的 ground truth | 官方性能白皮书 / 论坛 / 技术工单 | 高 |
| 源码缺失文件补拉 | 若 3.x 分析发现个别 .cpp 缺失 | `.tmp/gitcode_fetch.py cann ops-nn master matmul/mat_mul_v3` | 中 |
| CUTLASS/GEMM 建模对照（可选） | 方法论交叉验证 | 公开论文/文档 | 低 |

---

## 6. 情报就绪度总结

- 硬件规格：✅ 齐全（白皮书全文 + 解读 + 产品页）
- 性能建模公式：✅ 齐全（官方 matmul_performance.md 全套）
- 源码：✅ 基本齐全（mat_mul_v3 182 文件 + blasLt matmul 25 文件 + catlass + 官方样例）
- 文档：✅ 齐全（13097 篇 CANN 文档）
- **缺口集中在"实测数据"**：理论建模的**验证闭环**需要 msProf 实测数据，这是当前最需要补的一环，建议尽快落实真机/仿真途径。