@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.4

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/comm_shmem.md

@@ -0,0 +1,280 @@
+# 通信层（SHMEM / UDMA）参考
+
+本文档承载 MC2 skill 的"通信子能力"。涵盖：SHMEM API 目录、host/device 侧用法、禁止 HCCL 清单的执行细则、扩展其他通信原语（AllReduce / ReduceScatter / AllGather）的思路。
+
+> 官方文档：<https://shmem-doc.pages.dev/>。本文件不重抄官方 API；只记录参考工程用到的子集 + MC2 场景下的使用要点。
+>
+> **接口来源核验**（基于 `gitcode.com/cann/shmem` 仓库源码核对，仓库 version v1.5.0 系列）：
+>
+> | 接口 | 仓库证据（`include/` 下头文件） |
+> |------|--------------------------------|
+> | `aclshmemx_init_attr` | `host/init/shmem_host_init.h:66` |
+> | `aclshmemx_uniqueid_t` / `aclshmemx_init_attr_t` / `ACLSHMEMX_INIT_WITH_DEFAULT` | `host/shmem_host_def.h:106-111`、`host/shmem_host_def.h:164-181` |
+> | `aclshmem_align` / `aclshmem_free` | `host/mem/shmem_host_heap.h:53,62` |
+> | `aclshmem_my_pe` / `aclshmem_n_pes`（device 侧） | `device/team/shmem_device_team.h:27,35` |
+> | `aclshmem_ptr` | device: `device/gm2gm/engine/shmem_device_mte.h:26`；host: `host/data_plane/shmem_host_rma.h:74` |
+> | `aclshmemx_udma_put_nbi` / `aclshmemx_udma_quiet` | `device/gm2gm/engine/shmem_device_udma.h:63,106`（实现 `src/device/gm2gm/engine/shmem_device_udma.hpp`） |
+> | `aclshmem_barrier_all` | device: `device/gm2gm/shmem_device_cc.h:76`；host: `host/data_plane/shmem_host_cc.h:49` |
+> | `ACLSHMEM_DATA_OP_UDMA` / `ACLSHMEM_DATA_OP_MTE` | `host_device/shmem_common_types.h:81-86` |
+> | `L2_CACHELINE_SIZE = 512` | `host_device/shmem_common_types.h:166-168` |
+>
+> 平台限制：UDMA 引擎仅在 `__NPU_ARCH__ == 3510`（Ascend 950/A5）上启用（`src/device/gm2gm/engine/shmem_device_udma.hpp:21-24`），与 [`../capability-declaration.md`](../../capability-declaration.md) 中 dav-3510 × UDMA 的已验证路径一致。
+
+---
+
+## 1. SHMEM 初始化（host 侧）
+
+参考工程的 host 侧初始化在 `src/all_to_all_matmul.cpp::runAllToAllMatmul`，按以下顺序：
+
+```cpp
+// 1. ACL 标准 init
+ACL_CHECK(aclInit(nullptr));
+ACL_CHECK(aclrtSetDevice(deviceId));
+ACL_CHECK(aclrtCreateStream(&stream));
+
+// 2. SHMEM init（关键）
+aclshmemx_init_attr_t attributes;
+aclshmemx_uniqueid_t defaultFlagUid;
+test_set_attr(rankId, rankNum, localMemSize, ipport, defaultFlagUid, &attributes);
+attributes.option_attr.data_op_engine_type = ACLSHMEM_DATA_OP_UDMA;  // 选 UDMA 引擎
+ACL_CHECK(aclshmemx_init_attr(ACLSHMEMX_INIT_WITH_DEFAULT, &attributes));
+
+// 3. 分配 SHMEM 空间（所有 rank 对齐）
+void *shmemSpace = aclshmem_align(PACKAGE_SIZE, SHMEM_SPACE_SIZE);  // 512B 对齐，1 GB
+```
+
+### 多 rank 启动
+
+参考工程用 `fork` 启动多进程（`src/all_to_all_matmul.cpp::main`），每个进程对应一个 rank：
+
+```cpp
+for (int rankId = 0; rankId < rankNum; ++rankId) {
+    pid_t pid = fork();
+    if (pid == 0) {
+        // 子进程：setDevice(rankId) + SHMEM init + 跑 kernel
+        runAllToAllMatmul(rankNum, rankId, ...);
+        exit(ret);
+    }
+}
+```
+
+`tcp://127.0.0.1:8998` 是 rank 间发现的默认地址，可在 `test_set_attr` 里改。
+
+### 关键参数
+
+| 参数 | 含义 | 参考工程取值 |
+|------|------|------------|
+| `SHMEM_SPACE_SIZE` | 单卡 SHMEM 空间大小 | `1024 * 1024 * 1024` (1 GB) |
+| `PACKAGE_SIZE` | SHMEM 对齐粒度（`aclshmem_align` 第一参） | `512` bytes。shmem 仓库已定义 `L2_CACHELINE_SIZE = 512`（`include/host_device/shmem_common_types.h:166-168`），参考工程取该值对齐 |
+| `ACLSHMEM_DATA_OP_UDMA` | 数据搬运引擎选 UDMA（不是 RDMA） | 必须选 UDMA |
+
+### 资源释放
+
+```cpp
+aclshmem_free(shmemSpace);
+ACL_CHECK(aclshmem_finalize());
+ACL_CHECK(aclrtDestroyStream(stream));
+ACL_CHECK(aclrtResetDevice(deviceId));
+ACL_CHECK(aclFinalize());
+```
+
+顺序不能错：先 free SHMEM 空间，再 finalize SHMEM，再销毁 stream/device。
+
+---
+
+## 2. SHMEM 设备侧 API 目录
+
+参考工程在 `include/kernel/all_to_all_comm_udma.h` 用到的设备侧 API：
+
+| API | 作用 | 调用位置 |
+|-----|------|---------|
+| `aclshmem_n_pes()` | 返回总 rank 数 | `InitParams` |
+| `aclshmem_my_pe()` | 返回当前 rank ID | `InitParams` |
+| `aclshmem_ptr(shmemSpace, pe)` | 把对称地址 `shmemSpace` 翻译到 `pe` 视角的 GM 地址（传本卡 rankId 即本卡基地址） | `GetDataAddrGm` / `GetScaleAddrGm` |
+| `aclshmemx_udma_put_nbi(dst, src, ubuf, size, remoteRank)` | 非阻塞 Put：本地 src → 远程 dst | `PutSegmentToRank` |
+| `aclshmemx_udma_quiet(remoteRank)` | 等本次 Put 数据已到达对端 PE（completed） | `PutSegmentToRank` |
+| `aclshmem_barrier_all()` | 全卡 Barrier（跨核同步点） | `BarrierAll` |
+
+### Put 的 dst 地址语义
+
+UDMA Put 的 `dst` 是**本 rank 视角下本 rank 的 SHMEM 对称地址**。SHMEM 采用对称分配模型：所有 rank 通过 `aclshmem_align` 分配等大空间，本 rank 通过 `aclshmem_ptr(shmemSpace, rankId_)`（注意第二个参数是**本卡 rankId**）拿到本卡的 SHMEM 基地址。UDMA 引擎根据 `remoteRank` 参数将写入数据翻译到对端 rank 的对应地址。本 rank 不需要知道对端物理地址。
+
+```cpp
+// all_to_all_comm_udma.h::GetDataAddrGm
+GM_ADDR baseAddr = (GM_ADDR)(aclshmem_ptr(shmemContextGM_, rankId_));
+return baseAddr + bufferId * bufferBlockSize_;
+```
+
+注意 `aclshmem_ptr` 第二个参数是 `rankId_`（**本卡自己的 rank**），不是 remoteRank。本卡视角下本卡的 SHMEM 基地址就是其他卡 Put 过来的数据落点。UDMA 引擎负责地址翻译，开发者只需对本卡对称地址写入数据并指定 remoteRank。
+
+### ubuf 参数
+
+`aclshmemx_udma_put_nbi` 的第三个参数 `(__ubuf__ uint8_t*)nullptr` 在参考工程中始终为 `nullptr`。该参数为兼容 API 而保留的 UB 缓冲参数，UDMA 实现中直接 `(void)buf` 忽略（`src/device/gm2gm/engine/shmem_device_udma.hpp` 中 `aclshmemx_udma_put_nbi` 实现），因此传 `nullptr` 合法；MC2 的大块 Put 直接走 GM→GM。
+
+---
+
+## 3. AllToAll 通信实现剖析
+
+参考工程的 `AllToAllComm` 类（`include/kernel/all_to_all_comm_udma.h`）实现了"All rank 互发 M 段"的 AllToAll 语义。核心逻辑：
+
+### 3.1 Put 数据
+
+```cpp
+// PutToAllRanks: 当前 rank 把自己的 M 段发给所有其他 rank
+template<typename XType>
+__aicore__ inline void AllToAllComm<XType>::PutToAllRanks(
+    uint64_t srcMOffset, uint64_t mSize, uint32_t bufferId)
+{
+  // 每个 Block 负责发送到对应的 remoteRank，避免卡间竞争
+  if ((AscendC::GetBlockIdx() < rankSize_) && (AscendC::GetBlockIdx() != rankId_)) {
+    PutSegmentToRank(AscendC::GetBlockIdx(), srcMOffset, mSize, bufferId);
+  }
+  BarrierAll();  // 等所有卡完成 Put
+}
+```
+
+**关键设计**：不是单个 Block 串行 Put 给所有 remoteRank，而是多 Block 并发——Block i 负责发给 remoteRank i。这样 UDMA 引擎能并行下发多条指令。
+
+### 3.2 Put 单段
+
+```cpp
+template<typename XType>
+__aicore__ inline void AllToAllComm<XType>::PutSegmentToRank(
+    uint32_t remoteRank, uint64_t srcMOffset, uint64_t mSize, uint32_t bufferId)
+{
+  GM_ADDR remoteWinAddr = GetDataAddrGm(bufferId);  // 本 rank 视角下自己的 SHMEM
+  // 注意：Put 的 dst 是"本 rank 视角下本 rank 的 SHMEM 地址"，
+  //       UDMA 引擎会把这个地址映射到 remoteRank 的 SHMEM；
+  //       但 SHMEM 的地址翻译是按 rank 偏移做的，所以要加上 rankId 的偏移
+  uint64_t dstDataOffset = rankId_ * commMSize_ * bytesPerMRow_;  // 对端按 srcRank 区分
+  uint64_t srcDataOffset = remoteRank * M_ * bytesPerMRow_ + srcMOffset * bytesPerMRow_;
+  uint64_t dataSize = mSize * bytesPerMRow_;
+
+  aclshmemx_udma_put_nbi(
+    remoteWinAddr + dstDataOffset,
+    inputDataAddr_ + srcDataOffset,
+    (__ubuf__ uint8_t*)nullptr,
+    dataSize,
+    remoteRank);
+  aclshmemx_udma_quiet(remoteRank);  // 确保数据已到达对端 PE
+}
+```
+
+**地址语义陷阱**：
+- `dstDataOffset = rankId_ * commMSize_ * bytesPerMRow_`：对端收数据时，按"我从哪个 rank 来"放到对应位置，避免多 rank 数据互相覆盖；
+- `srcDataOffset = remoteRank * M_ * bytesPerMRow_ + srcMOffset * bytesPerMRow_`：本 rank 的 A 矩阵逻辑上按 `remoteRank` 分段，第 i 段是要发给 remoteRank=i 的数据。
+
+### 3.3 Scale 一次性 Put
+
+Scale（量化系数）不参与 M 轴流水，参考工程在 AIV 启动时一次性 Put 全部 Scale：
+
+```cpp
+// all_to_all_matmul_impl.h::AllToAllProcess 开头
+allToAllComm_.PutScaleToAllRanks(0, axisM_);  // 一次 Put 全 M 行的 Scale
+```
+
+因为 Scale 数据量小（`M * CeilDiv(K, 64) * 2` bytes，相比 A 的 `M * K` 小 32 倍），不值得做流水。
+
+---
+
+## 4. 扩展其他通信原语
+
+MC2 算子不限于 AllToAll。下面给出扩展思路（参考工程未直接实现，但架构允许）：
+
+### 4.1 AllReduce
+
+AllReduce = AllToAll + Reduce。两步：
+1. AllToAll 把每卡的段发到所有其他卡（复用参考工程的 `PutToAllRanks`）；
+2. 接收端做本地 reduce（AIV 用 Vector 指令做加法）。
+
+```cpp
+// 伪代码：AllReduce 通信层
+template<typename XType>
+__aicore__ inline void AllReduceComm::ReduceAllRanks(uint32_t bufferId) {
+  // bufferId 处的数据 layout: [rankSize][reduceLen]
+  // 用 AIV Vector 把 rankSize 个段加到一起
+  // ...（用 AscendC::Add 做 UB 内 reduce）
+}
+```
+
+### 4.2 ReduceScatter
+
+ReduceScatter = AllReduce + 每卡只保留一段。在 AllReduce 基础上，每张卡只 Reduce 自己负责的那段，输出落 GM。
+
+### 4.3 AllGather
+
+AllGather = 每卡 Put 自己段给所有其他卡，但不 reduce。本质就是 AllToAll 不带 reduce 步骤——参考工程的 `PutToAllRanks` 已经覆盖。
+
+### 4.4 自定义原语注意点
+
+- 必须保留 `aclshmemx_udma_quiet(remoteRank)` 调用，确保数据已到达对端 PE；
+- Barrier 类操作用 `aclshmem_barrier_all()`；`aclshmemx_barrier_all_vec` 已废弃（shmem 仓库 `device/gm2gm/shmem_device_cc.h:85,93` 标记 `[[deprecated]]`，提示改用 `aclshmem_barrier_all`），不能用 HCCL 的同步原语；
+- 跨核同步（AIV↔AIC）必须用 `CrossCoreSetFlag` / `CrossCoreWaitFlag`，不能用 SHMEM 的 barrier 替代。
+
+---
+
+## 5. 禁止 HCCL API 速查
+
+以下 API 出现在 `operators/{op}/` 任意文件即视为违反约束 1，代码审查直接 FAIL：
+
+完整禁止清单（7 类 18 个 API）：
+
+| 类别 | API |
+|------|-----|
+| 初始化/终结 | `Hccl::Init()` / `Hccl::InitV2()` / `Hccl::Finalize()` |
+| 任务调度 | `Hccl::Commit()` / `Hccl::Wait()` / `Hccl::Query()` / `Hccl::Iterate()` |
+| 集合通信原语 | `Hccl::AllReduce()` / `Hccl::AllGather()` / `Hccl::ReduceScatter()` / `Hccl::AlltoAll()` / `Hccl::AlltoAllV()` |
+| 写操作 | `Hccl::BatchWrite()` / `Hccl::AlltoAllvWrite()` |
+| Tiling | `Hccl::SetCcTiling()` / `Hccl::SetCcTilingV2()` |
+| 跨组同步 | `Hccl::InterHcclGroupSync()` |
+| Context | `GetHcclContext<>()` |
+
+### 历史背景与正确理解
+
+这些 API 是 asc-devkit 官方通算融合路径（`docs/zh/api/SIMD-API/adv_api/HCCL_communication/`）的通信入口，也是官方 AllGatherMatmul 类算子样例使用的接口。**注意**：官方文档明确 Hccl 高阶 API 本身支持在 Kernel 内编排"先通信后计算 / 先计算后通信"（见 `HCCL_usage.md`），并非只能串行。本 skill 不用它们的真正原因只有一个：**官方通算融合仅支持单算子 API 调用（aclnn），不支持 Kernel 直调**；而本 skill 的 MC2 工程是 Kernel 直调形态，拿不到框架注入的通信上下文。直调场景下通信必须由 Kernel 自建（SHMEM/UDMA），才能与计算在同一 Kernel 内深度耦合。
+
+---
+
+## 6. SHMEM 编译与链接
+
+参考工程的 `cmake/shmem.cmake` 自动处理 SHMEM 的拉取和构建。关键步骤：
+
+1. `third_party/shmem` 由 cmake 首次配置时自动 `git clone --branch v1.5.0 --depth 1`（gitcode.com/cann/shmem），无需 git submodule；
+2. CMake 首次配置时触发 `add_custom_target(cann_samples_shmem_dependencies)`：
+   - 若 `third_party/shmem/CMakeLists.txt` 不存在，执行 `git clone`；
+   - 用 `cmake -S ... -B .../build -DSOC_TYPE=Ascend950` 构建 shmem 共享库（`libshmem.so` 等）；
+   - `cmake --build ... --target install` 安装到 `third_party/shmem/install/shmem/`；
+3. 生成两个 IMPORTED 共享库：
+   - `cann_samples_shmem_bootstrap_uid`：基于 UID 的 bootstrap；
+   - `cann_samples_shmem_bootstrap_config_store`：配置存储；
+4. `cann_samples::shmem` alias 提供头文件路径 + 链接库。
+
+### Agent 开发注意
+
+- **不要**手动修改 `third_party/shmem/` 内部；它是 clone 来的外部依赖，改动不会被保留；
+- 新算子的 CMakeLists 应直接 `include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/shmem.cmake REQUIRED)`，与参考工程一致；
+- 若 shmem 构建失败，常见原因：`ASCEND_HOME_PATH` 未设、`SOC_TYPE` 不是 `Ascend950`、网络无法访问 gitcode.com。
+
+---
+
+## 7. 排错速查
+
+| 现象 | 可能原因 | 排查方向 |
+|------|---------|---------|
+| `aclshmem_align` 返回 nullptr | SHMEM 空间已被前次分配占满 | 检查 `aclshmem_finalize` 是否被调用；减小 `SHMEM_SPACE_SIZE` |
+| `aclshmemx_udma_put_nbi` 后立即读 buffer 拿不到数据 | Put 是非阻塞的，没等 quiet/barrier | 在读前调 `aclshmemx_udma_quiet` 确保数据到达对端 |
+| 多卡运行 deadlock | AIV 的 `CrossCoreSetFlag` idx 与 AIC 的 `CrossCoreWaitFlag` idx 不匹配 | 检查 `mLoopIdx` 在两侧是否一致 |
+| Put 数据错位 | `dstDataOffset` 算错（rankId 没乘对 commMSize） | 打印 bufferId、srcMOffset、dstDataOffset 在 host 端验证 |
+| 编译报 `aclshmemx_udma_put_nbi` 未定义 | 没链接 `cann_samples::shmem` | 检查 `target_link_libraries` 是否含 `cann_samples::shmem` |
+| 运行报 `aclshmemx_init_attr failed` | `tcp://` 地址被占用或 rankNum 不匹配 | 改 `ipport`，确认所有 rank 进程同时启动 |
+
+---
+
+## 8. 后续阅读
+
+| 想了解 | 读 |
+|--------|---|
+| Blaze Matmul 接入 | `matmul_blaze.md` |
+| 通算融合整体架构 | `mc2_architecture.md` |
+| 性能采集（L2 flush + msprof） | `profiling_mc2.md` |
+| 参考工程改造食谱 | `codebase_map.md` |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/matmul_blaze.md

