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

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/hccl-matmul/mc2_architecture.md

@@ -0,0 +1,142 @@
+# 910B（A2）MC2 架构心智模型
+
+本文档承载 910B MC2 skill 的"架构心智子能力"。面向第一次接触 910B MC2 的 Architect/Developer，建立通信方案选择、AIV/AIC 分工、HCCL AIC-only 下发、通算两层流水、M 轴切分并行的整体心智模型。读完应能回答：910B 有哪些通信方案、为何选 HCCL 高阶 API？Matmul 跑在哪个核？HCCL 该怎么下发？tileCnt 调什么？
+
+> 官方依据（CANN 官方仓库 <https://gitcode.com/cann/asc-devkit>）：HCCL 高阶 API 见 `docs/api/SIMD-API/高阶API/HCCL通信类`；Matmul 高阶 API 见 `docs/api/SIMD-API/高阶API/矩阵计算`；通算融合指南见 `docs/guide/算子实践参考/SIMD算子实现/融合算子编程/通算融合`（均取 A2/910B 标记内容）。蓝本为已验证功能正常的 [`all_gather_matmul/`](all_gather_matmul)。
+
+## 1. 910B（A2）MC2 是什么
+
+910B（A2，dav-2201/arch22）上的 MC2 = 多卡间集合通信 + 单卡内 `AscendC::Matmul` 计算 + 通算两层流水掩盖通信。典型场景：
+- AllGather + Matmul（多卡 Gather A 后各卡本地 Matmul，蓝本 `all_gather_matmul`）
+- AllReduce + Matmul（各卡 Matmul 后对结果 AllReduce，蓝本 `matmul_all_reduce`）
+- AlltoAll + Matmul（多卡数据重分布后 Matmul）
+
+> 通算融合算子**不支持 Kernel 直调（`<<<>>>`）与入图（GE）开发，仅支持单算子 API 调用**（指南 `算子实现.md:3`）。故 910B MC2 工程是 **aclnn 单算子工程**（`build.sh`→`.run`+`libcust_opapi.so`），不是 `<<<>>>` 直调工程；工程架构详见 [`op_architecture.md`](op_architecture.md)。本期不支持 quant（int8 通信、per-token 量化等）。本 skill 仅覆盖 A2（910B），不涉及 A3（910_93）。
+
+## 2. 910B 的通信方案与本 skill 的选择
+
+910B 上实现多卡通信有**多种方案**，并非只有一条路径：
+
+| 方案 | 性质 | 在 910B 的可用性 |
+|------|------|------------------|
+| **HCCL in-kernel 高阶 API（AICPU 引擎）** | 集合通信官方高阶 API，`prepare→(Commit)→Wait` 模型 | ✅ 官方支持（A2 服务端仅 `HCCL_SERVER_TYPE_AICPU`） |
+| SHMEM / UDMA（`aclshmemx_*`） | 设备侧共享内存原语 | ❌ 910B 硬件不支持（950/DAV_3510 专属） |
+| HCOMM 点对点（`hcomm_.WriteNbi` 等） | URMA/RDMA 原语，非集合 | ⚠️ 见现网部分算子使用，但非官方高阶集合 API |
+| 窗口手动 MTE | 手动 `DataCopy` 到通信窗口 + 状态标志软同步 | ⚠️ 见现网部分算子使用，需自行管理同步 |
+| RAC-server | 自研 all-reduce 路径 | ⚠️ legacy（如 `matmul_all_reduce` arch31） |
+| host 侧 HCCL C-API | `HcclAllReduce` 等 | 仅 host 侧 context 创建，不可作 kernel 通信 |
+
+**本 skill 选择 HCCL in-kernel 高阶 API（AICPU 引擎）**，原因：
+- 是官方高阶 API，集合原语齐全（AllReduce/AllGather/ReduceScatter/AlltoAll/BatchWrite）。
+- `prepare→（Commit）→Wait` 模型天然支持与 `AscendC::Matmul` 流水耦合（prepare 全部 → 逐 tile Wait 驱动计算）。
+- 由 AICPU 服务端执行通信，AIC 同时做本地 Matmul，二者经"消息区"+`hccl.Wait` 流水重叠（指南 `算子实现.md:118-137`）。
+
+```
+910B（A2）：Host → HCCL(AICPU server) ┐   AscendC::Matmul(AIC 计算) ┐   通算两层流水
+950       ：Host → SHMEM/UDMA(device) ┘  Blaze Cube                  ┘   通算两层流水
+```
+
+> 即：950 用 SHMEM/UDMA + Blaze；910B 本 skill 用 HCCL 高阶 API + `AscendC::Matmul`。这不是"910B 唯一可行路径"，而是本 skill 的选择。
+
+## 3. AIV/AIC 分工（Matmul 跑在 AIC）
+
+910B 为分离架构，一个 AI Core 由 **Cube Core（AIC）+ Vector Core（AIV）** 按 1:N 组合（910B 为 1:2）。910B 全系列子型号（910B1/B2/B3/B4/B2C）的 **AIC:AIV 配比一致**，故 `KERNEL_TASK_TYPE_DEFAULT(KERNEL_TYPE_MIX_AIC_1_2)` 在各子型号通用。
+
+**Matmul 的矩阵乘（MMAD）跑在 AIC/Cube 核**；AIV 只起"发起通知"作用并取回结果（A2 下经 AIC 内 Fixpipe 从 L0C 直出 GM，不经 UB；A2 无 L0C→UB 直连通路）。官方原文（`Matmul-Kernel侧接口/SetDim.md`）：
+> "分离模式：Matmul API 都是从 AIV 侧发起的，调用 Iterate 计算时在 AIV 侧只会起到通知的作用，**通知 AIC 去做矩阵计算**，计算完成后 AIC 告知 AIV 计算完成……"
+
+```
+AIV（Vector）：发起 mm.Iterate() → 通知 AIC → ... → GetTensorC(gmC) 取 GM 结果
+AIC（Cube） ：执行 MMAD（L1→L0→MMAD→L0C→GM，经 Fixpipe），不主动执行，由 AIV 触发
+```
+
+**HCCL 通信与 Matmul 都在 AIC 执行**（AIC-only，`if ASCEND_IS_AIC { … }` 正向门控，AIV 不执行算子主体/早返回），见 §4。这与通算融合指南的 `ASCEND_IS_AIV` 早返回 + `#define ASCENDC_CUBE_ONLY` 蓝本等价（`算子实现.md:451-457,549`）。
+
+> 注：`g_coreType` 在本算子中仅用于 `mc2_nd_to_nz.h` 的 ND→NZ AIV/AIC 分工（`SET_G_CORE_TYPE_IS_AIV/AIC` 宏在 `:22-28`，判定在 `:98,479,531`），**不用于** HCCL 门控（HCCL 用 `ASCEND_IS_AIC`）。
+
+## 4. HCCL 调用模式：AIC-only + ASCEND_IS_AIC 门控
+
+**实际蓝本（grep 实证，[`x_all_gather_matmul_full_mesh.h`](all_gather_matmul/x_all_gather_matmul/op_kernel/x_all_gather_matmul_full_mesh.h)）= AIC-only**：HCCL prepare/Wait/Finalize 与 Matmul 都在 `if ASCEND_IS_AIC { … }` 正向门控内执行（`:75,101,220`）；AIV 不执行算子主体。**Finalize 前需跨核同步**：蓝本 `HcclFinalize()`（`:218`）用 `CrossCoreSetFlag<0,PIPE_FIX>(EVENT_ID_6)`+`CrossCoreWaitFlag(EVENT_ID_6)`（`:224-225`）后 `hccl_.Finalize()`（`:226`）——非 `SyncAll<true>()`，但效果等同（保证所有核计算结束再 Finalize）。
+
+```cpp
+Hccl<HCCL_SERVER_TYPE_AICPU> hccl_;                  // :46（运行时 ASCEND_IS_AIC 门控）
+GM_ADDR contextGM = GetHcclContext<HCCL_GROUP_ID_0>();  // x_all_gather_matmul.cpp:71
+// Init()（:52-61）不带门控，AIC/AIV 都执行
+hccl_.InitV2(contextGM, tilingData);                  // V2（蓝本已用；:57）
+hccl_.SetCcTilingV2(offsetof(Mc2Tiling::XAllGatherMatmulTilingData, mc2CcTiling)); // V2 offset；:58
+if ASCEND_IS_AIC {                                    // HcclPrepare()，AIC-only 门控（非 g_coreType==AIV）；:75
+    handleId_ = hccl_.AllGather<true>(...);           // :89 主块 prepare（<true>=同步通知服务端）
+    if (cfg.tailCnt > 0) { tailHandleId_ = hccl_.AllGather<true>(...); }  // :91-92 尾块 prepare（有尾才发）
+}
+if ASCEND_IS_AIC {                                    // InnerProcess()；:101
+    // MatmulKernelLocal()（:104）本地 rank 先算（与首轮通信重叠）
+    // 逐 tile hccl_.Wait(:143) → 跳过本 rank(:149-150) → mm.Compute(:161)
+}
+// HcclFinalize()（:218 封装，:220 AIC 门控）：
+//   CrossCoreSetFlag<0,PIPE_FIX>(EVENT_ID_6); // :224 跨核同步（非 SyncAll，效果等同）
+//   CrossCoreWaitFlag(EVENT_ID_6);            // :225
+//   hccl_.Finalize();                         // :226 默认 = Finalize<true>
+```
+> 引自蓝本工程实测代码 + 通算融合指南 `算子实现.md:451-457,549,487-544`。
+
+> **关于 `g_coreType` / `SyncAll<true>()`**：HCCL 使用说明（`HCCL使用说明.md:149-157,198`）确有一段示例用 `if (g_coreType == AIV)` 门控 + `AscendC::SyncAll<true>();` 注释（"防 0 核提前 Finalize 致其他核 Wait 卡死"），那是 **AIV-下发场景** 的通用写法。MC2 通算融合蓝本走 **AIC-only**（`ASCEND_IS_AIC`）路径，不显式用 `g_coreType`/`SyncAll`，**但 Finalize 前仍需跨核同步**——蓝本用 `CrossCoreSetFlag<0,PIPE_FIX>(EVENT_ID_6)`+`CrossCoreWaitFlag(EVENT_ID_6)`（`full_mesh.h:224-225`）替代 `SyncAll`，效果等同（保证所有核计算结束再 Finalize）。本 skill 以蓝本（AIC-only）为准。
+
+> **关于"单 block 驱动 HCCL"（`notifyFlag_`）**：现网 legacy 算子（如 `matmul_all_reduce` arch22）曾用 `notifyFlag_` 让仅 block 0 下发 HCCL——**参考蓝本 `all_gather_matmul` 全树 0 hit，不采用**；本 skill 统一用 AIC-only 全核模式。
+
+### Commit/Wait 配对规则（官方约束，HCCL 文档实证）
+- `Wait` 顺序须匹配 `Prepare` 顺序；`Commit`/`Wait` 调用次数 = Prepare 的 `repeat` 数。
+- `Commit`/`Wait` 须与 `Prepare` 在**同一核类型**（AIC 或 AIV）调用。
+- 一通信域内所有 `Prepare` 总调用次数 ≤ 63（A2；A3 另含 `InterHcclGroupSync`）。
+
+## 5. 通算两层流水（prepare 全部 → 逐 tile Wait 驱动计算）
+
+两条典型生命周期（详见 [`comm_hccl.md`](comm_hccl.md)）：
+
+**蓝本 A（all_gather_matmul，通信在前）**——蓝本实测（`Process()` 四段：`HcclPrepare → Nd2NzBiasCast → InnerProcess → HcclFinalize`）：
+```
+InitV2 → SetCcTilingV2（不带门控）
+[ASCEND_IS_AIC] AllGather<true>(主块) [+ AllGather<true>(尾块，仅 tailCnt>0)]  [prepare 全部]
+[ASCEND_IS_AIC] 本地 rank 先算 → [逐 tile: Wait(i) → Matmul(i)，跳过本 rank]
+[ASCEND_IS_AIC] CrossCoreSetFlag/WaitFlag → Finalize<true>()
+```
+流水：tile i+1 的 AllGather 与 tile i 的 Matmul 重叠（AI CPU 执行卡间通信，AIC 同时做本地 Matmul）。
+
+**蓝本 B（matmul_all_reduce，计算在前，"一算一通信"）**——指南仅给调度图（`算子实现.md:111-114`）：
+```
+Init → SetCcTiling → AllReduce(prepare, repeat=tileCnt) → [逐 tile: Matmul(i) → Commit(i)] → Wait(全部) → Finalize<true>()
+```
+流水：tile i+1 的 Matmul 与 tile i 的 AllReduce 通信重叠（Commit 下发一次 repeat）。计算在通信前的算子建议本卡数据计算放最后，与末次通信互相掩盖（`算子实现.md:111`）。
+
+```
+tileCnt=1（串行基线，阶段一）:  MM ── AR ── MM ── AR ──
+tileCnt=N （阶段三·3.2 扫描）  :   MM0 ─┐ MM1 ─┐ MM2 ─┐
+                                  AR0 └─ AR1 └─ AR2 └─   (overlap)
+```
+
+## 6. 切分策略：M 轴通算并行
+
+| 候选轴 | 通算并行性 | 实现难度 | 适用场景 |
+|--------|-----------|----------|----------|
+| M 轴 | 高（逐 tile 流水） | 中 | AllGather+MM / AllReduce+MM 主选 |
+| K 轴 | 中（splitK） | 低 | K 大、M 小 |
+| N 轴 | 低 | 高 | 较少单独用 |
+
+- `tileCnt`（指南记 `tileNum`）= M 轴主块切分数；`tailNum`∈{0,1} 尾块（`算子实现.md:106,318-320`）。主块/尾块/本地 rank 各一套 `TCubeTiling`（`localTiling`/`tileTiling`/`tailTiling`）。
+- L2CACHE 分裂（`enableL2Tile`）：大 N/K 时单次扫 gathered buffer。
+> 详见 [`pipeline_tuning.md`](pipeline_tuning.md)。
+
+## 7. 性能采集要点
+910B 走 HCCL（AICPU），无 SHMEM B-matrix residency 问题，**无需 950 的 L2 cache flush**；但仍建议 warm-up。采集流程复用 [`../../shared/profiling_mc2.md`](../../shared/profiling_mc2.md)，跳过 `heavy_add_kernel`。
+> 注：通算融合指南未述 L2 flush（指南仅覆盖通信/计算重叠机制）；"无需 flush" 为本 skill 据 HCCL/AICPU 模型的推理。
+
+## 8. 后续阅读
+
+| 想了解 | 读 |
+|--------|-----|
+| 算子架构与可复用框架 | [`op_architecture.md`](op_architecture.md) |
+| HCCL API 与生命周期蓝本 | [`comm_hccl.md`](comm_hccl.md) |
+| Matmul 接入 | [`matmul_fusion.md`](matmul_fusion.md) |
+| PTA 接口生成 | `ops/torch-ascendc-op-extension` 路线 B（aclnn 注册） |
+| CANNBot 工作流 | [`workflow_integration.md`](workflow_integration.md) |
+| tileCnt 调优 | [`pipeline_tuning.md`](pipeline_tuning.md) |
+| 性能采集 | [`../../shared/profiling_mc2.md`](../../shared/profiling_mc2.md)（无需 L2 flush） |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/hccl-matmul/op_architecture.md

