文件	最后提交记录	最后更新时间
docs	feat: add MX BlockMmad L0C ping-pong sample Co-authored-by: Hu1L1<chenshujian5@huawei.com> Co-authored-by: zhanghua145<zhanghua145@users.noreply.gitcode.com> # message auto-generated for no-merge-commit merge: !335 merge codex/sync-mx-l0c-pingpong-blockmmad into master feat: add MX BlockMmad L0C ping-pong sample Created-by: Hu1L1 Commit-by: Hu1L1;zhanghua145 Merged-by: cann-robot Description: ## 描述 <!--在这里详细描述你的改动，包括改动的原因和所采取的方法。--> 本 PR 为 `matmul_story` 新增 MXFP8 L0C Ping-Pong 样例，用于演示通过 MMAD 的 N 向拆分延长 L0C 地址复用间隔，减少 FIXPIPE 读取与下一 Tile MMAD 写入之间的冲突。主要改动： - 新增 `quant_matmul_mxfp8_l0cdb` 样例及 CMake 构建目标。 - 新增 `QuantMatmulMxL0cPingpong` DispatchPolicy 和对应 BlockMmad 实现。 - 样例使用 MXFP8 E4M3FN 输入、FP8 E8M0 Scale、BF16 输出。 - 输出 Tile 小于半个 L0C 时，连续 Tile 在两片 L0C 地址间 Ping-Pong。 - 输出 Tile 无法放入半个 L0C 时，在首轮和尾轮 KL1 沿 N 方向近似对半拆分。 - MMAD 循环采用 `KL1 -> N Split -> KL0`，使一个 N 子块先完成全部 KL0 累加，再切换到另一个子块。 - 最终累加通过 UnitFlag 触发 FIXPIPE，将结果直接从 L0C 搬出到 GM，不引入 UB 中转或 AIV Epilogue。 - 保留原有 L1/L0 Ping-Pong 和事件同步关系。 - 新增 `qbmmv3_mx_mmad_split.md`，说明问题背景、理论分析、适用 Shape、流水结构及 Profiling 结果。 - 新增 MMAD/FIXPIPE 冲突、循环顺序对比和 MAC 阻塞趋势三张分析图。典型 Profiling Case： - Shape：`m=4096, k=1024, n=8960, transA=false, transB=true` - 原 MX SWAT：Kernel `95.412 us`，MAC `89.948 us` - MX L0C Ping-Pong：Kernel `92.359 us`，MAC `87.459 us` - 该 Case Kernel 耗时降低约 `3.20%` - 实际 MAC 与理论值的差距由 `2.955 us` 降至 `0.466 us` 上述收益为特定环境和 Shape 下的结果，不代表所有 Shape 的固定收益。 ## 关联的Issue <!-- 如果这个PR是为了解决特定的Issue，请在这里提供Issue链接。--> <!-- 如果这个PR是为了解决特定的问题单，请在这里描述问题单单号。--> https://gitcode.com/cann/cann-samples/issues/247 ## 测试 <!--描述进行了哪些测试来验证你的改动。包括但不限于二级冒烟、算子泛化等。--> ## 文档更新 <!--如果这个PR包含文档的更新，请在这里指出。例如：更新了README.md文件。--> 新增： - `Samples/2_Performance/matmul_story/docs/qbmmv3_mx_mmad_split.md` - `docs/images/qbmmv3-mx-mad-conflict.png` - `docs/images/qbmmv3-mx-iter-diff.png` - `docs/images/qbmmv3-mx-mac-gap-vs-rounds.png` ## 类型标签 <!-- [x] 表示选中 --> - [ ] Bug修复 - [x] 新特性 - [x] 性能优化 - [x] 文档更新 - [ ] 其他，请描述： See merge request: cann/cann-samples!335	6 小时前
matmul_recipes	refactor(matmul_recipes): rename QuantMatmulTilingData to QuantMatmulMxTilingData Co-authored-by: tangweiwei<tangweiwei2@huawei.com> # message auto-generated for no-merge-commit merge: !393 merge fix/rename-quantmatmultilingdata into master refactor(matmul_recipes): rename QuantMatmulTilingData to QuantMatmulMxTilingData Created-by: tangweiwei2 Commit-by: tangweiwei Merged-by: cann-robot Description: ## 描述将 `matmul_recipes` 目录下 MX 量化矩阵乘算子使用的 `QuantMatmulTilingData` 重命名为 `QuantMatmulMxTilingData`。该 TilingData 结构体仅用于 MX 量化格式（MXFP8/MXFP4）的矩阵乘算子，原命名 `QuantMatmulTilingData` 过于宽泛，容易与 INT8、HiFP8 等其他量化类型的 TilingData 混淆。新命名 `QuantMatmulMxTilingData` 与现有文件命名 `quant_matmul_mx_tiling_*.h` 保持一致。涉及 14 个文件共 28 处引用，均为纯文本替换，不涉及逻辑变更。 ## 关联的Issue 关联Issue #264 ## 测试使用 CANN 9.1.0 toolkit（dav-3510 架构）编译验证通过： - quant_matmul_mxfp8_swat ✅ - quant_matmul_mxfp8_swat_4_buffer ✅ - quant_matmul_mxfp8_swat_weight_nz ✅ - quant_matmul_mxfp8_a_full_load ✅ 全仓库搜索确认 `QuantMatmulTilingData` 无残留。 ## 文档更新不涉及文档更新。 ## 类型标签 - [ ] Bug修复 - [ ] 新特性 - [ ] 性能优化 - [ ] 文档更新 - [x] 其他，请描述：代码重构（命名优化） --- > 此 PR 由 AI Agent 辅助生成。 See merge request: cann/cann-samples!393	3 小时前
matmul_tutorials	保持third_party下目录结构和ops-tensor一致 Co-authored-by: cry<chenruiyu4@huawei.com> # message auto-generated for no-merge-commit merge: !324 merge change_directory into master 保持third_party下目录结构和ops-tensor一致 Created-by: Crrryyyy Commit-by: cry Merged-by: cann-robot Description: ## 描述 - 将 `third_party/tensor_api` 子模块路径调整为 `third_party/ops-tensor`，使 `third_party` 下目录结构与 ops-tensor 项目名称保持一致。 - 同步更新 `.gitmodules`、README 以及样例/CMake 中对旧 `tensor_api` 路径的引用。 - 调整相关 include 与依赖路径，避免目录改名后仍引用旧路径导致构建失败。 ## 关联的Issue https://gitcode.com/cann/cann-samples/issues/199 ## 测试 - `cmake --build build --parallel` 编译无误，执行涉及修改目录下的用例无误 ## 文档更新 - 更新 `README.md` 中第三方依赖目录相关说明。 ## 类型标签 - [ ] Bug修复 - [ ] 新特性 - [ ] 性能优化 - [x] 文档更新 - [x] 其他，请描述：第三方依赖目录结构调整 See merge request: cann/cann-samples!324	1 个月前
CMakeLists.txt	refactor(cmake): extract arch check boilerplate into cann_sample_check_arch() macro Co-authored-by: songkai111<songkai16@huawei.com> # message auto-generated for no-merge-commit merge: !352 merge master into master refactor(cmake): extract arch check boilerplate into cann_sample_check_arch() macro Created-by: songkai111 Commit-by: songkai111 Merged-by: cann-robot Description: ## 描述将 29 个 sample CMakeLists.txt 中重复的架构校验样板（SUPPORTED_NPU_ARCHS + skip message）提取到 `cmake/sample_common.cmake` 的 `cann_sample_check_arch()` 宏中。每个 leaf sample 的 CMakeLists.txt 从原来的 5 行 boilerplate 缩减为 1 行宏调用： `cmake # Before (5 行) set(SUPPORTED_NPU_ARCHS dav-3510) file(RELATIVE_PATH SAMPLE_PATH ${PROJECT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}) if(NOT "${NPU_ARCH}" IN_LIST SUPPORTED_NPU_ARCHS) message(STATUS "Skip sample ${SAMPLE_PATH}: NPU_ARCH=${NPU_ARCH} is not supported") return() endif() # After (1 行) cann_sample_check_arch(dav-3510)` 变更涉及 30 个文件，净减少 144 行（185 删除，41 新增）。 ### 改动原因 49 个 sample CMakeLists.txt 中每个都独立实现了完全相同的架构校验逻辑，存在维护成本高和一致性衰减问题。这是 Issue #226 中提到的 CMake 样板代码重复问题的务实第一步。 ### 改动方法 - 新增 `cmake/sample_common.cmake`：定义 `cann_sample_check_arch()` 宏，封装架构校验逻辑 - 根 `CMakeLists.txt` 添加 `include(cmake/sample_common.cmake)` - 逐个迁移 29 个 leaf sample CMakeLists.txt（保留了三种架构配置：`dav-3510`、`dav-2201`、`dav-2201 dav-3510`） - 未修改中间 dispatcher CMakeLists.txt 和继承父级架构检查的子目录（如 matmul_tutorials） ## 关联的Issue - https://gitcode.com/cann/cann-samples/issues/226 ## 测试 - 远程 Git Hook 检查通过（推送前） - 代码逻辑等价替换，架构校验行为无变化 - 宏变量使用下划线前缀（`_cann_sample_expected_archs`、`_cann_sample_path`）避免与 sample 本地变量冲突 ## 文档更新无 ## 类型标签 - [ ] Bug修复 - [ ] 新特性 - [ ] 性能优化 - [ ] 文档更新 - [x] 其他，请描述：CMake 构建系统重构（消除重复样板代码） See merge request: cann/cann-samples!352	20 天前
README.md	Add MXFP8FP4 weight quant matmul sample Co-authored-by: xubinglin<xubinglin@huawei.com> # message auto-generated for no-merge-commit merge: !276 merge mm_mxfp8fp4_swat_version into master Add MXFP8FP4 weight quant matmul sample Created-by: xubinglin Commit-by: xubinglin Merged-by: cann-robot Description: ## 描述本 PR 新增 `matmul_recipes` 下的 MXFP8FP4 权重量化矩阵乘样例，支持 MXFP8 输入、packed MXFP4 NZ 权重、E8M0 scale、BF16 输出。主要改动包括： - 新增两个 target，通过 target 固定 2-buffer / 4-buffer 配置： - `weight_quant_matmul_mxfp8fp4` - `weight_quant_matmul_mxfp8fp4_swat_4_buffer` - 新增 MXFP8FP4 对应的 host tiling、kernel universal 特化、block scheduler、block MMAD、weight prologue 和 weight copy helper。 - 使用 compact tail split 调度有效 tile，避免 scheduler 产生 zero block shape。 - 简化 tiling data，使用 `tileShapeKL1` / `tileShapeScaleKL1` 表达 L1 K 与 scale K extent，buffer 数由 target/dispatch policy 固定。 - 新增 `gen_data.py` 与 `verify_result.py`，支持样例数据生成和 NPU 输出校验。 - 更新 CMake 安装逻辑和 README，接入 matmul recipe 样例目录。 ## 关联的Issue [#190](https://gitcode.com/cann/cann-samples/issues/190) ## 测试 - 格式化：对`.h` / `.asc` 文件执行仓库 clang-format 规则。 - 编译验证： - `cmake --build build --target weight_quant_matmul_mxfp8fp4 weight_quant_matmul_mxfp8fp4_swat_4_buffer --parallel` - Host tiling 泛化： - 2buf/4buf 合计 2,000,000 条合法 shape，全部 PASS。 - NPU 精度泛化： - 合计执行 5,000 条 resource-gated shape，全部 PASS。 - `weight_quant_matmul_mxfp8fp4`: 2,500 PASS - `weight_quant_matmul_mxfp8fp4_swat_4_buffer`: 2,500 PASS - msprof 性能扫点： - shape：`k=4096,n=8192,m=1,2,4,8,16,32,64,128,256,384,512,768,1024` - warmup 1 次，repeat 3 次。 - 两个 target 均为 39/39 PASS。 ## 文档更新 - 更新 `Samples/2_Performance/matmul_story/README.md` - 更新 `Samples/2_Performance/matmul_story/matmul_recipes/README.md` - 新增 `Samples/2_Performance/matmul_story/matmul_recipes/examples/weight_quant_matmul_mxfp8fp4/README.md` ## 类型标签 - [ ] Bug修复 - [x] 新特性 - [ ] 性能优化 - [x] 文档更新 - [ ] 其他，请描述： See merge request: cann/cann-samples!276	2 个月前