@@ -0,0 +1,259 @@
+# 计算层（Blaze Matmul）参考
+
+本文档承载 MC2 skill 的"计算子能力"。涵盖：Blaze 模板选型、BlockMmad 接入、Tiling 数据流、与通信层的 buffer 协议。
+
+> Blaze 是 Ascend C 的 CUTLASS 风格模板库，由 `tensor_api/` 提供。**两条路线的 Blaze/tensor_api 来源不同**：
+> - **blaze-shmem 路线**：tensor_api 来自 `gitcode.com/cann/asc-devkit` 仓 `feature/tensor_api_from_9.0.0` 分支，Blaze 来自 CANN toolkit 内置 `opp/built-in/op_impl/ai_core/tbe/impl/ops_nn/ascendc/common`（参考工程 CMakeLists 用 `_BLAZE_COMMON_DIR` 指向该目录）
+> - **apace 路线**：Blaze **和** tensor_api 均来自 `gitcode.com/cann/ops-tensor` 仓（tensor_api 是 ops-tensor 的 submodule，指向 asc-devkit）
+>
+> 与 `ascendc-blaze-best-practice` 共享 Blaze 基底，但聚焦 MC2 场景下的差异点。**禁止使用 asc-devkit 的 matmul 高阶 API（`AscendC::Matmul` 等）**——它是官方通算融合（单算子 API 调用）路径的计算接口，不支持 Kernel 直调场景。
+
+---
+
+## 1. MC2 场景下的 Blaze 子集
+
+参考工程用到的 Blaze 组件：
+
+| 层级 | 组件 | 文件 | 作用 |
+|------|------|------|------|
+| **Kernel** | `Blaze::Gemm::Kernel::QuantMatmulMxKernelSwat`（项目级） | `include/kernel/qbmm_mx_kernel.h` | SWAT 量化 Matmul kernel 包装，遍历所有 rank 累加 L0C |
+| **Block** | `Blaze::Gemm::Block::BlockMmad` | `blaze/gemm/block/block_mmad_qbmm_mx.h`（toolkit 内） | 单 Block 的 MMAD 计算（L0A×L0B→L0C→GM） |
+| **Block Scheduler** | `Blaze::Gemm::Block::BlockSchedulerQuantBatchMatmulV3` | `include/block/quant_matmul_mx_block_scheduler_swat.h` | 多 Block 间任务切分 |
+| **Dispatch Policy** | `Blaze::Gemm::MatmulWithScaleMx` | `blaze/gemm/policy/dispatch_policy.h`（toolkit 内） | 流水策略（含 scale 处理） |
+| **Tile** | `Blaze::Gemm::Tile::*` | `include/tile/*.h` | L1→L0 搬运、Scale pad |
+| **Layout/Tensor** | `AscendC::Te::*` | `tensor_api/`（SHMEM: asc-devkit clone; apace: ops-tensor submodule） | Tensor / Layout 抽象 |
+
+**Agent 开发原则**：`include/block/`、`include/tile/`、`include/policy/` 下的文件 **`[REUSE]`**，常规 MC2 算子不需要改。需要改的是：
+- `include/kernel/qbmm_mx_kernel.h`：Scale 处理、A/B 来源切换；
+- `include/kernel/all_to_all_matmul_impl.h`：通算流水编排；
+- `include/tiling/quant_matmul_mx_tiling_swat.h`：Tiling 字段。
+
+---
+
+## 2. 从 Blaze 到 MC2 的桥接
+
+参考工程在 `qbmm_mx_kernel.h` 定义 `QuantMatmulMxKernelSwat`，把标准 Blaze `BlockMmad` 接入 MC2 通算流水。AIC 在通信 buffer 上遍历所有 rank，把各 rank 的部分和在 L0C 上累加，最后一次 `mmadOp_` 触发 fixpipe 输出 GM。
+
+```cpp
+// qbmm_mx_kernel.h ProcessSingleBatch 核心逻辑（简化伪码）
+for (uint64_t rank = 0; rank < rankSize; rank++) {
+  auto actualMPos = rank * oriM + mPos;            // local A 按 oriM 分段
+  auto actualCommMPos = rank * headMSize + mPos;   // 通信 buffer 按 headMSize 分段
+
+  // 默认从通信 buffer 读 A；rank == rankId 时改从本卡 GM 读
+  auto gmBlockA = gmA.Slice(actualCommMPos, ...);
+  auto gmBlockScaleA = gmScaleA.Slice(actualMPos, ...);
+  if (rank == rankId) {
+    gmBlockA = gmALocal.Slice(actualMPos, ...);    // 本卡 GM
+    gmBlockScaleA = gmScaleALocal.Slice(actualMPos, ...);
+  }
+
+  // B / ScaleB 始终从本卡 GM 读，按 rank 切 K 轴段
+  auto gmBlockB = gmB.Slice(rank * K + nPos, ...);
+
+  // L0C 上累加：remoteRankCnt=0 时 L0C reset；最后一次触发 fixpipe
+  mmadOp_(gmBlockA, gmBlockB, gmBlockScaleA, gmBlockScaleB, gmBlockBias, gmBlockC,
+          singleShape, remoteRankCnt);
+  remoteRankCnt++;
+}
+```
+
+### 2.1 为什么 rank == rankId 时从本卡 GM 读？
+
+`AllToAllComm::PutToAllRanks` 中每个 Block 只 Put 给 `remoteRank != rankId` 的对端——本 rank 不 Put 给自己。所以通信 buffer 中本 rank 的段是**未填充**的，AIC 算到 `rank == rankId` 时必须切换到本卡 GM（`localAGmAddr_`），否则会读到未初始化数据。
+
+### 2.2 remoteRankCnt 的语义
+
+`mmadOp_` 的最后一个参数 `remoteRankCnt` 控制 L0C 累加位置：
+- `= 0`：L0C reset，开始新的累加序列；
+- `> 0`：在已有结果上累加；
+- `== splitKNum - 1`（这里 splitKNum = rankSize）：触发 fixpipe，把 L0C 累加结果写回 GM。
+
+参考工程在 `SetupParams` 中固定 `splitKNum = rankSize`，保证 `for rank` 循环最后一次正好触发 fixpipe。
+
+---
+
+## 3. Layout 与 Tensor 构造
+
+参考工程在 `qbmm_mx_kernel.h::ProcessSingleBatch` 构造 Blaze Tensor 句柄：
+
+```cpp
+// Layout 构造
+auto layoutA = MakeLayoutA{}(rankSize * Te::Get<MNK_M>(problemShape),
+                              Te::Get<MNK_K>(problemShape));
+auto layoutB = MakeLayoutB{}(rankSize * Te::Get<MNK_K>(problemShape),
+                              Te::Get<MNK_N>(problemShape));
+auto layoutC = MakeLayoutC{}(Te::Get<MNK_M>(problemShape),
+                              Te::Get<MNK_N>(problemShape));
+
+// Tensor 句柄
+auto gmA = Te::MakeTensor(Te::MakeMemPtr<Te::Location::GM>(aGmAddr_), layoutA);
+auto gmB = Te::MakeTensor(Te::MakeMemPtr<Te::Location::GM>(bGmAddr_), layoutB);
+auto gmC = Te::MakeTensor(Te::MakeMemPtr<Te::Location::GM>(cGmAddr_), layoutC);
+```
+
+### MC2 场景的 layout 维度
+
+注意 layout 维度包含 `rankSize *`，因为 A 和 B 矩阵在 MC2 中是"按 rank 切分后逻辑拼起来"的：
+
+- **A 矩阵**：每卡持有自己的 M 段，但 SHMEM buffer 收齐所有 rank 的 M 段后，逻辑上是 `rankSize * headMSize` 行的矩阵；
+- **B 矩阵**：每卡持有自己的 K 段（kPerRank），逻辑上是 `rankSize * kPerRank = K` 行的矩阵；
+- **C 矩阵**：本卡只输出自己 M 段的结果，维度是 `headMSize * N`（不含 rankSize）。
+
+Slice 时按 rank 切：
+
+```cpp
+// 取远程 rank 的 A 段
+auto gmBlockA = gmA.Slice(
+  Te::MakeCoord(rank * Get<MNK_M>(problemShape) + mPos, kPos),
+  Te::MakeShape(Get<MNK_M>(singleShape), Get<MNK_K>(problemShape)));
+```
+
+---
+
+## 4. Tiling 数据流
+
+参考工程的 Tiling 链路：
+
+```
+Host: QuantMatmulTilingSwat::GetTilingData()
+    ↓ 填充 QuantMatmulTilingData (baseM/baseN/baseK/...)
+Device: AllToAllQuantMatmulImpl::SetupParams()
+    ↓ 转成 Blaze Params (BlockMmadParams + L1Params + ...)
+Device: QuantMatmulMxKernelSwat::Run()
+    ↓ 调用 BlockMmad
+Device: BlockMmad::operator() 做 MMAD
+```
+
+### Tiling 字段速查（`include/tiling/quant_matmul_tiling_data.h`）
+
+| 字段 | 含义 |
+|------|------|
+| `m, n, k` | 问题 shape（注意 k 是单卡的 kPerRank） |
+| `baseM, baseN, baseK` | 单 block 的 tile shape |
+| `mTailTile, nTailTile` | 尾块切分 |
+| `mBaseTailSplitCnt, nBaseTailSplitCnt` | 尾块分裂策略 |
+| `mTailMain, nTailMain` | 尾块主区大小 |
+| `usedCoreNum` | 实际使用的 AIC 核数 |
+| `dbL0c` | L0C DoubleBuffer 深度（1 或 2） |
+| `scaleKL1` | Scale 在 L1 的复用深度 |
+| `stepK` | K 轴 step |
+| `nBufferNum` | L1 buffer 数 |
+
+### MC2 专属 Tiling 字段（`include/tiling/all_to_all_matmul_tiling_data.h`）
+
+```cpp
+struct AllToAllCommTilingData {
+    uint32_t tileCnt;      // M 轴切分块数（headMSize * tileCnt = M）
+    uint32_t bufferSize;   // 通信流水深度（典型 4）
+};
+```
+
+参考工程 host 侧的 Tiling 计算（`src/all_to_all_matmul.cpp`）：
+
+```cpp
+uint32_t headMSize = 512;  // 参考工程默认值，非最优——详见 pipeline_tuning.md
+uint32_t tileCnt = (m - tailMSize) / headMSize;
+tilingData.commTilingData.tileCnt = tileCnt;
+tilingData.commTilingData.bufferSize = 4;
+// 每块 matmul 的 Blaze tiling 由 GetTilingData 根据 headMSize 自动推导
+tilingEngine.GetTilingData(headMSize, n, ka, false, true, tilingData.tileQbmmTilingData);
+```
+
+> `headMSize=512` 只是参考工程经验起点，**实际最优 `tileCnt`（即 `headMSize = M/tileCnt`）以 `msprof op` 实测为准**。精度调试阶段建议先用 `tileCnt=1`（`headMSize=m`）做串行基线，性能调优阶段再扫描 `tileCnt` 找最优——详见 [`pipeline_tuning.md`](../../shared/pipeline_tuning.md)。
+
+### Tiling 算法
+
+`include/tiling/quant_matmul_mx_tiling_swat.h` 实现了 SWAT tiling 算法（SWAT 为项目内部命名，CANN 库中无此术语的官方定义。算法行为是滑动窗口 + N 轴 zigzag 的 tile 调度）：
+
+1. `CalcBasicBlock()`：从 256 出发，对齐到 CUBE_BLOCK（16）和 L1 对齐粒度；
+2. `OptimizeEdgeBasicBlock()`：合并 K 对齐时的尾块；
+3. `CalcTailBasicBlock()`：尾块按 M/N 双向切分；
+4. `CalcPathSpecificL1()`：搜索 L1 深度（A/B 对称起步，必要时打破）。
+
+新算子一般不改这些算法，只调 host 侧的 `headMSize`（等价于调 `tileCnt = M/headMSize`）等参数。
+
+---
+
+## 5. DispatchPolicy 选择
+
+参考工程用 `MatmulWithScaleMx`（带 MX 量化 scale 的 dispatch policy）：
+
+```cpp
+// all_to_all_matmul_impl.h using 声明段
+using DispatchPolicy = Blaze::Gemm::MatmulWithScaleMx<NONE_FULL_LOAD_MODE, false>;
+```
+
+- `NONE_FULL_LOAD_MODE`：A/B 不全载 L1（与 `ascendc-blaze-best-practice` 的模式选择一致）；
+- 第二个模板参数 `false` 是 `ATOMIC_ADD`（是否启用输出 atomic add，默认关闭）。
+
+可选的 DispatchPolicy（详见 `ascendc-blaze-best-practice` skill `references/scenarios/index.md`）：
+- `MatmulMultiBlockPolicy<NO_FULL_LOAD_MODE>`：通用多 block SWAT；
+- `MatmulMultiBlockPolicy<A_FULL_LOAD_MODE>`：A 全载（N≫M 时用）；
+- `MatmulWithScaleMx<...>`：MX 量化 matmul（参考工程用）。
+
+MC2 算子若非量化场景，可改用 `MatmulMultiBlockBasic`。
+
+---
+
+## 6. Scale（量化系数）处理
+
+参考工程是 MX FP8 量化 matmul，Scale 处理是关键。两条路径：
+
+### 6.1 Scale 的 SHMEM Put
+
+Scale 不参与 M 轴流水，AIV 启动时一次性 Put（`all_to_all_matmul_impl.h::AllToAllProcess` 开头）：
+
+```cpp
+allToAllComm_.PutScaleToAllRanks(0, axisM_);  // offset=0, 全 M 行
+```
+
+### 6.2 Scale 的 L0B 加载
+
+参考工程在 `include/tile/copy_scale_l1_to_l0b.h` 处理 Scale 从 L1 到 L0B 的搬运。`qbmm_mx_kernel.h` 的 `SetScaleL2Cache`（`ProcessSingleBatch` 内）控制 Scale 的 L2 cache 行为（数据对齐时禁用 cache 走 stream，不对齐时走 normal）。
+
+### 6.3 非 MX 场景
+
+若新算子不做量化（纯 BF16/FP16 matmul），可以：
+- 去掉 `allToAllComm_.PutScaleToAllRanks`；
+- 把 `BlockMmad` 模板从量化版（`block_mmad_qbmm_mx.h`）换成普通版（`block_mmad.h`）；
+- Tiling 字段去掉 scaleKL1、stepK 等。
+
+---
+
+## 7. 排错速查
+
+| 现象 | 可能原因 | 排查方向 |
+|------|---------|---------|
+| 编译报 `BlockMmad` 模板参数错误 | DispatchPolicy 与 BlockScheduler 的 `*_LOAD_MODE` 不一致 | 检查 `NONE_FULL_LOAD_MODE` 是否两侧都用 |
+| 精度错（局部对，整体差） | `remoteRankCnt` 没从 0 起算 / rank==rankId 时未切换到本卡 GM | 核对 ProcessSingleBatch 中的 if (rank == rankId) 分支 |
+| L0C 累加结果不对 | `splitKNum` 与实际 rank 遍历数不一致 | 检查 SetupParams 中 `splitKNum = rankSize_` 是否正确 |
+| fixpipe 时崩溃 | C 地址偏移错（mOffset 算错） | 打印 `cGm_ + mOffset * axisN_ * sizeof(CType)` 与预期对比 |
+| 性能不达标（cube ratio 低） | L1 深度过浅，K 轴反复加载 | 调大 `scaleKL1` 或换 `MatmulMultiBlockBasic<A_FULL_LOAD_MODE>` |
+| blaze 头文件找不到 | `target_include_directories` 漏了 `_BLAZE_COMMON_DIR` | 参考 `CMakeLists.txt` 的 `target_include_directories` 段 |
+
+---
+
+## 8. 与 ascendc-blaze-best-practice 的关系
+
+`ascendc-blaze-best-practice` skill 是 Blaze 单算子（无跨卡通信）的完整指南。复用其 Blaze 基底，但在以下方面不同：
+
+| 维度 | ascendc-blaze-best-practice | MC2 场景 |
+|------|-----------------------------|----------------|
+| 通信 | 无 | SHMEM/UDMA 跨卡 |
+| 数据来源 | 全部本卡 GM | rank==rankId 走本卡 GM，其他 rank 走 SHMEM buffer |
+| Tiling | 单卡 L1/L0 容量 | + SHMEM 空间预算 |
+| Scale | 可选 | 量化场景必需（参考工程是 MX FP8） |
+
+新算子设计时，**先读 `ascendc-blaze-best-practice` 选 Blaze 模板，再将模板接入 MC2 通算流水**。
+
+---
+
+## 9. 后续阅读
+
+| 想了解 | 读 |
+|--------|---|
+| SHMEM/UDMA 通信层 | `comm_shmem.md` |
+| MC2 整体架构 | `mc2_architecture.md` |
+| Blaze 单算子细节（模板选型、Tiling 算法） | `ascendc-blaze-best-practice` skill `references/scenarios/index.md` |
+| 参考工程改造食谱 | `codebase_map.md` |