@@ -0,0 +1,167 @@
+# 算子架构与可复用框架（910B/A2 / aclnn 单算子 API）
+
+本文档承载 910B（A2）MC2 skill 的"算子架构子能力"——以已验证功能正常的 [`all_gather_matmul/`](all_gather_matmul) 为蓝本，讲清单算子工程的真实目录分工、aclnn 注册模型，以及 `mc2_common/` 这套可跨算子复用的框架（即"哪些部分通用、可总结为经验"）。读完应能回答：一个新 910B MC2 算子工程长什么样？哪些文件改、哪些文件原样复用？
+
+> 官方依据（CANN 官方仓库 <https://gitcode.com/cann/asc-devkit>）：通算融合指南 `docs/guide/算子实践参考/SIMD算子实现/融合算子编程/通算融合/算子实现.md`（A2 样例 `all_gather_matmul_v2`）；HCCL/Matmul 高阶 API 见 `docs/api/SIMD-API/高阶API/` 对应目录。本 skill 仅覆盖 A2。
+
+> **关键事实**：通算融合算子**不支持 Kernel 直调（`<<<>>>`）与入图（GE）开发，仅支持单算子 API 调用**（`算子实现.md:3`）。故 910B MC2 工程是 **aclnn 单算子 API 工程**（`build.sh` → `.run` 包 + `libcust_opapi.so`），不是 `<<<>>>` 直调工程。本 skill 早期版本误标为"Kernel 直调"，已更正。
+
+## 1. 工程总览（真实结构）
+
+```
+all_gather_matmul/
+├── build.sh                       # 构建入口：bash build.sh -n x_all_gather_matmul [-c ascend910b]
+├── CMakeLists.txt                 # 顶层：project(cann_ops_adv)；ASCEND_COMPUTE_UNIT 默认 ascend910b
+├── cmake/                         # 构建框架（config/func/intf/intf_pub/modules/Findalog/scripts）
+├── x_all_gather_matmul/           # 目录名必须 == OpDef 类名 snake_case（XAllGatherMatmul）
+│   ├── CMakeLists.txt             # 算子级：host include 根、vendored mc2_common include、target_sources
+│   ├── op_host/
+│   │   ├── x_all_gather_matmul_def.cpp          # 算子定义（IRD）：DataType({FP16,BF16}) → opc 自动烘焙双 dtype
+│   │   ├── x_all_gather_matmul_proto.cpp        # infershape（调 mc2_common_infershape）
+│   │   ├── op_api/
+│   │   │   ├── aclnn_x_all_gather_matmul.cpp    # aclnn 两段式 C 接口（GetWorkspaceSize + launch）
+│   │   │   └── aclnn_x_all_gather_matmul.h
+│   │   └── op_tiling/
+│   │       ├── x_all_gather_matmul_tiling_base.{cpp,h}   # tiling 基类（Mc2CcTilingConfig 填充等）
+│   │       ├── x_all_gather_formulaic_tiling.{cpp,h}     # XAllGatherPlusMM（继承 OneCalcOneCommBase）
+│   │       └── arch22/
+│   │           ├── x_all_gather_matmul_tiling_a2a3.{cpp,h}   # A2/A3 具体子类（SocVersion::SOC910_B）
+│   │           └── x_all_gather_formulaic_tiling_a2a3.{cpp,h}
+│   ├── op_kernel/
+│   │   ├── x_all_gather_matmul.cpp            # kernel 入口 x_all_gather_matmul；GetHcclContext<HCCL_GROUP_ID_0>
+│   │   ├── x_all_gather_matmul_base.h        # 公共基类
+│   │   ├── x_all_gather_matmul_full_mesh.h   # AIC-only 融合主类（HCCL + MatmulCompute）
+│   │   ├── x_all_gather_matmul_tiling.h      # device 侧 tiling 结构体（首字段 Mc2InitTiling）
+│   │   └── x_all_gather_matmul_tiling_key.h  # tiling key
+│   └── mc2_common/                           # 可复用框架（vendor 进来，跨算子原样复用）
+│       ├── op_host/{mc2_common_infershape.*, op_tiling/*, utils/*}
+│       ├── op_kernel/{mc2_matmul_block*, mc2_matmul_compute.h, mc2_nd_to_nz.h, mc2_tiling_struct.h}
+│       └── utils/{mc2_hcom_topo_info.*, ops_utils.h}
+├── examples/                     # 多进程精度测试（golden/run_test.sh/single_server_*；调用 PTA 前须先按路线 B 生成）
+└── README.md
+```
+
+构建产物：`bash build.sh -n x_all_gather_matmul` → 单次构建即烘焙 **fp16 + bf16 双二进制**（opc 按 `_def.cpp` 的 `DataType({DT_FLOAT16, DT_BF16})` 列表自动 per-dtype 烘焙，运行时按 tensor dtype 经 `multi_kernel` 选择，无需为 bf16 单独重建）→ `build/custom_opp_<arch>.run`（含 `libcust_opapi.so`，导出 `aclnnXAllGatherMatmul` 公共 C 接口）。运行前 `export ASCEND_CUSTOM_OPP_PATH=<vendors/custom_opp 绝对路径>`。
+
+- `-n`/`ASCEND_OP_NAME` 的取值必须等于**外层算子目录名**：`func.cmake` 遍历子目录，取含 `CMakeLists.txt` 的目录 basename 作 `OP_NAME`，再与 `ASCEND_OP_NAME` 比对过滤（`func.cmake:15-31`）。省略 `-n` 时默认 `ALL`（`CMakeLists.txt:9`），编译全部算子。多个算子用分号分隔并加引号。
+- 默认 SoC `ascend910b`（`CMakeLists.txt:8`）；顶层 `project(cann_ops_adv)`（未指定 VERSION）；`VENDOR_NAME` 默认 `custom_opp`（`CMakeLists.txt:10`），CPack 产物名 `custom_opp_${CMAKE_SYSTEM_PROCESSOR}.run`（`:552`），安装树暂存于 `build/_CPack_Packages/Linux/External/<run 名>/packages/vendors/${VENDOR_NAME}`。
+- `.run` **只在 `-b host` 模式下**被 build.sh 额外拷贝到 `output/`（`build.sh:303-309`）；默认模式产物留在 `build/`。
+- `build.sh` 的 `--help` 只列了 `-h/-n/-c/--tiling_key/--verbose`，但实际还解析 `-p|--package-path`、`-b|--build`、`--ccache`、`--parent_job`、`--enable_host_tiling`、`--op_build_tool`、`--ascend_cmake_dir`、`--msdebug`、`--ops-compile-options`、`--tiling-key`、`--clang`、`-f|--changed_list`、`--disable-check-compatible`。
+
+> 经验：dtype 不靠 `-DDTYPE_*` 宏（`x_all_gather_matmul/CMakeLists.txt:109-115` 注释明确），由 opc 自动烘焙；硬编码 `-DDTYPE_*` 会退化为单 dtype。
+>
+> 经验：op_type 必须带自定义前缀（此处 `X`），否则与 CANN 内置 `AllGatherMatmul` 撞注册表 key，构建与调用都"成功"但实际跑的是内置实现，kernel 里的 printf 不会输出。蓝本据此把整条链路（OpDef 类名、公式化 tiling 类、device tiling 类、aclnn 符号、kernel 入口、PTA op_type）统一加了 `X` 前缀。
+
+## 2. op_host 分工（host 侧）
+
+| 文件 | 职责 |
+|------|------|
+| `x_all_gather_matmul_def.cpp` | 算子定义（IRD）：`OP_ADD(XAllGatherMatmul)`（`:78`）；输入 `x1`/`x2`/`bias`（bias OPTIONAL）、输出 `y`/`gather_out`；属性 7 个且**全 snake_case**：`group`(String,必选)/`is_trans_a`(Bool,false)/`is_trans_b`(Bool,false)/`gather_index`(Int,0)/`comm_turn`(Int,0)/`rank_size`(Int,0)/`is_gather_out`(Bool,true)；五个张量的 `DataType({DT_FLOAT16, DT_BF16})` 驱动双 dtype 烘焙；`this->MC2().HcclGroup("group")`（`:74`） |
+| `x_all_gather_matmul_proto.cpp` | `IMPL_OP_INFERSHAPE(XAllGatherMatmul).InferShape(...).InferDataType(...)`（infershape **与 infer dtype 一起注册**）；infershape 调 `AllGatherMatmulCommonInferShape(context, GATHER_OUT_V1)`（见 §4）→ `y=[dimM*rankSize, dimN]`、`gather_out=[dimM*rankSize, dimKX1]`（`is_gather_out=false` 时为 `[0]`） |
+| `op_api/aclnn_x_all_gather_matmul.{cpp,h}` | **aclnn 两段式 C 接口**：`aclnnXAllGatherMatmulGetWorkspaceSize(x1, x2, bias, group, gatherIndex, commTurn, streamMode, output, gatherOut, workspaceSize, executor)` + `aclnnXAllGatherMatmul(workspace, workspaceSize, executor, stream)`；`group` 为 `const char*`（由 torch_npu 分布式创建的 HCCL 通信域名）；`output`/`gatherOut` 由调用方预分配、在第一段就要传入 |
+| `op_tiling/x_all_gather_matmul_tiling_base.{cpp,h}` | tiling 基类（508 行）：`Mc2CcTilingConfig(group, tilingData->param.commtype, algConfig)`（`:444`）填充 `mc2InitTiling`/`mc2CcTiling`（`:449-450`）；`param.commtype` 在 `:478` 置 `AicpuComType::HCCL_CMD_ALLGATHER`；`SetSkipBufferWindowCopy`（`:448`）按 `gatherLen` 选 `MC2_BUFFER_TYPE_DEFAULT`/`MC2_BUFFER_TYPE_OUTPUT` |
+| `op_tiling/x_all_gather_formulaic_tiling.{cpp,h}` | `XAllGatherPlusMM : public OneCalcOneCommBase`（`:30`，算子专属公式化 tiling） |
+| `op_tiling/arch22/x_all_gather_*_a2a3.{cpp,h}` | `XAllGatherPlusMMA2A3 : public XAllGatherPlusMM`（`x_all_gather_formulaic_tiling_a2a3.h:23`）——**A2 具体子类**，实例化 `SocVersion::SOC910_B`（`x_all_gather_matmul_tiling_a2a3.cpp:53`）；`algConfig = "AllGather=level0:fullmesh"`（`:46`）；`IMPL_OP_OPTILING(XAllGatherMatmul)`（`:69`） |
+
+## 3. op_kernel 分工（device 侧 / AIC-only）
+
+核心事实（grep 实证，[`x_all_gather_matmul_full_mesh.h`](all_gather_matmul/x_all_gather_matmul/op_kernel/x_all_gather_matmul_full_mesh.h)）：
+
+- **整算子 AIC-only**：HCCL prepare/Wait/Finalize 与 Matmul 都在 **`if ASCEND_IS_AIC { … }`** 正向门控内执行（`:75,101,220`）；AIV 不执行算子主体。这与通算融合指南的 `ASCEND_IS_AIV` 早返回 + `#define ASCENDC_CUBE_ONLY` 蓝本等价（`算子实现.md:451-457,549`）。**不是** `g_coreType==AIV` 门控。**Finalize 前需跨核同步**：`HcclFinalize()`（`:218`）用 `CrossCoreSetFlag<0,PIPE_FIX>(EVENT_ID_6)`+`CrossCoreWaitFlag(EVENT_ID_6)`（`:224-225`）后 `hccl_.Finalize()`（`:226`）——非 `SyncAll<true>()` 但效果等同。
+- **HCCL 对象**：`Hccl<HCCL_SERVER_TYPE_AICPU> hccl_;`（`:46`，无 config 模板参=DEFAULT，运行时由 `ASCEND_IS_AIC` 门控）。
+- **生命周期（V2）**：`hccl_.InitV2(contextGM, tilingData); hccl_.SetCcTilingV2(offsetof(Mc2Tiling::XAllGatherMatmulTilingData, mc2CcTiling));`（`:57-58`）。蓝本已用 V2；V1 `Init`/`SetCcTiling` 已废弃（A2 仍支持），详见 [`comm_hccl.md`](comm_hccl.md) §2。
+- **AllGather**：主块 `hccl_.AllGather<true>(...)`（`:89`）恒发；尾块（`:92`）仅在 `cfg.tailCnt > 0` 时发（`:91` 条件）。`<true>`=prepare 时同步通知服务端。
+- **融合循环**：`MatmulKernelCompute` 中逐 tile `hccl_.Wait(handleId)`（`:143`）→ 跳过本 rank（`:149-150`）→ `mm.Compute(index)`（`:161`，AIC 计算）；L2CACHE 变体 `MatmulKernelComputeL2Cache` 同结构，`Wait` 在 `:188`。
+- **Finalize**：`HcclFinalize()`（`:218` 封装，`:220` AIC 门控）内 `CrossCoreSetFlag<0,PIPE_FIX>(EVENT_ID_6)`（`:224`）+ `CrossCoreWaitFlag(EVENT_ID_6)`（`:225`）→ `hccl_.Finalize()`（`:226`，默认 = `Finalize<true>`）。
+- **context**：`GM_ADDR contextGM = GetHcclContext<HCCL_GROUP_ID_0>();`（`x_all_gather_matmul.cpp:71`，index∈{0,1} 最多 2 通信域）。
+
+| 文件 | 职责 |
+|------|------|
+| `x_all_gather_matmul.cpp` | kernel 入口：`extern "C" __global__ __aicore__ void x_all_gather_matmul(aGM, bGM, biasGM, cGM, gatherOut, workspaceGM, tilingGM)`（`:61-62`，**不是 `REGISTER_KERNEL`**）；`REGISTER_TILING_DEFAULT(Mc2Tiling::XAllGatherMatmulTilingData)`（`:64`）；取 HCCL context；dispatch `XAllGatherMatmulFullMesh` |
+| `x_all_gather_matmul_base.h` | 公共基类（成员/初始化 + `MatmulKernelLocal()`，`:134-150`） |
+| `x_all_gather_matmul_full_mesh.h` | AIC-only 融合主类（230 行）：HCCL 生命周期 + `MatmulCompute` 调用 + 本地 rank 先算 |
+| `x_all_gather_matmul_tiling.h` | device 侧 tiling 类 `XAllGatherMatmulTilingData`（**`Mc2InitTiling` 必为首字段**） |
+| `x_all_gather_matmul_tiling_key.h` | tiling key 定义 |
+
+> 本地 rank 先算：AllGather 输出含本卡数据，`InnerProcess()` 先调 `this->MatmulKernelLocal()`（`:104`）算本卡，与首轮通信重叠；随后的远端循环里再用 `if (rank == this->rankId_) { continue; }`（`:149-150`）跳过本 rank，避免重复计算——通算两层流水的关键（`算子实现.md:111,514`）。注意跳过逻辑在 `MatmulKernelCompute` 内，`MatmulKernelLocal()` 自身不含该判断。
+
+## 4. mc2_common 可复用框架（"经验"）
+
+`x_all_gather_matmul/mc2_common/`（**在算子目录内部，不是工程根下的独立目录**）是 vendor 自上游 `ops-transformer/mc2`（<https://gitcode.com/cann/ops-transformer>，未在 cannbot 挂载；蓝本已剥离为自包含示例工程，vendor 副本即权威、不依赖上游仓库）的**通用框架**，跨 MC2 算子原样复用。新算子只改 `op_host`/`op_kernel` 的算子专属文件，`mc2_common/` 基本不动。分四块：
+
+### 4.1 op_host/op_tiling（host 侧 tiling 基础设施）
+- `formulaic_tiling_datatype.h`：核心枚举/常量。`enum class SocVersion{SOC910_B,SOC310_P,SOC910_93,SOC910_B4,SOC950}`、`enum class KernelType{ALL_REDUCE,ALL_GATHER,REDUCE_SCATTER,ALL_TO_ALL,REDUCE_SCATTER_VIA_ALL_TO_ALL,ALL_REDUCE_VIA_TWO_SHOT}`、`enum class MatmulCalcType{FP16,QUANT,ANTI_QUANT}`、`enum class HCCLType{FULL_MESH,DOUBLE_RING,SWITCH,RING_RANK2_310P,RING_RANK4_310P}`、`enum class TopoType{STANDARD_CARD(4P),EIGHT_P(8P)}`、`struct MatmulParameters/.../HCCLFittingParameters/CutResult/TileArguments/TilingBestBaseBlock`（默认 baseM=256/baseN=256/baseK=128，`:157-159`）。
+- `mc2_tiling_struct.h`（host 副本）：**trimmed**，仅留常量 `COMM_ALG_FULL_MESH=1`、`KVALUE_MIN=256`、`KVALUE_MAX=65535`；注释指向 kernel 副本。
+- `mc2_tiling_utils.{h,cpp}`（`namespace mc2tiling`）：`GetNpuArch`（用 `platform_ascendc::PlatformAscendC::GetCurNpuArch`，替代已移除的 `GetSocVersion`）、`GetMaxWindowSize`（读 `HCCL_BUFFSIZE`，默认 200MB，`cpp:209-222`）、`supportedRankSizeSet`（**DAV_2201={1,2,4,8}**，`h:205-209`）、`GetRankSize`（调 `Mc2Hcom::MC2HcomTopology::CommGetInstSizeByGroup`）、`ConvertGeTypeToHcclType`/dtype-size maps、`CheckSuppportedFormat`（仅 `ge::FORMAT_ND`）。**另含 A2 相关容量常量**：`AICPU_NUM_BLOCKS_A2=6`（`h:79`）、`ALL_GATHER_HCCL_MEM_LIMIT=256MB`（`h:87`）、`ALL_GATHER_HCCL_NUM_LIMIT=16`（`h:88`）。> 注意：`CheckSuppportedFormat` 只认 ND，但通用入参校验 `CommonParamCheck` 走的是另一张更宽的 `SUPPORTED_FORMAT` 表（含 NCL/NCDHW/NHWC 等，`h:211-213`），两者不要混淆。
+- `matmul_formulaic_tiling.{h,cpp}`（`namespace mc2tiling`）：`class MatmulFormulaicTiling`——`GetCubeTiling(TilingArgs&, TCubeTiling&, [TileL2Tiling&])`、`static GetRankSize(group)`、`SetSocVersion`、`GetBaseBlockParm`；常量 `BASE_BLOCK_M/N/K=128/256/64`（`:37-39`）、`L1_SIZE`、`L0C_SIZE_DB_ON=128KB`（`:50`）、`enum MC2_BUFFER_TYPE`（`:117-126`，枚举值**带前缀**：`MC2_BUFFER_TYPE_DEFAULT=0`/`_OUTPUT`/`_WINDOW_IN`/`_WINDOW_OUT`/`_WORKSPACE`/`_INPUT`/`_COMMOUT`/`_END`）、`struct TilingArgs`（`:159-194`，含 cmdType/rankDim/usedCoreNum/orgM/N/K/aicCoreNum/commTurn/commAlg/isATrans/isBTrans/isBias/...）、`struct SoCInfo`（`:263-271`，`platform_ascendc::SocVersion socVersion = ASCEND910B`）。
+- `hccl_performance.{h,cpp}`：`class HCCLPerformanceModel`——`CommTime`/`InverseCommTime`（分段抛物→线性）、`GetRankTileNum`（非 ALL_REDUCE 走 `GetFullMeshRankTileNum`，ALL_GATHER→`rankDim-1`；ALL_REDUCE→1，`cpp:102-114`）、`GetLinearThresholdLen`；常量 `HCCL_MIN_TILE_LEN=64KB`（`:21`）、`FULL_MESH_TIME_FACTOR=2.0`（`:24`）、`FITTING_RANK=8`（`:29`）、`LOCAL_REDUCE_FACTOR=0.4`（`:30`）。
+- `matmul_performance.{h,cpp}`（`namespace MatmulPerformance`）：`class MatmulPerformanceModel`——`MatmulTime`/`InverseMatmulTime`/`FindCubeUtil`/`GetMatmulGradient`；常量 `COMPUTES_PER_CYCLE=4096`（`:21`）、**`MARK_CORE_NUM_SOC910B=20`**（`:30`）、`CYCLE_PER_MICRO_SEC=1.8*1024`（`:32`）、`MAX_CUBE_UTIL=0.95`（`:54`）、`AVERAGE_CUBE_UTIL=0.75`（`:55`）。
+- `hccl_formulaic_tiling.{h,cpp}`：**`class FormPartition`**（`:45`，M 轴切分：`GenerateInitialPartition`/`FitTileLengthDiscrete/Continuous`/...）+ **`class OneCalcOneCommBase`**（`:112`，公式化 tiling 基类，组合 `MatmulPerformanceModel`+`HCCLPerformanceModel`+`FormPartition`）；常量 **`MAX_TILE_CNT=16`**（`:38`）、`commGrowRatio=1.15`（`:39`）、`ALLGATHERMM_COMMTIME_FACTOR=2`（`:40`）、`ALLREDUCE_COMMTIME_FACTOR=2.0517`（`:41`）、`REDUCESCATTER_COMMTIME_FACTOR=2.09136`（`:42`）（详见 [`pipeline_tuning.md`](pipeline_tuning.md) §5）。
+- `mc2_common_infershape.{h,cpp}`（`namespace ops`）：`AllGatherMatmulCommonInferShape(context, gatherIndex)`——属性槽常量 `GROUP=0/AG_IS_TRANS_A=1/AG_IS_TRANS_B=2/RANK_SIZE=5/GATHER_OUT_V1=6/GATHER_OUT_V2=8`（`h:24-34`）；输出 `y=[dimM*rankSize,dimN]`（`cpp:112-113`）、`gather_out=[dimM*rankSize,dimKX1]`（`cpp:128-130`）或 `[0]`（`cpp:132-133`）。> 注意两点坑：① 本算子只有 7 个属性（槽位 0–6），`GATHER_OUT_V2=8` 是给属性布局不同的其它 MC2 算子留的，本算子传 `GATHER_OUT_V1`；② 形参名叫 `gatherIndex`，实际索引的是 `is_gather_out` 属性槽，不是 `gather_index` 属性。
+
+### 4.2 op_kernel（device 侧可复用 helper）
+- `mc2_matmul_compute.h`：**`template <class A_TYPE, class B_TYPE, class C_TYPE, class BIAS_TYPE, SplitType T> class MatmulCompute`**（`:22-23`）——是 `MatmulImpl<A_TYPE, B_TYPE, C_TYPE, BIAS_TYPE, CFG_MDL> mm_` 的封装（`:44`），`Init→SetSingleShape/SetTensorA/B/SetBias→Iterate→GetTensorC` 循环 + **`SetFlag`/`WaitFlag<HardEvent::FIX_M>`** 同步（`:130-132,161-162,195-196`，配 `GetTPipePtr()->FetchEventID`；**不是** `CrossCoreSetFlag`）；`typename BlockType<T>::PARAMS block_` 选块策略。
+- `mc2_matmul_block.h`：`class MatmulBaseBlockMC2`——多核块索引/偏移（`mBlockCnt/nBlockCnt/totalBlockCnt`、`GetBlockStartIdx`/`UpdateBlockParams`/`CalcGMOffset`）。行/列序与原子写的实际写法（`:83-92`）：`isRowOrder` 默认 `true`，仅当 `tiling_.N > 5 * tiling_.M` 时置 `false`；`isAtomic` 默认 `false`，仅当 `isTransA` 时置 `true`。
+- `mc2_matmul_block_l2cache.h`：`class MatmulBaseBlockL2Cache: public MatmulBaseBlockMC2`（L2 分裂变体）+ **`enum SplitType{DEFAULT=0,L2CACHE=1}`**（`:142-146`）+ `BlockType<DEFAULT|L2CACHE>::PARAMS` 选型（`:149-163`）。
+- `mc2_nd_to_nz.h`（580 行）：ND→NZ 转换 + **`g_coreType` 在此合法**（`SET_G_CORE_TYPE_IS_AIV/AIC` 宏定义在 `:22-28`，判定在 `:98`（`!= AIV`）、`:479`（`== AIV`，AIV 转 NZ）、`:531`（`== AIC`，AIC 消费））+ `CastBFtoFloat`（`:529`，`__CCE_AICORE__==220` AIC 分支 `:530-531`）。**注意**：`g_coreType` 是 ND2NZ helper 的 AIV/AIC 分工机制，**不是** HCCL 门控（HCCL 用 `ASCEND_IS_AIC`）。
+- `mc2_tiling_struct.h`（kernel 副本）：**full** structs，`namespace Mc2Tiling` 共 7 个：`MC2ServerCfg`/`MC2HcommCfg`（含 `skipBufferWindowCopy` `:37`、`stepSize` `:38`）/`Mc2Msg`（含 `notifyOff` `:64`/`notifyBeginCnt` `:66`/`notifyEndCnt` `:67`）/`RCSTiling`（rankDim/rankID/commtype/tileCnt/tailM/rankM/N/K/isTransposeA/B/gatherLen/aicCoreNum/dataType/...）/`TileL2Tiling`（mL2TileCnt/nL2TileCnt/enableL2Tile/...）/`TileInfo`/`MC2MatmulV3TilingData`；另有 constexpr `COMM_ALG_FULL_MESH`/`KVALUE_MIN`/`KVALUE_MAX`。
+
+### 4.3 utils
+- `mc2_hcom_topo_info.{h,cpp}`（`namespace Mc2Hcom`，`class MC2HcomTopology`）：**eager 模式** rank 解析——`HcclLibLoader` dlopen `libhccl.so`（经 `ASCEND_HOME_PATH` 定位 `x86_64-linux/lib64` 或 `aarch64-linux/lib64`，`cpp:39-51`）后 dlsym `HcomGetRankSizeEx`；`CommGetInstSizeByGroup`/`CommGetGroupLocalWindowSize`（失败回退 `GetMaxWindowSize()`）/`TryGetGroupTopoType`（失败时默认 `COMM_MESH`/FullMesh）。三者都有 `#ifdef BUILD_OPEN_PROJECT` 两套分支（`build.sh` 恒传 `-DBUILD_OPEN_PROJECT=ON`）；图模式下 `MC2HcomTopology` 另走 `libhccl_fwk.so`（`cpp:95-110`）。> 经验：本 A2 单算子工程用 eager 路径；多机/非 fullmesh 需 graph 模式（torchair）。> 这也是为什么构建/运行前必须先 `source set_env.sh`——`libhccl.so` 不在默认 `LD_LIBRARY_PATH` 里时，dlopen 与 `import torch_npu` 都会失败。
+- `ops_utils.h`（`namespace OpsUtils`）：`Ceil/CeilAlign/CeilDiv/FloorDiv/Aligned/FloorAlign` 等模板工具。
+- `hcom_topo_info.h`：vendor 的 `ge::HcomTopoInfo`（topo/rank_size/local_window_size 查询）。
+
+### 4.4 tiling 类层级（算子专属层叠在 mc2_common 之上）
+```
+OneCalcOneCommBase     (x_all_gather_matmul/mc2_common/op_host/op_tiling/hccl_formulaic_tiling.h:112)
+   ↑
+XAllGatherPlusMM       (x_all_gather_matmul/op_host/op_tiling/x_all_gather_formulaic_tiling.h:30)   算子专属
+   ↑
+XAllGatherPlusMMA2A3   (x_all_gather_matmul/op_host/op_tiling/arch22/x_all_gather_formulaic_tiling_a2a3.h:23)  A2 具体子类
+   实例化 (x_all_gather_matmul_tiling_a2a3.cpp:53):
+     XAllGatherPlusMMA2A3 tileFormulate(args, args.rankDim, KernelType::ALL_GATHER, SocVersion::SOC910_B);
+```
+
+## 5. 可复用性经验（新算子起手）
+
+| 改动范围 | 文件 | 说明 |
+|---------|------|------|
+| **原样复用（vendor 不动）** | `x_{op}/mc2_common/**` | 整套通用框架，跨算子不变 |
+| **原样复用** | `cmake/**`、`build.sh`、`CMakeLists.txt` | 构建框架 |
+| **改算子名/输入输出/dtype** | `op_host/*_def.cpp`、`*_proto.cpp` | IRD + DataType 列表（驱动双 dtype 烘焙） |
+| **改 aclnn 接口** | `op_host/op_api/aclnn_*.{cpp,h}` | 两段式签名 |
+| **改 tiling** | `op_host/op_tiling/*_base.{cpp,h}`、`*_formulaic_tiling.{cpp,h}`、`arch22/*_a2a3.{cpp,h}` | 算子专属 + A2 子类 |
+| **改融合主体** | `op_kernel/*.cpp`、`*_base.h`、`*_full_mesh.h`、`*_tiling.h`、`*_tiling_key.h` | HCCL 蓝本 + MatmulCompute 调用 |
+| **生成 PTA** | 不在本路线提供 | 算子可跑通后走 `ops/torch-ascendc-op-extension` 路线 B |
+| **改测试** | `examples/golden.py`、`single_server_*`、`run_test.sh` | golden + 多轮随机 shape/dtype |
+
+> 经验：`mc2_common` 是"算子=通信+计算+复用框架"中的"复用框架"层；新算子的 80% 工作量在 `op_host/op_tiling`（切分策略）与 `op_kernel/*_full_mesh.h`（通算两层流水编排），`mc2_common` 几乎零改动。
+
+## 6. aclnn 注册模型（构建链）
+
+```
+op_host/*_def.cpp  ──[OP_BUILD_TOOL/ascendc_impl_build.py]──▶  aclnn op_api（aclnnXxxGetWorkspaceSize + aclnnXxx）自动生成
+op_host/op_tiling/* ──[tiling_key + opc]──▶  liboptiling.so（含 tiling key 注册）
+op_kernel/*.cpp     ──[opc per-dtype 烘焙]──▶  per-dtype kernel binary（multi_kernel 运行时择）
+                                                        ↓
+                    install(... DESTINATION packages/vendors/${VENDOR_NAME}/...)
+                                                        ↓
+                              CPack/makeself ──▶  build/custom_opp_<arch>.run（含 libcust_opapi.so）
+                                                        ↓ 运行时
+                              export ASCEND_CUSTOM_OPP_PATH=<vendors/custom_opp 绝对路径>
+```
+
+- `x_all_gather_matmul/CMakeLists.txt`：vendored mc2_common 的 7 条 `-I` include（`:101-107`：`op_kernel`/`mc2_common/op_kernel`/`mc2_common/op_host`/`mc2_common/op_host/op_tiling`/`mc2_common/utils`/`mc2_common`/`mc2_common/op_api`——最后一条目录在蓝本中并不存在，是无害的空占位）；kernel 编译选项完整为 `--cce-auto-sync=off -DHCCL_COMM -Wno-deprecated-declarations -Wno-error=option-ignored -mllvm -cce-aicore-hoist-movemask=false`（`:116-121`）；host include 根 `_X_AGM_HOST_INC`（`:124-161`）= 10 条工程内路径 + 按 `aarch64-linux`/`arm64-linux`/`${CMAKE_SYSTEM_PROCESSOR}-linux` 探测追加的 5 个 CANN 根（`include/op_common`、`pkg_inc`、`include/external`、`asc/include/tiling`、`include/platform`），显式加是为避免与 intf_pub 的 register/graph 头冲突。`ascendc/include` 属 kernel 侧 `-I`（`:22-28`），不在 host include 根内。
+- `optiling` target 的源文件**显式列出**（无 `file(GLOB)` 跨 mc2_common，`:169-180`）：4 个算子专属（`x_all_gather_matmul_tiling_base.cpp`、`x_all_gather_formulaic_tiling.cpp`、`arch22/x_all_gather_matmul_tiling_a2a3.cpp`、`arch22/x_all_gather_formulaic_tiling_a2a3.cpp`）+ 6 个 vendored mc2_common（`hccl/matmul_formulaic_tiling`+`*_performance`+`mc2_tiling_utils`+`mc2_hcom_topo_info`），共 10 个。
+- `opsproto`（infershape，`:192-195`）含 `op_host/x_all_gather_matmul_proto.cpp` + vendored `mc2_common/op_host/mc2_common_infershape.cpp`（后者必须在 opsproto 以解析 `AllGatherMatmulCommonInferShape` 符号）。
+
+## 7. 后续阅读
+
+| 想了解 | 读 |
+|--------|-----|
+| 通信层 HCCL V2 生命周期 | [`comm_hccl.md`](comm_hccl.md) |
+| 计算层 AscendC::Matmul | [`matmul_fusion.md`](matmul_fusion.md) |
+| 架构心智/AIC-only | [`mc2_architecture.md`](mc2_architecture.md) |
+| PTA 接口生成 | `ops/torch-ascendc-op-extension` 路线 B（aclnn 注册） |
+| 改造食谱（按文件） | [`codebase_map.md`](codebase_map.md) |
+| tileCnt 调优 | [`pipeline_tuning.md`](pipeline_tuning.md) |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/hccl-matmul/pipeline_tuning.md