矩阵乘性能优化实践

目录结构

matmul_story/
├── CMakeLists.txt
├── README.md
├── matmul_recipes/                             # 算子实现与示例代码
│   ├── CMakeLists.txt
│   ├── README.md
│   ├── common/                                 # 公共工具函数（host/kernel）
│   ├── include/                                # 头文件 (block, kernel, policy, tile, tiling, utils)
│   ├── docs/                                   # 性能优化技术文档
│   └── examples/                               # 算子示例目录
│       ├── quant_matmul_mxfp4/                 # MXFP4 量化矩阵乘示例
│       ├── quant_matmul_mxfp8/                 # MXFP8 量化矩阵乘示例
│       ├── quant_matmul_hifp8/                 # HiFloat8 量化矩阵乘示例
│       ├── matmul_a16w16/                      # A16W16 非量化矩阵乘示例
│       └── weight_quant_matmul_mxfp8fp4/       # MXFP8FP4 量化矩阵乘示例
└── matmul_tutorials/                           # 分步教程（细目见 matmul_tutorials/README.md）
    ├── CMakeLists.txt
    ├── README.md
    ├── common/                                 # 教程共享工具函数与 tile 头文件
    ├── images/                                 # 教程流水截图
    ├── scripts/                                # 数据生成与验证脚本
    ├── 0_naive/                                # Step 0 基准
    ├── 1_pingpong/                             # Step 1 打开 Ping-Pong
    ├── 2_block_swat/                           # Step 2 SWAT
    ├── 3_last_round_tile_balance/              # Step 3 尾轮负载均衡
    ├── 4_unit_flag/                            # Step 4 UnitFlag
    ├── 5_halfl1_ping_halfl1_pong/              # Step 5 Half-L1 Ping/Half-L1 Pong
    ├── 6_scale_memory_access_coalescing/       # Step 6 Scale 访存合并优化
    └── 7_fullload/                             # Step 7 A 全载

