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

package/assets/ops-direct-invoke/skills/ascendc-api-best-practices/references/api-gathermask.md

@@ -0,0 +1,243 @@
+# GatherMask 使用指南
+
+> **适用场景**：从 interleaved 数据中按固定间隔提取元素时，替代逐元素 SetValue/GetValue 或 Host 侧列拆分。
+
+---
+
+## 目录
+
+- [概述](#概述)
+- [模式一：内置固定模式（built-in patterns）](#模式一内置固定模式built-in-patterns)
+  - [pattern 1-2：奇偶拆分](#pattern-1-2奇偶拆分)
+  - [pattern 3-6：列分量分离](#pattern-3-6列分量分离)
+- [模式二：用户自定义模式（custom Tensor mask）](#模式二用户自定义模式custom-tensor-mask)
+- [GatherMaskParams 结构](#gathermaskparams-结构)
+- [Normal vs Counter 选择](#normal-vs-counter-选择)
+- [tile 与循环结构约束](#tile-与循环结构约束-实测经验非官方约束)
+- [常见错误](#常见错误)
+- [检查清单](#检查清单)
+- [适用性检测](#适用性检测)
+- [参考资料](#参考资料)
+
+---
+
+## 概述
+
+GatherMask 提供三种用法模式：
+
+| 模式 | `src1Pattern` 类型 | 适用场景 |
+|------|-------------------|---------|
+| **内置固定模式 1-2** | `uint8_t` = 1 / 2 | 奇偶索引拆分（RoPE 等） |
+| **内置固定模式 3-6** | `uint8_t` = 3 / 4 / 5 / 6 | 每 4 元素取 1 个（列分量分离等） |
+| **用户自定义模式** | `LocalTensor<uint16_t/uint32_t>` | 非均匀间隔、复杂 mask 逻辑 |
+
+内置固定模式值（910B2C 全部支持）：
+
+| 值 | 二进制 mask | 语义 |
+|----|-----------|------|
+| 1 | 01010101… | 偶数索引 |
+| 2 | 10101010… | 奇数索引 |
+| 3 | 00010001… | 每 4 取第 1 |
+| 4 | 00100010… | 每 4 取第 2 |
+| 5 | 01000100… | 每 4 取第 3 |
+| 6 | 10001000… | 每 4 取第 4 |
+| 7 | 11111111… | 全取 |
+
+---
+
+## 平台适用性
+
+| 平台 | 适用性 | 说明 |
+|------|--------|------|
+| **A2 / A3**（DAV_2201） | ✅ 推荐 | 内置固定模式全部可用，是 RoPE 奇偶拆分、列分量分离的推荐方案 |
+| **A5**（DAV_3510） | ⚠️ 非首选 | A5 上有更高效的专用指令处理 RoPE 奇偶拆分和 interleaved 列分离，应优先使用专用指令而非 GatherMask |
+
+> 本指南中的模式、参数和约束均基于 A2/A3（DAV_2201）平台验证。A5（DAV_3510）平台开发者应优先查阅对应平台的专用指令文档。
+
+---
+
+## 模式一：内置固定模式（built-in patterns）
+
+### pattern 1-2：奇偶拆分
+
+```cpp
+// pattern 1: 偶数索引    pattern 2: 奇数索引
+uint64_t rsvdCnt = 0;
+LocalTensor<float> src = kvF32[offset];  // 零拷贝偏移
+
+GatherMask(dst, src,
+    static_cast<uint8_t>(1), true,               // pattern=1, Counter 模式
+    static_cast<uint32_t>(total_elements),       // 元素总数（非 half）
+    GatherMaskParams(1, 1, 8, 0), rsvdCnt);
+PipeBarrier<PIPE_V>();
+```
+
+**约束**：Normal/Counter 均可（官方示例用 Normal pattern=2）。`rsvdCnt` 声明为 `uint64_t` 初始化为 0。`count` 传元素总数。
+
+### pattern 3-6：列分量分离
+
+```cpp
+// pattern 3 (00010001): 每 4 取第 1    pattern 4 (00100010): 每 4 取第 2
+// pattern 5 (01000100): 每 4 取第 3    pattern 6 (10001000): 每 4 取第 4
+
+// Normal 模式: 每次 repeat 处理 256B = 64 float32 → 16 dst
+int32_t alignedLen = (tileLen / 16) * 16;
+uint16_t repeatTimes = alignedLen / 16;
+GatherMaskParams gmParams(1, repeatTimes, 8, 0);   // stride=8 (256B)，不可写成 1
+
+uint64_t rsvdCnt = 0;
+GatherMask(x1, src, static_cast<uint8_t>(3), false, 0, gmParams, rsvdCnt);
+GatherMask(y1, src, static_cast<uint8_t>(4), false, 0, gmParams, rsvdCnt);
+GatherMask(x2, src, static_cast<uint8_t>(5), false, 0, gmParams, rsvdCnt);
+GatherMask(y2, src, static_cast<uint8_t>(6), false, 0, gmParams, rsvdCnt);
+PipeBarrier<PIPE_V>();  // GatherMask 是 V 操作，等 V 完成
+
+// 尾块: tileLen 非 16 倍数时标量补齐（≤15 元素，开销可忽略）
+for (int32_t j = alignedLen; j < tileLen; ++j) {
+    int32_t off = j * 4;
+    x1.SetValue(j, src.GetValue(off));
+    ...
+}
+```
+
+**关键约束表**：
+
+| 参数 | 正确值 | 错误值 | 后果 |
+|------|--------|--------|------|
+| `src0RepeatStride` | `8` (8 DataBlocks = 256B) | `1` | 连续 repeat 重叠 224B → 精度全 fail |
+| 对齐粒度 | 16（Normal 每 repeat 输出 16 dst） | 8 | 不匹配 Normal 语义 |
+| `repeatTimes` | `alignedLen / 16` | `tileLen / 16`（不向下对齐） | 尾 repeat 源数据不足 256B |
+| GatherMask 后 | `PipeBarrier<PIPE_V>()` | 无 barrier | dst 被后续指令读为旧值 |
+
+---
+
+## 模式二：用户自定义模式（custom Tensor mask）
+
+当内置固定模式无法覆盖 mask 逻辑时（如非均匀间隔、不是按固定数量取元素），用 LocalTensor 传入自定义 mask：
+
+```cpp
+// src1Pattern: LocalTensor<uint32_t>，每个元素的二进制位 = 1 则选取、0 则跳过
+// 例如 0x99999999 = 1001_1001_... → 每 4 元素取第 1 和第 4
+LocalTensor<uint32_t> src1Local = inQueueSrc1.DeQue<uint32_t>();
+
+uint32_t mask = 70;          // Counter 模式: 每 repeat 处理 70 个源元素
+uint64_t rsvdCnt = 0;
+
+// reduceMode=true (Counter), repeatTimes=2, src0RepeatStride=4 (间隔 4 DataBlocks)
+// src1RepeatStride=0: 每次 repeat 复用同一个 src1Pattern
+AscendC::GatherMask(dstLocal, src0Local, src1Local,
+    true, mask,
+    GatherMaskParams(1, 2, 4, 0), rsvdCnt);
+```
+
+**关键差异**：
+
+| 特性 | 内置固定模式 | 用户自定义模式 |
+|------|------------|--------------|
+| `src1Pattern` 类型 | `uint8_t` 常量 | `LocalTensor<uint16_t/uint32_t>` |
+| `src1RepeatStride` | 无效（填 0） | 有效，控制 src1 迭代间步长 |
+| 数据类型匹配 | — | `half/uint16_t/int16_t` dst → `uint16_t` mask；`float/uint32_t/int32_t` dst → `uint32_t` mask |
+| Normal 模式 | ✓ | ✓ |
+| Counter 模式 | ✓ | ✓ |
+
+**典型场景**：需要自定义间隔（如每 5 取 2、非均匀采样）或 mask 值运行时决定时使用。
+
+---
+
+## `GatherMaskParams` 结构
+
+```cpp
+struct GatherMaskParams {
+    uint8_t  src0BlockStride;   // 单 repeat 内 DataBlock 步长，连续=1
+    uint16_t repeatTimes;       // Normal: 256B 块数；Counter: 与 mask 配合
+    uint16_t src0RepeatStride;  // 相邻 repeat 起始地址间隔（DataBlock 单位）
+    uint8_t  src1RepeatStride;  // 内置固定模式无效(填0)；用户自定义模式有效
+};
+// GatherMaskParams(src0BlockStride, repeatTimes, src0RepeatStride, src1RepeatStride)
+```
+
+Normal 模式：`repeatTimes = 总源元素数 / 64`，`src0RepeatStride = 8`（64 float × 4B / 32B = 8 DataBlocks）。repeatTimes=1 时 `src0RepeatStride` 可填 0。
+
+---
+
+## Normal vs Counter 选择
+
+| 模式 | `reduceMode` | 数据量控制 | 推荐场景 |
+|------|-------------|-----------|---------|
+| **Normal** | `false` | 每次 repeat 固定 256B，`mask` 无效 | built-in patterns 3-6（推荐，语义简洁） |
+| **Counter** | `true` | 每次 repeat 处理 `mask` 个元素 | pattern 1-2（RoPE 奇偶拆分）、用户自定义模式、built-in patterns 3-6（也可用） |
+
+两种模式均可搭配 built-in patterns 3-6。Normal 模式语义更清晰（固定 256B/repeat），优先推荐。
+
+> **官方约束**（CANN 8.5.0）：GatherMask 调用后接口内部自动重置为 Normal 模式。若混用 Counter 模式，调用后需显式重新设置。
+
+---
+
+## tile 与循环结构约束（※ 实测经验，非官方约束）
+
+**tile 大小**：tile 过小会导致 DMA 次数随 N 线性增长，压过 GatherMask 收益。**规则**：tile 填到 UB 上限。910B2C UB=248KB，GatherMask + compute buffers ≈112KB，tile ≥ 2048 安全。
+
+**循环结构**：解交织维度必须放外层循环。
+
+```
+✓ 解交织维度 OUTER — 解交织一次，内层全量复用  →  DMA O(N/tile)
+✗ 解交织维度 INNER — 每外层迭代重解交织        →  DMA O(M×N/tile²)
+```
+
+外层循环的数据 UB 常驻。小维度走标量 GM 读取即可，不要两侧都 GatherMask——增加 UB 压力无额外收益。
+
+---
+
+## 常见错误
+
+| 错误 | 原因 | 解决方案 |
+|-----|------|---------|
+| 精度全 fail，误差 > 0.3 | `src0RepeatStride=1`，连续 repeat 重叠 224B | 设为 `8`（8 DataBlocks = 256B） |
+| 混用模式后计算结果异常 | GatherMask 调用后自动切回 Normal | Counter 模式下调用后显式重新设置 |
+| 大 N 加速比退化到 <1x | tile < 512 且解交织维度放内层循环 | tile ≥ 2048 + 解交织维度放外层 |
+| 尾块数据错乱 | `repeatTimes = tileLen/16` 未向下对齐 | `alignedLen = (tileLen/16)*16`，尾块标量 |
+| dst 数据被读为旧值 | GatherMask 后未加 barrier | 添加 `PipeBarrier<PIPE_V>()` |
+| 用户自定义模式 dst 类型与 mask 类型不匹配 | half dst 配 uint32_t mask | half/uint16_t → uint16_t mask；float/uint32_t → uint32_t mask |
+
+---
+
+## 检查清单
+
+**参数配置**：
+- [ ] `reduceMode` 与模式匹配（patterns 1-2 Normal/Counter 均可，patterns 3-6 推荐 Normal）
+- [ ] `src0RepeatStride = 8`（Normal 模式 repeatTimes > 1 时）
+- [ ] `repeatTimes = alignedLen / 16`（内置固定模式，向下对齐到 16）
+- [ ] `rsvdCnt` 声明为 `uint64_t` 并初始化为 0
+- [ ] 用户自定义模式：mask Tensor 数据类型与 dst 匹配
+
+**tile 与循环**：
+- [ ] tile ≥ 2048（填到 UB 上限）
+- [ ] 解交织维度放外层循环
+- [ ] 不同时对两侧做 GatherMask（小维度走标量）
+
+**同步**：
+- [ ] GatherMask 后 `PipeBarrier<PIPE_V>()`
+- [ ] Counter 模式混用时注意自动切回 Normal 行为
+
+---
+
+## 适用性检测
+
+```bash
+# Host 侧列拆分 → 可用 built-in patterns 替代
+grep -nE "\.select\(.*\)\.contiguous\(\)" op_host/*.cpp
+
+# 逐元素 SetValue/GetValue 解交织 → 可用内置固定模式或用户自定义模式替代
+grep -nE "for.*SetValue.*GetValue|for.*GetValue.*SetValue" op_kernel/*.cpp
+
+# 检查现有 GatherMask 参数是否正确
+grep -nE "GatherMaskParams.*\{1.*repeatTimes.*1.*0\}" op_kernel/*.cpp      # stride=1，错误
+```
+
+---
+
+## 参考资料
+
+- CANN 8.5.0 API 文档 — GatherMask：`https://www.hiascend.com/document/detail/zh/canncommercial/850/API/ascendcopapi/atlasascendc_api_07_0071.html`
+- P100 卡片：GatherMask 替代逐元素 SetValue/GetValue（RoPE 奇偶拆分场景）
+- P101 卡片：GatherMask 替代 Host 侧列拆分

package/assets/ops-direct-invoke/skills/ascendc-api-best-practices/references/api-gmm.md

@@ -0,0 +1,260 @@
+# Ascend C GMM 高阶 API 最佳实践
+
+> **适用路径**：Ascend C **Matmul 高阶 API** 上的 GroupedMatmul（`MatmulImpl` + 分组调度）。
+> **适用平台**：Atlas A2 / A3（Ascend910B、Ascend910_93，NpuArch `DAV_2201`）。
+> **不适用**：Ascend 950（`DAV_3510`）GMM 实现 → 950 侧有独立实现路线，勿套用本文档。
+> **扩展策略**：当新架构出现时，按新架构 NpuArch 新增 reference 文件或更新现有平台适配说明。
+>
+> 适用算子：GroupedMatmul（分组矩阵乘）。
+> MatMul 通用 API（`MatmulImpl`、`MatmulConfig`、`IterateAll`、`SetHF32`、`TilingHeader` 加载等）见 [api-matmul.md](api-matmul.md)。本文档仅覆盖 GMM 差异化 API 和设计要点。
+
+---
+
+## 1. 分组 Shape 管理
+
+GMM 核心特征是**多组矩阵乘的 M/K/N 可能各不相同**，kernel 侧需要动态获取每组的 shape。
+
+### 1.1 Tiling 侧传递
+
+> **字段来源**：`GMMArray[128]` 数组规格来自 CANN 9.0.0 / asc-devkit 9.0.0（GroupedMatmul 算子 Tiling 头文件），具体版本以本地 `$ASCEND_HOME_PATH/include/` 为准；版本差异请用 `ascendc-docs-search` skill 查询。
+
+Host 端在 `GMMArray` 中填好 3 个数组（最多 128 组）：
+
+| 数组 | 字段 | 含义 | 特殊值 |
+|------|------|------|--------|
+| mList[128] | 每组 M 大小 | 各组 x 的有效行数 | `mList[0] == -1` 表示 M 由 groupList 提供 |
+| kList[128] | 每组 K 大小 | 各组的 K 轴大小 | 单 tensor 时仅 `kList[0]` 有效 |
+| nList[128] | 每组 N 大小 | 各组的 N 轴大小 | 单 tensor 时仅 `nList[0]` 有效 |
+
+### 1.2 Kernel 侧访问
+
+```cpp
+// 通过 tiling 数据获取
+GET_TILING_DATA_MEMBER(GMMTilingData, gmmBaseParams, gmmBaseParams_, tiling);
+GET_TILING_DATA_MEMBER_ADDR(GMMTilingData, gmmArray, gmmArrayAddr_, tiling);
+
+// 遍历分组时按组索引读取 shape
+for (uint32_t groupIdx = 0; groupIdx < gmmBaseParams_.groupNum; ++groupIdx) {
+    int32_t m = gmmArrayAddr_.mList[groupIdx];
+    int32_t k = gmmArrayAddr_.kList[groupIdx];
+    int32_t n = gmmArrayAddr_.nList[groupIdx];
+    // 按 (m, k, n) 执行该组的 MatMul ...
+}
+```
+
+**单 tensor 场景**（s-s-s / s-m-s / m-m-s）：`mList[0] == -1`，M 需从 groupList 动态读取；K/N 只用 `kList[0]` / `nList[0]`。
+
+**多 tensor 场景**（m-m-m）：`mList[i] / kList[i] / nList[i]` 三值均有效。
+
+### 1.3 GM 偏移累加
+
+多 tensor 场景下，各组数据在 GM 中拼接存放，需按组累加偏移：
+
+```cpp
+int64_t gmOffsetA = 0;  // x 的每组起始偏移
+int64_t gmOffsetB = 0;  // weight 的每组起始偏移
+int64_t gmOffsetC = 0;  // y 的每组起始偏移
+
+for (uint32_t groupIdx = 0; groupIdx < groupNum; ++groupIdx) {
+    int32_t m = /* ... */, k = /* ... */, n = /* ... */;
+    // 当前组使用偏移 gmOffsetA/gmOffsetB/gmOffsetC
+    // ...
+    // 下一组累加
+    gmOffsetA += m * k;
+    gmOffsetB += k * n;
+    gmOffsetC += m * n;
+}
+```
+
+---
+
+## 2. 分块索引计算
+
+GMM 以 `baseM × baseN` 为基本块进行核间分配，各组统一按最大 shape 划分：
+
+```
+mDim = ceil(maxM / baseM)        // M 方向块数
+nDim = ceil(maxN / baseN)        // N 方向块数
+totalBlocks = mDim × nDim × groupNum   // 总任务块数
+```
+
+Kernel 内部将 blockIdx 映射到具体的 (groupIdx, mIdx, nIdx)：
+
+```cpp
+const int32_t blockIdx = GetBlockIdx();
+if (blockIdx >= totalBlocks) return;  // 越界守卫
+
+// 块坐标 → 组坐标
+const int32_t blockPerGroup = mDim * nDim;
+const int32_t groupIdx = blockIdx / blockPerGroup;
+const int32_t innerIdx  = blockIdx % blockPerGroup;
+const int32_t mIdx = innerIdx / nDim;
+const int32_t nIdx = innerIdx % nDim;
+
+// 当前 base 块的实际大小（考虑尾块）
+const int32_t curM = (mIdx == mDim - 1) ? (M - mIdx * baseM) : baseM;
+const int32_t curN = (nIdx == nDim - 1) ? (N - nIdx * baseN) : baseN;
+```
+
+> 对角线分核时，blockIdx 到 (groupIdx, mIdx, nIdx) 的映射需按蛇形/对角线模式重新编排，本质不变。
+
+---
+
+## 3. 量化 Epilogue — Per-Token Dequant
+
+GMM 的量化场景（A8W8O16）在 MatMul 输出 int32 结果后，需要执行反量化流程。与通用 MatMul 直接用 `IterateAll` 写回不同，GMM 的量化 Epilogue 由 AIV 侧完成。
+
+### 3.1 数据流
+
+```
+GM_C(int32) → UB_C(int32)    // MatMul Cube 输出，写入 workspace
+GM_Scale(fp16/bf16) → UB_Scale(fp16/bf16)   // per-channel scale
+GM_PerTokenScale(fp16/bf16) → UB_PerTokenScale(fp16/bf16)  // per-token scale
+
+UB_C(int32) → Cast(fp32)
+    → Mul(RowBroadcast: ×UB_Scale_fp32)       // 逐列放缩
+    → Mul(ColumnBroadcast: ×UB_PerTokenScale_fp32)  // 逐行放缩
+    → Cast(fp16/bf16) → GM_Y
+```
+
+### 3.2 AscendC API 映射
+
+```cpp
+// === 1. 搬运 MatMul 输出 (int32) 到 UB ===
+// UB 由静态偏移分配，不通过 TPipe
+LocalTensor<int32_t> ubC = ubBuf.Get<int32_t>(offsetC);
+LocalTensor<int32_t> gmC;
+gmC.SetGlobalBuffer(reinterpret_cast<__gm__ int32_t*>(workspacePtr));
+DataCopyExtParams copyParam;
+copyParam.blockCount = 1;
+copyParam.blockLen   = tileRows * tileCols * sizeof(int32_t);  // 32B 对齐
+copyParam.rsv = 0;
+DataCopyPad(ubC, gmC[gmOffsetC], copyParam);
+
+// === 2. 搬运 Scale 到 UB ===
+LocalTensor<half> ubScale = ubBuf.Get<half>(offsetScale);
+LocalTensor<half> gmScale;
+gmScale.SetGlobalBuffer(reinterpret_cast<__gm__ half*>(scalePtr));
+copyParam.blockLen = tileCols * sizeof(half);
+DataCopyPad(ubScale, gmScale[scaleOffset], copyParam);
+
+// === 3. 搬运 PerTokenScale 到 UB ===
+LocalTensor<half> ubPerTokenScale = ubBuf.Get<half>(offsetPTS);
+LocalTensor<half> gmPerTokenScale;
+gmPerTokenScale.SetGlobalBuffer(reinterpret_cast<__gm__ half*>(ptsPtr));
+copyParam.blockLen = tileRows * sizeof(half);
+DataCopyPad(ubPerTokenScale, gmPerTokenScale[ptsOffset], copyParam);
+
+// === 4. 计算：int32 → fp32 ===
+LocalTensor<float> ubCfp32 = ubBuf.Get<float>(offsetTmp);
+Cast(ubCfp32, ubC, RoundMode::CAST_NONE, tileRows * tileCols);
+
+// === 5. Scale cast fp16 → fp32 ===
+LocalTensor<float> ubScaleFp32 = ubBuf.Get<float>(offsetTmp2);
+Cast(ubScaleFp32, ubScale, RoundMode::CAST_NONE, tileCols);
+
+// === 6. RowBroadcast Mul: float[tileRows * tileCols] × float[tileCols] ===
+Mul(ubMulFp32, ubCfp32, ubScaleFp32, tileRows * tileCols);
+
+// === 7. PerTokenScale cast + ColumnBroadcast ===
+LocalTensor<float> ubPtsFp32 = ubBuf.Get<float>(offsetTmp3);
+Cast(ubPtsFp32, ubPerTokenScale, RoundMode::CAST_NONE, tileRows);
+// 广播到 tileRows×tileCols
+// 方式一：逐行 Mul(repeatTimes=1, dstRepStride=tileCols, srcRepStride=0)
+Mul(ubResultFp32, ubMulFp32, ubPtsFp32, tileRows * tileCols);
+
+// === 8. Cast fp32 → fp16/bf16 写回 ===
+LocalTensor<half> ubResult = ubBuf.Get<half>(offsetOut);
+Cast(ubResult, ubResultFp32, RoundMode::CAST_RINT, tileRows * tileCols);
+DataCopyPad(gmY[gmOffsetY], ubResult, copyParam);
+```
+
+### 3.3 UB Buffer 分配
+
+量化场景 UB 需分块复用，以 per-token A8W8O16 为例：
+
+```
+ubCalSize = ubSize / ubDivideBlkNum              // 每块元素数
+ubCalSize = AlignDown(ubCalSize, ubBlockAlign)    // 对齐
+
+ubBaseK = perTokenOrPerGroupSize                  // K 方向分块粒度
+ubBaseN = min(BEST_UB_BASEN, AlignUp(ubCalSize / ubBaseK, MIN_UB_BASEN))
+```
+
+各 buffer 以 `ubCalcSize = ubBaseM × ubBaseN` 为基本单元份数分配：
+
+| Buffer | 份数 | 类型 | 用途 |
+|--------|------|------|------|
+| MatMul 输出 | 8 (DB×2) | int32 | Cube 结果暂存 |
+| 最终输出 | 4 | fp16/bf16 | dequant 后结果 |
+| 中间临时 | 16 | fp32 | Cast + broadcast + Mul 复用 |
+| **合计** | 28 份 | — | `28 × ubCalcSize × sizeof(type)` 需 ≤ ubSize |
+
+---
+
+## 4. Cube MatMul 接口（与通用 MatMul 共享）
+
+GMM 的 Cube 计算部分复用标准 `MatmulImpl`，差异在于：
+
+| 项目 | 通用 MatMul | GMM |
+|------|-----------|-----|
+| `MatmulImpl` 实例数 | 1 个 | 1 个（各组共用 Tiling 参数） |
+| `SetSingleShape` | 单组 (M,N,K) | 各组共用 (baseM, baseN, K) |
+| 分组管理 | 无 | 通过 blockIdx 映射到 groupIdx |
+| 多组间 offset | 无 | 需累加各组 A/B/C 的 GM offset |
+| Epilogue | `IterateAll` 直接写回 | AIV 侧 dequant 后写回 |
+
+### 4.1 纯 Cube 场景（非量化）
+
+```cpp
+// 纯 Cube 模式（AIC only），与通用 MatMul 几乎一致
+// 仅需 ADD 分组循环和 GM offset 计算
+if ASCEND_IS_AIV { return; }                              // 只有 Cube
+MatmulImpl<A_TYPE, B_TYPE, C_TYPE, BIAS_TYPE, CFG> mm;
+mm.Init(&mmTilingData_, &tPipe);
+
+for (auto blockIdx = GetBlockIdx(); blockIdx < totalBlock; blockIdx += blockDim) {
+    // 块坐标映射到 (groupIdx, mIdx, nIdx)
+    // 计算 curM/curN, offsetA/offsetB/offsetC
+    mm.SetSingleShape(curM, curN, K);
+    mm.SetTensorA(gmA[offsetA]);
+    mm.SetTensorB(gmB[offsetB]);
+    mm.IterateAll(gmC[offsetC], /*enAtomic=*/false);
+}
+mm.End();
+```
+
+### 4.2 量化 C+V 场景
+
+AIC 侧仅完成 MatMul 计算，不写回 GM；AIV 侧完成 dequant 后写回。两者通过 **workspace + cross-core sync flag** 通信：
+
+```
+AIC:  MatMul → workspace[coreIdx]
+      SetFlag → AIV
+AIV:  WaitFlag ← AIC
+      Dequant(workspace[coreIdx]) → GM_Y
+      SetFlag → AIC (释放 workspace)
+```
+
+---
+
+## 5. AIC/AIV 分职模式
+
+| 模式 | AIC 任务 | AIV 任务 | 触发条件 |
+|------|---------|---------|---------|
+| **Cube Only** | MatMul + 写回 GM | 无（直接返回） | 非量化 fp16/bf16/fp32 |
+| **C:V = 1:1** | MatMul → workspace | Dequant → GM | A8W8 perTensor / perToken 小 token |
+| **C:V = 2:1** | MatMul → workspace | Dequant → GM（双 Vector 核） | perToken + (K≤1024 或 K≥2048) + token≥128 |
+
+---
+
+## 6. 检查清单
+
+- [ ] GMMArray 的 mList/kList/nList 与 tensor 组合匹配（单/多 tensor 语义）
+- [ ] blockIdx 到 (groupIdx, mIdx, nIdx) 映射正确
+- [ ] 各组 GM offset 累加正确（注意数据类型和 NZ 格式 stride 差异）
+- [ ] 量化场景 UB 分块参数非零（ubDivideBlkNum / ubBlockAlign）
+- [ ] workspace 大小为 `usedCoreNum × baseM × baseN × sizeof(int32_t)` 的倍数
+- [ ] AIC/AIV cross-core sync flag 正确配对（SetFlag / WaitFlag）
+- [ ] Cube 完成后 `PipeBarrier<PIPE_AIC>()`；跨核 AIC→AIV 依赖用 flag 配对
+- [ ] A8W8 perToken 场景的 Dequant API 顺序：Cast→Mul(RowBroadcast)→Mul(ColBroadcast)→Cast

package/assets/ops-direct-invoke/skills/ascendc-api-best-practices/references/api-hccl-host.md

@@ -0,0 +1,187 @@
+# HCCL Host 侧 API 使用指南
+
+> **适用场景**：跨卡算子 Host 侧 launcher 的通信域创建、channel 建链、engine context 管理、内存注册。本文档只覆盖 CANN HCCL 公共 host API 的签名与约束；具体框架的 builder 流程请参考对应框架文档。
+
+---
+
+## 目录
+
+1. [概述](#1-概述)
+2. [API 签名与参数](#2-api-签名与参数)
+3. [最小通用示例](#3-最小通用示例)
+4. [资源生命周期](#4-资源生命周期)
+5. [常见错误](#5-常见错误)
+6. [检查清单](#检查清单)
+
+---
+
+## 1. 概述
+
+跨卡 kernel 直调需要 host 侧完成三件事：
+
+1. **创建通信域**：rootInfo 交换 → `HcclCommInitRootInfoConfig`
+2. **建链**：`HcclChannelAcquire` 获取 channel 句柄 + 获取各 rank 通信 buffer 地址
+3. **下发上下文**：`HcclEngineCtxCreate/Copy` 把上下文结构写入 device GM，kernel 以 `__gm__` 指针接收
+
+头文件：`hccl/hccl_comm.h`、`hccl/hccl_res.h`、`hccl/hccl_rank_graph.h`（CANN 安装目录 `include/hccl/`）。
+
+---
+
+## 2. API 签名与参数
+
+### 2.1 通信域管理
+
+| API | 签名 | 用途 |
+|:---|:---|:---|
+| `HcclGetRootInfo` | `HcclResult HcclGetRootInfo(HcclRootInfo* rootInfo)` | rank0 生成 rootInfo |
+| `HcclCommInitRootInfo` | `HcclResult HcclCommInitRootInfo(uint32_t nRanks, const HcclRootInfo* rootInfo, uint32_t rank, HcclComm* comm)` | 创建通信域（默认配置） |
+| `HcclCommInitRootInfoConfig` | `HcclResult HcclCommInitRootInfoConfig(uint32_t nRanks, const HcclRootInfo* rootInfo, uint32_t rank, const HcclCommConfig* config, HcclComm* comm)` | 创建通信域（自定义配置，**推荐**） |
+| `HcclCommDestroy` | `HcclResult HcclCommDestroy(HcclComm comm)` | 销毁通信域 |
+| `HcclGetRankId` | `HcclResult HcclGetRankId(HcclComm comm, uint32_t* rank)` | 获取本 rank ID |
+| `HcclGetRankSize` | `HcclResult HcclGetRankSize(HcclComm comm, uint32_t* rankSize)` | 获取总 rank 数 |
+
+> `HcclCommConfig` 用 `HcclCommConfigInit(&config)` 初始化；`hcclBufferSize` 字段控制 HCCL 内置 buffer 大小（MB），不设置时用默认值（CANN 默认 200MB）。
+
+### 2.2 内存管理
+
+| API | 签名 | 用途 |
+|:---|:---|:---|
+| `HcclGetHcclBuffer` | `HcclResult HcclGetHcclBuffer(HcclComm comm, void** buffer, uint64_t* size)` | 取本 rank HCCL 内置 buffer（**库内管理，严禁释放**） |
+| `HcclCommMemReg` | `HcclResult HcclCommMemReg(HcclComm comm, const char* memTag, const CommMem* mem, HcclMemHandle* memHandle)` | 注册通信内存 |
+
+### 2.3 Channel 管理
+
+| API | 签名 | 用途 |
+|:---|:---|:---|
+| `HcclChannelDescInit` | `HcclResult HcclChannelDescInit(HcclChannelDesc* desc, uint32_t num)` | 初始化 channel 描述符（**Acquire 前必须调用**，官方 @warning 强制） |
+| `HcclChannelAcquire` | `HcclResult HcclChannelAcquire(HcclComm comm, CommEngine engine, const HcclChannelDesc* desc, uint32_t num, ChannelHandle* channels)` | 创建 channel |
+| `HcclChannelGetHcclBuffer` | `HcclResult HcclChannelGetHcclBuffer(HcclComm comm, ChannelHandle channel, void** buffer, uint64_t* size)` | 取指定 channel 对端 rank 的 HCCL buffer 地址（URMA 路径填 Win 区地址用） |
+| `HcclChannelGetRemoteMems` | `HcclResult HcclChannelGetRemoteMems(HcclComm comm, ChannelHandle channel, uint32_t* memNum, CommMem** remoteMems, char*** memTags)` | 取对端注册内存列表（按 memTag 匹配，注册内存路径用） |
+
+> **engine 一致性**：`HcclChannelAcquire` 与 `HcclEngineCtxCreate/Get/Copy` 必须使用同一 `CommEngine`，否则 engine ctx 复用失效。
+
+### 2.4 Engine Context
+
+| API | 签名 | 用途 |
+|:---|:---|:---|
+| `HcclEngineCtxCreate` | `HcclResult HcclEngineCtxCreate(HcclComm comm, const char* ctxTag, CommEngine engine, uint64_t size, void** ctx)` | 创建引擎上下文 device 内存 |
+| `HcclEngineCtxGet` | `HcclResult HcclEngineCtxGet(HcclComm comm, const char* ctxTag, CommEngine engine, void** ctx, uint64_t* size)` | 查询已存在上下文（同 tag+engine 命中即复用） |
+| `HcclEngineCtxCopy` | `HcclResult HcclEngineCtxCopy(HcclComm comm, CommEngine engine, const char* ctxTag, const void* srcCtx, uint64_t size, uint64_t dstCtxOffset)` | host→device 拷贝上下文 |
+| `HcclEngineCtxDestroy` | `HcclResult HcclEngineCtxDestroy(HcclComm comm, const char* ctxTag, CommEngine engine)` | 显式销毁 engine ctx（不调用则随 `HcclCommDestroy` 释放） |
+
+### 2.5 Rank Graph（链路发现）
+
+| API | 签名 | 用途 |
+|:---|:---|:---|
+| `HcclRankGraphGetLayers` | `HcclResult HcclRankGraphGetLayers(HcclComm comm, uint32_t** netLayers, uint32_t* netLayerNum)` | 获取网络层 |
+| `HcclRankGraphGetLinks` | `HcclResult HcclRankGraphGetLinks(HcclComm comm, uint32_t netLayer, uint32_t srcRank, uint32_t dstRank, CommLink** links, uint32_t* linkNum)` | 查询指定 netLayer 下 srcRank 与 dstRank 之间的链路信息（建链时按 `linkAttr.linkProtocol` 匹配取 endpoint） |
+
+---
+
+## 3. 最小通用示例
+
+```cpp
+// Step 1: rank0 生成 rootInfo，通过带外通道（如 TCP）分发给所有 rank
+HcclRootInfo rootInfo;
+HcclGetRootInfo(&rootInfo);              // rank0 执行；其他 rank 接收
+
+// Step 2: 创建通信域
+HcclCommConfig config;
+HcclCommConfigInit(&config);
+config.hcclWorldRankID = rankId;
+HcclComm comm = nullptr;
+HcclCommInitRootInfoConfig(rankNum, &rootInfo, rankId, &config, &comm);
+
+// Step 3: 建链（每对 rank 一条 channel）
+HcclChannelDesc desc;
+HcclChannelDescInit(&desc, 1);           // 强制：Acquire 前必须 Init
+desc.remoteRank = peerRank;
+desc.channelProtocol = COMM_PROTOCOL_UBC_CTP;
+ChannelHandle channel = 0;
+HcclChannelAcquire(comm, engine, &desc, 1, &channel);
+
+// Step 4: 取通信 buffer 地址（本 rank / 对端 rank）
+void* localBuf = nullptr;  uint64_t bufSize = 0;
+HcclGetHcclBuffer(comm, &localBuf, &bufSize);
+void* remoteBuf = nullptr; uint64_t remoteSize = 0;
+HcclChannelGetHcclBuffer(comm, channel, &remoteBuf, &remoteSize);
+
+// Step 5: 下发上下文到 device
+void* devCtx = nullptr;
+HcclEngineCtxCreate(comm, "my_ctx", engine, ctxBytes, &devCtx);
+HcclEngineCtxCopy(comm, engine, "my_ctx", &hostCtx, ctxBytes, 0);
+
+// Step 6: 所有 rank 完成建链握手后（带外 barrier），再 launch kernel
+```
+
+> 可用性验证：以上 API 均以 `hccl_res.h`/`hccl_comm.h` 头文件存在为准（CANN 9.1.0 安装头文件已包含全部上述声明）。
+
+---
+
+## 4. 资源生命周期
+
+| 资源 | 管理方式 |
+|:---|:---|
+| HCCL 内置 buffer（`HcclGetHcclBuffer`） | **库内管理，严禁 `aclrtFree`** |
+| engine ctx（`HcclEngineCtxCreate` 返回的 device 内存） | HCCL engine 管理：随 `HcclCommDestroy` 释放，或显式 `HcclEngineCtxDestroy`；**不要 `aclrtFree`** |
+| `HcclComm` | `HcclCommDestroy` |
+| ACL 资源 | `aclrtDestroyStream` → `aclrtResetDevice` → `aclFinalize` |
+
+**释放顺序约束**：`HcclCommDestroy` 必须在 `aclrtResetDevice` 之前（comm 依赖 device）。
+
+---
+
+## 5. 常见错误
+
+### 错误1：ctxTag 冲突
+
+同 `ctxTag`+同 engine 命中 `HcclEngineCtxGet` 会**直接复用已有 ctx**——这是特性，但不同通信域/不同用途的上下文共用 tag 会导致互相覆盖。规则：不同通信域用不同 ctxTag。
+
+### 错误2：跳过 HcclChannelDescInit
+
+`HcclChannelAcquire` 前必须 `HcclChannelDescInit`（官方 @warning 强制），否则描述符字段为随机值，建链行为未定义。
+
+### 错误3：释放 HCCL 内置 buffer
+
+```cpp
+// ❌ 错误：释放 HCCL 内置 buffer
+void* buffer; uint64_t size;
+HcclGetHcclBuffer(comm, &buffer, &size);
+aclrtFree(buffer);  // 严禁！库内管理
+```
+
+### 错误4：资源释放顺序错误
+
+```cpp
+// ❌ 错误：先 ResetDevice 再 DestroyComm
+aclrtResetDevice(deviceId);     // device 已重置
+HcclCommDestroy(comm);          // comm 依赖 device，崩溃！
+```
+
+### 错误5：对 engine ctx 调 aclrtFree
+
+engine ctx 的 device 内存由 HCCL engine 分配管理，用 `HcclEngineCtxDestroy` 或随 `HcclCommDestroy` 释放；`aclrtFree` 不是其配对接口。
+
+### 错误6：建链未完成即 launch kernel
+
+所有 rank 的 channel 握手完成前 launch kernel，device 侧轮询远端地址会无限挂死。必须在 launch 前做一次跨 rank 的带外 barrier（如 TCP barrier）。
+
+---
+
+## 检查清单
+
+- [ ] 使用 `HcclCommInitRootInfoConfig`（非 `HcclCommInitRootInfo`）
+- [ ] `HcclChannelAcquire` 前已 `HcclChannelDescInit`
+- [ ] `HcclChannelAcquire` 与 `HcclEngineCtx*` 使用同一 engine
+- [ ] 不同通信域使用不同 ctxTag
+- [ ] HCCL 内置 buffer 未手动释放
+- [ ] engine ctx 用 `HcclEngineCtxDestroy` 或随 `HcclCommDestroy` 释放（未用 `aclrtFree`）
+- [ ] kernel launch 在跨 rank 带外 barrier 之后
+- [ ] `HcclCommDestroy` 在 `aclrtResetDevice` 之前
+
+---
+
+## 相关文档
+
+- [api-hcomm.md](api-hcomm.md) — Hcomm device 侧通信原语（channel 的消费端）
+- [api-crosscore-sync.md](api-crosscore-sync.md) — 跨核同步 API