@@ -0,0 +1,47 @@
+# hccl-matmul 通算并行调优（tileCnt，910B / A2）
+
+两阶段策略（`tileCnt=1` 串行基线 → 扫描找最优）与 `headMSize = M / tileCnt` 概念复用 [`../../shared/pipeline_tuning.md`](../../shared/pipeline_tuning.md)，**本文不重复**。下文只写本路线差异。
+
+> 蓝本：[`all_gather_matmul/`](all_gather_matmul)。A2 上 `algConfig` 为预留字段，仅 FullMesh。
+
+## 1. 本路线的 tileCnt 含义
+
+`tileCnt` = M 轴切分块数，作为 `AllGather<true>(..., repeat=tileCnt)` / `AllReduce(..., repeat=tileCnt)` 的 repeat；逐 tile `Commit`/`Wait` 与 Matmul 流水。蓝本代码以 `tileTiling.M` / `tailTiling.M` 体现单 tile M 长度，无 `headMSize` 字面量。
+
+## 2. A2 特有约束
+
+| 约束 | 说明 | 违反后果 |
+|------|------|----------|
+| 一通信域 Prepare ≤ 63 | A2 上限（不含 A3 的 `InterHcclGroupSync`） | Prepare 失败 |
+| 扫描候选 | `{1,2,4,8,16}`（`MAX_TILE_CNT=16`） | 超过公式化 tiling 默认上限 |
+| NZ 外轴 16 对齐 | 单 tile M 按 dtype block 对齐 | MMAD 报错 |
+| UB 192KB / L0C 128KB | 单 tile 须 fit | OOM / tiling 失败 |
+| 无 doublering | A2 仅 FullMesh | 误传也不生效 |
+
+**无需 950 的 L2 flush**：本路线通信由 AICPU 执行，不占 AI Core L2 residency。采集流程仍复用 [`../../shared/profiling_mc2.md`](../../shared/profiling_mc2.md) 的 msprof task-based 与多卡 last-N 取 max；跳过 `heavy_add_kernel`。
+
+## 3. 公式化 tiling 系数（MC2-repo 辅助，非官方 API）
+
+蓝本权威副本：`all_gather_matmul/x_all_gather_matmul/mc2_common/op_host/op_tiling/`。系数以头文件为准，暂不需真机校准。
+
+| 来源 | 常量 |
+|------|------|
+| `hccl_formulaic_tiling.h` | `MAX_TILE_CNT=16`、`commGrowRatio=1.15`、`ALLGATHERMM_COMMTIME_FACTOR=2`、`ALLREDUCE_COMMTIME_FACTOR=2.0517`、`REDUCESCATTER_COMMTIME_FACTOR=2.09136` |
+| `hccl_performance.h` | `HCCL_MIN_TILE_LEN=64KB`、`FULL_MESH_TIME_FACTOR=2.0`、`FITTING_RANK=8`、`LOCAL_REDUCE_FACTOR=0.4` |
+| `matmul_performance.h` | `COMPUTES_PER_CYCLE=4096`、`MARK_CORE_NUM_SOC910B=20`、`CYCLE_PER_MICRO_SEC=1.8*1024`、`MAX_CUBE_UTIL=0.95`、`AVERAGE_CUBE_UTIL=0.75` |
+| `mc2_tiling_utils.h`（仅定义、蓝本无其它引用） | `AICPU_NUM_BLOCKS_A2=6`、`ALL_GATHER_HCCL_MEM_LIMIT=256MB`、`ALL_GATHER_HCCL_NUM_LIMIT=16` |
+
+A2 子类 `XAllGatherPlusMMA2A3` 硬编码 `SocVersion::SOC910_B`。A3 的额外 `*0.6` 因子不适用。
+
+## 4. 调优决策（本路线）
+
+```
+tileCnt=1 串行基线跑通（精度 + R1–R8）?
+  ├─ 否 → 修精度/审查
+  └─ 是 → 扫描 tileCnt ∈ {1,2,4,8,16}
+            ├─ cube_ratio<40% → 增 tileCnt
+            ├─ cube_ratio>70% → 减 tileCnt 或关 L2CACHE
+            └─ 选最优 → 写入 DESIGN.md
+```
+
+910B 核数：910B2 为 24 Cube / 48 Vector；910B3/B4 为 20/40。`SetBlockDim` 据实核数。

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/hccl-matmul/review-checklist.md