概述

本仓库提供矩阵乘算子在昇腾AI处理器上的完整性能优化实践方案。矩阵乘法是深度学习模型中最核心的计算操作之一，其性能直接影响模型的整体训练和推理效率。

多数据类型支持：涵盖Float16、BFloat16、MXFP8、MXFP4等多种数据类型的实现示例，满足不同精度和性能需求
完整优化体系：包含性能建模、数据传输优化、计算效率优化、指令并行度优化等完整技术栈，从理论到实践全方位指导
分步教程：提供从零开始实现算子极致性能的详细指导，帮助开发者快速掌握昇腾平台高性能编程技巧

算子示例

matmul_a16w16：A16W16 非量化矩阵乘算子优化实践
quant_matmul_mxfp4：MXFP4 量化矩阵乘算子优化实践
quant_matmul_mxfp8：MXFP8 量化矩阵乘算子优化实践
quant_matmul_hifp8：HiFloat8（hifp8）矩阵乘，quant_matmul_hifp8_tt / quant_matmul_hifp8_tc 双入口说明见目录 README
weight_quant_matmul_mxfp8fp4：MXFP8FP4 量化矩阵乘算子实践

优化指南

quant_matmul_mx_performance：MX量化场景矩阵乘算子性能优化指南
weight_quant_matmul_mxfp8fp4_performance：MXFP8FP4混合精度量化矩阵乘算子性能优化指南

分步教程

各 Step 说明、Case 与流水图见 matmul_tutorials/README.md；目录树见上文 matmul_tutorials/。