@@ -0,0 +1,39 @@
+# hccl-matmul 路线代码审查验收条件
+
+> Reviewer 在设计评审与阶段三验收逐项检查。违反任意红线项 = FAIL。本路线仅覆盖 Ascend 910B（A2 / dav-2201）。
+
+## 红线项
+
+| # | 检查项 | 验收条件 |
+|---|--------|---------|
+| R1 | 架构=910B(A2) | `grep -i "ascend910b\|dav-2201"` 命中；无 A3/910_93/950 |
+| R2 | 通信走 HCCL 高阶 V2 | 含 `Hccl<HCCL_SERVER_TYPE_AICPU>`、`InitV2`、`SetCcTilingV2`、`AllGather`/`AllReduce`/`Commit`/`Wait`/`Finalize`；V1 `Init`/`SetCcTiling` 应为空 |
+| R3 | Matmul 走 `AscendC::Matmul` | 含 `lib/matmul/matmul_intf.h` 或 `MatmulImpl`/`MatmulCompute`；无 Blaze |
+| R4 | 无 SHMEM/UDMA | `grep -rn "aclshmem"` 应为空 |
+| R5 | 无 Blaze | `grep -rni "blaze"` 应为空 |
+| R6 | AIC-only + Finalize 前跨核同步 | `ASCEND_IS_AIC` 命中；Finalize 前有 `CrossCoreSetFlag`/`CrossCoreWaitFlag`（非 `SyncAll`） |
+| R7 | 无 quant | `grep -rni "quant\|qbmm_mx\|copy_scale"` 应为空 |
+| R8 | 仅注册 / aclnn | 无 `<<<>>>` 直调入口；host 有 `MC2().HcclGroup("group")` |
+
+## 精度门禁
+
+| 融合方向 | 判据 |
+|----------|------|
+| 先通后算（AllGather+MM） | 误差元素比例 `<1e-2`，逐元素 `np.isclose`（fp16 `5e-3`，bf16 `1e-2`） |
+| 先算后通（MM+ReduceScatter/AllReduce） | 整体相对误差 `‖y_npu−y_fp32‖₂/‖y_fp32‖₂ ≤ 4ε`；不可照抄逐元素 `atol` |
+| scatter 类（各卡输出不同） | **逐 rank** 比对，不可只查 rank-0 |
+
+详见 [`workflow_integration.md`](workflow_integration.md) §1.4.1。
+
+## 常见 FAIL 原因
+
+| 现象 | 根因 | 修复方向 |
+|------|------|----------|
+| R2 命中 `hcomm_`/`aclshmem` | 误用 SHMEM/HCOMM | 改回 `Hccl<HCCL_SERVER_TYPE_AICPU>` V2 |
+| R5 命中 Blaze | 误抄 950 模板 | 换 `AscendC::Matmul` |
+| `Wait` 卡死 | Finalize 前缺跨核同步 | 加 `CrossCoreSetFlag/CrossCoreWaitFlag`（参考 `full_mesh.h:224-225`） |
+| 误用 `AlltoAllV` | A2 不支持 | 改 `AlltoAll`（等长） |
+| R7 命中 quant | 引入量化路径 | 删除 quant 文件 |
+| bf16 稳定超差 2%~3%（先算后通） | 判据不适用，非算子问题 | 换整体相对误差 `≤4ε` |
+| scatter 类精度"全过"但上层结果错 | 只校验了 rank-0 | 逐 rank 比对 |
+| 改了 kernel 仍跑旧结果 | `.run` 装成 `vendors/custom_opp/vendors/custom_opp` 嵌套，或 op_type 与内置算子撞名 | 改 `VENDOR_NAME` / `--install-path=`；op_type 加自定义前缀（蓝本用 `X`） |

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/hccl-matmul/workflow_integration.md

@@ -0,0 +1,152 @@
+# CANNBot 工作流在 910B（A2）MC2 场景的具体化
+
+本文档把 hccl-matmul 路线（910B / A2 / dav-2201，HCCL 高阶 API V2 + `AscendC::Matmul`，aclnn 单算子，无 quant）的设计/开发/验收门禁具体化。本路线仅覆盖 A2，不涉及 A3（910_93）。流程编排归属 plugin 层；本文只补充本路线技术要点。
+
+> 蓝本为已验证功能正常的 [`all_gather_matmul/`](all_gather_matmul)。
+
+> 工作流四阶段：**阶段一 需求与设计**（CP1/CP1.5/CP2）→ **阶段二 开发** → **阶段三 验收**（3.1 精度 / CP3 / 3.2 性能 / CP4）→ **阶段四 上库**（CP5）。
+
+## 阶段一：需求与设计
+
+### 1.1 开发准备（环境检查，门禁）
+
+按父级加载 `ascendc-env-check` + `ascendc-docs-search`，填 `operators/{op}/docs/environment.md`（状态行 `✅ 通过` 才继续）。
+
+| 校验项 | 命令/方法 | 失败处理 |
+|--------|-----------|----------|
+| NPU 架构 = dav-2201（A2） | `ascendcPlatform.GetCurNpuArch()` → `NpuArch::DAV_2201`；`GetSocVersion()` → `ASCEND910B` | 非 2201：本路线不适用（950 集合通信走 blaze-shmem/apace） |
+| 910B 子型号（B4 等） | **蓝本不做自动判定**：`x_all_gather_matmul_tiling_a2a3.cpp:53` 硬编码 `SocVersion::SOC910_B` 实例化公式化 tiling。`SOC910_B4` 枚举存在（`formulaic_tiling_datatype.h:46`），仅在 perf 模型的 K 对齐折扣分支被用到（`matmul_performance.cpp:185`，`K_UNALIGN_UTIL_RATIO_910_B4`） | 若目标是 B4 且性能模型偏差明显，需自行在 arch22 子类里按实际子型号传 `SOC910_B4` |
+| HCCL/Matmul 头 + 工具链 | CANN 官方仓库 <https://gitcode.com/cann/asc-devkit> 的 `docs/api/SIMD-API/高阶API/HCCL通信类`、`矩阵计算` 可读；`lib/matmul/matmul_intf.h`、`adv_api/hccl/hccl.h` 可解析；CANN（cann-9.1.0）+ bisheng + `ASCEND_CUSTOM_OPP_PATH` 就绪 | 确认 `ASCEND_HOME_PATH`/`ASCEND_OPP_PATH`/`ASCEND_CUSTOM_OPP_PATH` |
+| 硬件/仿真 | 真机或 `cannsim`（`ops-simulator`） | 无真机时优先 `ops-simulator` |
+
+### 1.2 需求分析（→ CP1 用户确认 → 1.2.5 spec 生成/评审 → CP1.5）
+
+按父级 spec-to-design 流程产出算子 spec（名称、数学定义、dtype、shape、通信原语）。MC2 场景须明确：通信算子类型（AllGather/AllReduce/ReduceScatter/AlltoAll/BatchWrite）、rankDim、是否 bias、是否 gather_out。
+
+### 1.3 设计（→ 1.3R 方案评审 → CP2）
+
+DESIGN.md + PLAN.md 必含：
+
+#### §三大约束显式确认
+```
+- 通信：HCCL in-kernel 高阶 API V2（Hccl<HCCL_SERVER_TYPE_AICPU>，A2 服务端仅 AICPU；InitV2+SetCcTilingV2，蓝本已用）；禁 SHMEM/HCOMM/窗口手动 MTE/RAC
+- 计算：AscendC::Matmul（Matmul 跑在 AIC/Cube 核，AIV 通知）；禁 Blaze
+- 流程：按注册形态工作流推进，不跳过设计/精度/性能验收
+- 本期不支持 quant
+```
+
+#### §切分策略
+- 通信算子类型；algConfig 在 A2 为预留字段，仅 FullMesh。
+- M 轴切分：`tileCnt`（指南 `tileNum`）+ `tailNum`∈{0,1}；主块/尾块/本地 rank 各一套 `TCubeTiling`。
+- 窗口优化：`SetSkipBufferWindowCopy` 由 `MC2_BUFFER_TYPE` 驱动（value 2 仅 AllReduce/AlltoAll）。
+
+#### §AIV/AIC 分工与 HCCL 下发模式
+- Matmul 在 AIC 计算、AIV 通知消费。
+- HCCL 与 Matmul 都在 AIC 执行（**AIC-only**，`if ASCEND_IS_AIC { … }` 门控，AIV 不执行主体）；**Finalize 前需跨核同步**：蓝本 `HcclFinalize()` 用 `CrossCoreSetFlag<0,PIPE_FIX>(EVENT_ID_6)`+`CrossCoreWaitFlag(EVENT_ID_6)`（`full_mesh.h:224-225`），非 `SyncAll<true>()` 但效果等同。HCCL V2（`InitV2`+`SetCcTilingV2`，蓝本已用）。详见 [`mc2_architecture.md`](mc2_architecture.md) §3/§4、[`comm_hccl.md`](comm_hccl.md) §2。
+
+### 1.4 测试设计（→ 1.4R 测试设计评审）
+- `examples/golden.py`：CPU fp32 参考（蓝本：gather dim0 → matmul → +bias）；`test_golden_cpu.py` 自测。golden 须**逐卡忠实**——每卡各自的输入分片分别参与运算，不要用"单卡输入 × rank_size"糊过去。
+- `examples/run_test.sh`：多轮随机 shape（M∈[1,64]、K/N 抽样）、fp16/bf16 与 bias 有/无按轮次奇偶交替（`isGatherOut` 恒为 1，未参与循环）；每轮 `RESULT: CHECK PASSED`。
+- 校验范围：**各卡输出不同**的算子（ReduceScatter/AlltoAll 类）必须**逐 rank 比对**。蓝本只读 rank-0 产物（`output` + `gather_out`）是因为 AllGather 后各卡输出相同；照抄到 scatter 类算子会漏掉 rank 块偏移算错的 bug。
+
+#### 1.4.1 精度判据按融合方向选择（不可照抄蓝本）
+
+| 融合方向 | 例 | 误差量级 | 判据 |
+|----------|----|----------|------|
+| 先通后算（通信在 Matmul 前） | AllGather+MM（蓝本） | ∝ `\|输出\|`——输出只经历一次"对自身"的舍入 | 蓝本判据可用：误差元素比例 `<1e-2`，逐元素 `np.isclose(rtol=atol=5e-3)`（bf16 `1e-2`），非严格 allclose |
+| **先算后通**（归约在 Matmul 后） | MM+ReduceScatter、MM+AllReduce | ∝ **加数**量级——部分积先按输出 dtype 落 workspace（那就是通信发送缓冲）再跨卡求和，故 `\|err\| ~ ε·\|partial\|`、`\|partial\| ~ rms(\|y\|)/√R` | **不可**沿用逐元素 `rtol`/`atol`：改用整体相对误差 `‖y_npu−y_fp32‖₂ / ‖y_fp32‖₂ ≤ 4ε`（fp16 `ε=2⁻¹¹`→`1.95e-3`；bf16 `ε=2⁻⁸`→`1.56e-2`），逐 rank 各判一次 |
+
+先算后通为什么会被逐元素判据系统性误判：randn 输入下 `y ~ N(0, σ)`，必然有一小撮元素 `|y| << σ`——它们是若干 `~σ/√R` 量级的加数**相消**出来的，却仍带着完整的 `ε·|partial|` 绝对误差。这些元素上 `rtol·|y|` 项塌缩到 0，只剩一个与数据量级无关的固定 `atol`，必然判 FAIL。**这是判据不适用，不是算子精度不够**；发送缓冲 dtype 必须等于通信 dtype，是先算后通结构的固有属性，改不掉。
+
+实测标定（MM+ReduceScatter，randn 单位输入，`K=12288`、`R=2`、bf16）：`rms(|y|) ≈ √K·√R ≈ 157`，舍入噪声 `σ_err ≈ 0.3·ε·rms(|y|) ≈ 0.18`；按 `|err| > atol + rtol·|y|`（`atol=rtol=0.02`）积分得超差元素比例 2.1%–2.6%，实测 **2.55%**——误差恰好等于 bf16 能达到的极限，无异常。fp16 同法算得约 0.33%，低于 1% 门限但余量仅 3 倍，所以会偶发踩线（现象是"bf16 几乎必挂、fp16 偶尔挂"）。
+
+整体相对误差以全局能量为分母，对相消免疫；纯舍入下约 `0.3ε` 且**与 `rank_size` 无关**（`rel_l2 ≈ 0.3ε` 与 R 无关，故阈值不必按卡数放大），取 `4ε` 留一个数量级余量。它不比逐元素判据弱：`err_ratio<1e-2` 本来就容忍不到 1% 的元素出错，而任何能让 1% 元素出错的 bug（某片/某 rank 块算错）在整体相对误差上是 `O(0.1)`，比 `O(ε)` 大两三个数量级。参考实现见 `matmul_reduce_scatter` 类算子的 `examples/single_server_check_result.py`。
+
+### Architect 加载顺序
+1. [`op_architecture.md`](op_architecture.md) → 2. [`mc2_architecture.md`](mc2_architecture.md) → 3. [`comm_hccl.md`](comm_hccl.md) → 4. [`matmul_fusion.md`](matmul_fusion.md) → 5. [`pipeline_tuning.md`](pipeline_tuning.md)（Matmul API 签名回 `ascendc-api-best-practices` 的 `api-matmul.md`）
+
+## 阶段二：开发（CP2 通过后）
+
+### 起手流程
+```bash
+cp -r references/all_gather_matmul operators/{op_name}
+cd operators/{op_name}
+# 0) CANN 环境（必须先 source，否则后续 import torch_npu 会找不到 libhccl.so）
+source /usr/local/Ascend/ascend-toolkit/set_env.sh
+# 1) 构建算子（.run + libcust_opapi.so；默认 SoC ascend910b，单次烘焙 fp16+bf16）
+bash build.sh -n x_{op_name}          # -n 的值必须 == 外层算子目录名（== OpDef 类名 snake_case）
+                                      # 产物 build/custom_opp_<arch>.run（仅 -b host 才拷到 output/）
+export ASCEND_CUSTOM_OPP_PATH=<vendors/custom_opp 绝对路径>
+# 2) PTA（若用户要在 PyTorch 里调）：走 torch-ascendc-op-extension **路线 B**（aclnn 注册）
+#    蓝本不提供 torch_ops_extension，不要在本路线内手写 PTA 层。
+# 3) 精度测试（多卡 mp.spawn + HCCL；依赖 PTA 已按路线 B 生成）
+bash examples/run_test.sh            # RESULT: CHECK PASSED
+```
+> 构建机制详见 [`op_architecture.md`](op_architecture.md) §6 与 [`codebase_map.md`](codebase_map.md) §5。HCCL context 由 torch_npu 分布式创建（非虚构 host launcher），见 [`comm_hccl.md`](comm_hccl.md) §7。PTA 生成见 `ops/torch-ascendc-op-extension/routes/aclnn-registry.md`。
+> ⚠️ 从 references 复制出来的工程与原工程会共用同一个 `VENDOR_NAME`（`custom_opp`）。同一环境里两份工程交替编译安装时，`.run` 容易装成 `vendors/custom_opp/vendors/custom_opp` 嵌套，运行时加载到旧版本——现象是"改了 kernel 却跑出旧结果"。给复制出的工程改一个不同的 `VENDOR_NAME`（顶层 `CMakeLists.txt:10`），或安装 `.run` 时用 `--install-path=` 显式指定，详见 [`codebase_map.md`](codebase_map.md) §5。
+
+### 开发阶段红线
+- 通信：只用 `Hccl<HCCL_SERVER_TYPE_AICPU>` 高阶 API **V2**（`InitV2`+`SetCcTilingV2`）；不得引入 `aclshmemx_*`/`hcomm_`/窗口手动 MTE/RAC/A2 不支持的接口（`AlltoAllV`/`Finalize<false>` 等）。
+- 计算：只用 `AscendC::Matmul`（或别名 `MatmulImpl`/`MatmulCompute` 封装）；不得引入 Blaze；不调 `SetLocalWorkspace`（A2 不支持）。
+- 不得引入 quant 代码。
+- HCCL/计算 AIC-only 门控（`if ASCEND_IS_AIC`）；**Finalize 前必跨核同步**（`CrossCoreSetFlag`/`CrossCoreWaitFlag`，非 SyncAll）。
+
+## 阶段三：验收
+
+### 3.1 精度验收（→ CP3）
+Reviewer R1–R7（见下）+ `bash examples/run_test.sh` 多轮 `CHECK PASSED`；精度报告归档 `docs/precision/summary.txt`。
+
+判据必须与融合方向匹配（§1.4.1）：先算后通的归约算子若照抄蓝本的逐元素 `rtol`/`atol`，会得出"bf16 精度不达标"的假结论并浪费一轮返工。判据选择与阈值须在 DESIGN.md 里写明理由。
+
+### Reviewer 速查（R1–R7）
+```bash
+R1: grep -i "ascend910b\|dav-2201" CMakeLists.txt x_{op}/CMakeLists.txt  # → ascend910b（默认）/dav-2201，无 A3/910_93/950
+R2: grep -rn "Hccl<HCCL_SERVER_TYPE_AICPU>\|InitV2\|SetCcTilingV2\|hccl_\.\(AllGather\|AllReduce\|AlltoAll\|Commit\|Wait\|Finalize\)" operators/{op}/
+R3: grep -rn "lib/matmul/matmul_intf.h\|AscendC::Matmul\|MatmulImpl\|MatmulCompute" operators/{op}/  # 无 Blaze
+R4: grep -rn "aclshmem" operators/{op}/                         # 应空
+R5: grep -rni "blaze" operators/{op}/                          # 应空
+R6: ls docs/                                                    # DESIGN/PLAN/WALKTHROUGH/REVIEW 齐全；environment.md ✅通过
+R7: grep -rni "quant\|qbmm_mx\|copy_scale" operators/{op}/     # 应空
+# HCCL 模式：grep "ASCEND_IS_AIC" 命中（AIC-only）；grep "CrossCoreSetFlag\|CrossCoreWaitFlag" 命中（Finalize 前同步，非 SyncAll）；
+#   V2（grep InitV2/SetCcTilingV2）；V1 Init/SetCcTiling 应为空（已废弃）
+```
+
+### 3.2 性能验收（→ CP4）
+```bash
+# 前置：build.sh -n x_{op_name} 已构建 + ASCEND_CUSTOM_OPP_PATH 已设 + PTA 已由 torch-ascendc-op-extension 路线 B 生成
+bash examples/run_test.sh                       # 精度基线
+msprof --application="python examples/single_server_run.py" --output=PROF_xxx --aic-metrics=... --task-based
+python scripts/extract_perf.py PROF_*/op_summary_*.csv   # 每卡 last N、跨 rank max
+```
+> 910B 走 HCCL（AICPU），无 SHMEM B-matrix residency 问题，**无需 950 的 L2 flush**；warm-up 仍建议。指南未述 L2 flush，此为本 skill 推理。
+- 两阶段 tileCnt 扫描：先 `tileCnt=1` 基线，再扫 {1,2,4,8,16}（A2 一通信域 Prepare≤63）。
+- perf 跑 ≥10 轮，多卡取每卡 last 5、跨 rank max；核数 `MARK_CORE_NUM_SOC910B=20`（910B3/B4 20-core 变体）。
+- 门禁：cube_ratio 40–70%、通信隐藏率符合 DESIGN.md。
+
+### 常见 FAIL
+| 现象 | 根因 | 修复方向 |
+|------|------|----------|
+| R2 命中 `hcomm_`/`aclshmem` | 误用 SHMEM/HCOMM | 改回 `Hccl<HCCL_SERVER_TYPE_AICPU>` V2 |
+| R5 命中 Blaze | 误抄 950 模板 | 换 `AscendC::Matmul` |
+| `Wait` 卡死 | Finalize 前缺跨核同步 | 加 `CrossCoreSetFlag/CrossCoreWaitFlag`（参考 `full_mesh.h:224-225`） |
+| 误用 `AlltoAllV` | A2 不支持 | 改 `AlltoAll`（等长） |
+| R7 命中 quant | 引入量化路径 | 删除 quant 文件 |
+| bf16 稳定超差 2%~3%、fp16 偶发（先算后通算子） | 判据不适用：相消元素被固定 `atol` 误判，**非算子问题** | 换整体相对误差 `≤4ε`（§1.4.1）；先看误差是否 ≈ `0.3·ε·rms(\|y\|)`，是则纯舍入 |
+| scatter 类算子精度"全过"但上层结果错 | 只校验了 rank-0（照抄蓝本），各卡不同的输出没查 | 逐 rank 比对（§1.4） |
+
+## 阶段四：上库（CP5）
+
+审查通过且精度+性能验收完成后，汇报：最终判定、总分、代码路径、精度概要（各 dtype 达标状态）、性能概要（Task Duration、cube_ratio、通信隐藏率）、关键问题列表。
+
+## 后续阅读
+
+| 想了解 | 读 |
+|--------|-----|
+| 算子架构与可复用框架 | [`op_architecture.md`](op_architecture.md) |
+| 910B MC2 心智模型 | [`mc2_architecture.md`](mc2_architecture.md) |
+| HCCL API 与 V2 生命周期 | [`comm_hccl.md`](comm_hccl.md) |
+| Matmul 接入（AIC） | [`matmul_fusion.md`](matmul_fusion.md) |
+| PTA 接口生成 | `ops/torch-ascendc-op-extension` 路线 B（aclnn 注册），本路线不重做 |
+| 性能采集 | [`../../shared/profiling_mc2.md`](../../shared/profiling_mc2.md)（本路线无需 L2 flush） |
+| tileCnt 调优 | [`pipeline_tuning.md`](pipeline_tuning.md) |
+| 基座工程改造 | [`codebase_map.md`](codebase_map.md) |