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

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

@@ -0,0 +1,229 @@
+# Hcomm 通信原语使用指南
+
+> **适用场景**：AIV 核发起的跨卡点对点数据搬运（URMA），包括 ReadNbi/WriteNbi/Drain/Commit 的正确用法。本文档只覆盖 asc-devkit 标准 API（`adv_api/hcomm/hcomm.h`）的签名与约束；channel 的创建与具体算子的编排模式请参考对应框架文档。
+
+---
+
+## 目录
+
+1. [概述](#1-概述)
+2. [API 签名与参数](#2-api-签名与参数)
+3. [通信协议](#3-通信协议)
+4. [最小通用示例](#4-最小通用示例)
+5. [常见错误](#5-常见错误)
+6. [检查清单](#检查清单)
+
+---
+
+## 1. 概述
+
+`Hcomm` 是 asc-devkit 提供的 AIV 侧跨卡点对点通信模板类，基于 URMA 队列（SQ 投递 WQE、按序执行）实现：
+
+| 场景 | API | 数据方向 |
+|:---|:---|:---|
+| 拉远端数据到本地 | `ReadNbi` | 远端 GM → 本地 GM |
+| 推本地数据到远端 | `WriteNbi` | 本地 GM → 远端 GM |
+| 推数据并远端通知 | `WriteWithNotifyNbi` | 本地 → 远端 + 写通知值 |
+| 原子计数 | `AtomicFAA` | 远端原子加 |
+| 原子比较交换 | `AtomicCAS` | 远端 CAS |
+
+**关键语义**：
+- 同一 channel 上的多个任务在 URMA 队列中**按序执行**，不会互相覆盖；可以连续发起多个搬运后只 Drain 一次
+- `Drain` 保证该 channel 所有已投递任务完成（远端写已生效）
+- `channel` 句柄（`ChannelHandle` = uint64_t）由 host 侧建链获取并经上下文传入 kernel——Hcomm 本身不负责建链
+
+---
+
+## 2. API 签名与参数
+
+> 头文件：`adv_api/hcomm/hcomm.h`，模板类 `Hcomm<CommProtocol commProtocol = COMM_PROTOCOL_UBC_CTP>`
+
+### 2.1 Init
+
+```cpp
+// 方式一：UB 指针（内部自动对齐到 32B）
+__aicore__ inline int32_t Init(__ubuf__ uint8_t* buff, uint32_t len);
+
+// 方式二：LocalTensor（起始地址必须 32B 对齐）
+template<typename T>
+__aicore__ inline int32_t Init(const LocalTensor<T>& buff, uint32_t len);
+```
+
+| 参数 | 类型 | 含义 |
+|:---|:---|:---|
+| `buff` | `__ubuf__ uint8_t*` / `LocalTensor<T>` | UB 工作区（指针重载内部自动 32B 对齐；LocalTensor 重载要求调用方保证 32B 对齐） |
+| `len` | `uint32_t` | 工作区字节数，URMA 实现最小 512B（不足返回失败） |
+| 返回值 | `int32_t` | 0=成功，-1=失败 |
+
+### 2.2 ReadNbi
+
+```cpp
+template<bool commit = true,
+         pipe_t commitPipe = PIPE_S,
+         pipe_t reqPipe = PIPE_MTE3,
+         auto const& config = URMA_DEFAULT_CFG>
+__aicore__ inline int32_t ReadNbi(ChannelHandle channel, GM_ADDR dst, GM_ADDR src, uint64_t len);
+```
+
+| 参数 | 类型 | 含义 |
+|:---|:---|:---|
+| `channel` | `ChannelHandle` (uint64_t) | 通信通道句柄（host 建链获取） |
+| `dst` | `GM_ADDR` | 本地 GM 目标地址 |
+| `src` | `GM_ADDR` | 远端 GM 源地址 |
+| `len` | `uint64_t` | 搬运字节数 |
+| `commit` | `bool` | `true`（默认）：内部自动提交；`false`：需手动调 `Commit` |
+| 返回值 | `int32_t` | 0=成功，-1=失败 |
+
+### 2.3 WriteNbi
+
+```cpp
+template<bool commit = true,
+         pipe_t commitPipe = PIPE_S,
+         pipe_t reqPipe = PIPE_MTE3,
+         auto const& config = URMA_DEFAULT_CFG>
+__aicore__ inline int32_t WriteNbi(ChannelHandle channel, GM_ADDR dst, GM_ADDR src, uint64_t len);
+```
+
+参数同 ReadNbi，方向相反（`dst`=远端，`src`=本地）。
+
+### 2.4 Drain（阻塞等待）
+
+```cpp
+template<pipe_t pipe = PIPE_MTE3>
+__aicore__ inline int32_t Drain(ChannelHandle channel);
+```
+
+阻塞直到该 channel 所有已投递任务完成。同 channel 多个串行任务可只 Drain 最后一次。
+
+### 2.5 Commit（手动提交）
+
+```cpp
+template<pipe_t pipe = PIPE_S>
+__aicore__ inline int32_t Commit(ChannelHandle channel);
+```
+
+> 仅当 ReadNbi/WriteNbi 的 `commit=false` 时需要手动调用。默认 `commit=true` 时无需调用。
+
+### 2.6 WriteWithNotifyNbi
+
+```cpp
+template<bool commit = true, pipe_t commitPipe = PIPE_S, pipe_t reqPipe = PIPE_MTE3,
+         auto const& config = URMA_DEFAULT_CFG>
+__aicore__ inline int32_t WriteWithNotifyNbi(
+    ChannelHandle channel, GM_ADDR dst, GM_ADDR src, uint64_t len,
+    GM_ADDR notifyAddr, uint64_t notifyVal);
+```
+
+| 参数 | 含义 |
+|:---|:---|
+| `notifyAddr` | 远端通知地址（写入后远端可轮询此地址判断数据就绪） |
+| `notifyVal` | 通知写入的值 |
+
+### 2.7 AtomicFAA / AtomicCAS
+
+```cpp
+// Fetch-and-Add（T ∈ {int32_t, uint32_t, int64_t, uint64_t}）
+template<typename T, bool commit = true, pipe_t commitPipe = PIPE_S,
+         pipe_t reqPipe = PIPE_MTE3, auto const& config = URMA_DEFAULT_CFG>
+__aicore__ inline int32_t AtomicFAA(ChannelHandle channel, GM_ADDR dst, GM_ADDR fetchAddr, T addVal);
+
+// Compare-and-Swap（T 同上）
+template<typename T, bool commit = true, pipe_t commitPipe = PIPE_S,
+         pipe_t reqPipe = PIPE_MTE3, auto const& config = URMA_DEFAULT_CFG>
+__aicore__ inline int32_t AtomicCAS(ChannelHandle channel, GM_ADDR dst, GM_ADDR fetchAddr, T compareVal, T swapVal);
+```
+
+> 需 channel 初始化后调用；仅支持 32/64 位整型。浮点累加场景用 `SetAtomicAdd`（见 [api-atomic.md](api-atomic.md)），两者作用层不同。
+
+---
+
+## 3. 通信协议
+
+| CommProtocol | 值 | 用途 |
+|:---|:---|:---|
+| `COMM_PROTOCOL_UBC_CTP` | 4 | URMA 点对点数据通道（Hcomm 默认值，device 侧数据搬运使用） |
+| `COMM_PROTOCOL_UB_MEM` | 6 | UBMEM 协议（host 侧建链时用于 barrier 类通道） |
+| `COMM_PROTOCOL_HCCS` | 0 | HCCS 片间互连协议 |
+
+---
+
+## 4. 最小通用示例
+
+```cpp
+// --- 初始化（必须先 Init，workspace ≥ 512B）---
+AscendC::Hcomm<AscendC::COMM_PROTOCOL_UBC_CTP> comm;
+__ubuf__ uint8_t* commBuf = /* UB 中分配的 512B 工作区 */;
+int32_t ret = comm.Init(commBuf, 512);
+ascendc_assert(ret == 0, "Hcomm Init failed, ret=%d", ret);
+
+// --- GET：从远端拉数据到本地 ---
+ChannelHandle ch = /* host 建链获取的 channel 句柄 */;
+ret = comm.ReadNbi(ch, localDst, remoteSrc, byteLen);
+ascendc_assert(ret == 0, "ReadNbi failed, ret=%d", ret);
+
+// --- PUT：推本地数据到远端 ---
+ret = comm.WriteNbi(ch, remoteDst, localSrc, byteLen);
+ascendc_assert(ret == 0, "WriteNbi failed, ret=%d", ret);
+
+// --- 等待完成（同 channel 的 Read+Write 按序执行，可只 Drain 一次）---
+ret = comm.Drain(ch);
+ascendc_assert(ret == 0, "Drain failed, ret=%d", ret);
+```
+
+要点：
+- `Init` 必须先于任何搬运调用
+- 返回值必须检查（0=成功，-1=失败）
+- 同 channel 任务 URMA 队列按序执行，连续发起后只需 Drain 一次
+
+---
+
+## 5. 常见错误
+
+### 错误1：Init 未调用或 workspace 不足
+
+```cpp
+// ❌ 错误：未 Init 直接 ReadNbi
+comm.ReadNbi(channel, dst, src, len);  // 行为未定义
+
+// ✅ 正确：先 Init，workspace ≥ 512B（URMA 实现强制检查，不足返回 -1）
+comm.Init(commBuf, 512);
+```
+
+### 错误2：误以为同 channel 并发会互相覆盖
+
+URMA 实现是向 SQ 投递 WQE 排队执行，同 channel 多任务**按序执行不会覆盖**。正确认知：同 channel 的多个串行搬运（如 data + scale）可连续 Commit 后只 Drain 一次，无需逐个 Drain。
+
+### 错误3：返回值未检查
+
+```cpp
+// ❌ 错误：忽略返回值
+comm.ReadNbi(channel, dst, src, len);
+
+// ✅ 正确：检查返回值
+int32_t ret = comm.ReadNbi(channel, dst, src, len);
+ascendc_assert(ret == 0, "ReadNbi failed, ret=%d", ret);
+```
+
+### 错误4：跨块场景漏块间同步
+
+`Drain` 只保证**本 block 的** channel 任务完成。若后续动作依赖**所有 block** 都完成搬运（如统一通知计算核数据就绪），`Drain` 后还需 `SyncAll<true>()` 做块间同步再通知（SyncAll 用法见 [api-crosscore-sync.md](api-crosscore-sync.md)）。
+
+> ⚠️ **SyncAll 不是免费的**：它是全 block 硬栅栏，会打散通信/计算流水重叠。逐 tile 热路径上"Drain + SyncAll + 通知"三连是流水性能差的典型根因。优化方向不是删同步点（数据可见性不可裁剪），而是：① 增大 tile 粒度减少轮次从而降低 SyncAll 频率；② 能改用计数式 CrossCore flag 生产者-消费者握手的时序就不用 SyncAll；③ 提高通信并行度（多核分摊 target）缩短 Drain 本身。详见 [api-crosscore-sync.md](api-crosscore-sync.md) 性能代价小节。
+
+---
+
+## 检查清单
+
+- [ ] `Init` 在搬运之前调用（UB workspace ≥ 512B；LocalTensor 重载需 32B 对齐）
+- [ ] ReadNbi/WriteNbi/Drain 返回值检查为 0
+- [ ] 同 channel 多任务利用 URMA 按序语义，合并 Drain（而非逐个 Drain）
+- [ ] 依赖"所有 block 完成"时已加 `SyncAll` 块间同步
+- [ ] 浮点原子累加用 `SetAtomicAdd`（DMA 层），整型跨卡原子用 `AtomicFAA/CAS`（UDMA 层），未混用
+
+---
+
+## 相关文档
+
+- [api-crosscore-sync.md](api-crosscore-sync.md) — CrossCore flag 与 SyncAll（块间/跨核同步）
+- [api-atomic.md](api-atomic.md) — SetAtomicAdd（DMA 层原子累加）
+- [api-hccl-host.md](api-hccl-host.md) — HCCL Host 侧 API（channel 建链）

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

@@ -0,0 +1,129 @@
+# Host 侧 Runtime API 使用规范
+
+> **适用范围**：Kernel 直调模式下的 Host 侧代码（`.asc` 中的 `main()` 函数）
+
+---
+
+## 1. 设备初始化 API 调用顺序 ⚠️ **强制**
+
+### 1.1 核数获取 API 选择 ⚠️ **关键**
+
+**根据算子类型选择正确的核数获取 API**：
+
+| 算子类型 | 使用的 API | 说明 |
+|---------|-----------|------|
+| **纯向量计算**（Add/Mul/Div/Reduce等） | `ACL_DEV_ATTR_VECTOR_CORE_NUM` | 使用 Vector Core 数量 |
+| **矩阵计算**（MatMul/Conv等） | `ACL_DEV_ATTR_CUBE_CORE_NUM` | 使用 Cube Core 数量 |
+| **混合计算** | `ACL_DEV_ATTR_AICORE_CORE_NUM` | 使用 AI Core 数量 |
+
+**Ascend910B3 芯片核数参考**：
+- AI Core: 20
+- Cube Core: 20
+- Vector Core: 40（每个 AI Core 有 2 个 Vector Core）
+
+### 1.2 aclrtGetDeviceInfo 调用要求
+
+**规则**：`aclrtGetDeviceInfo` **必须**在 `aclrtSetDevice` 之后调用
+
+**原因**：获取设备资源前必须先设置设备上下文
+
+**正确示例**（纯向量算子）：
+```cpp
+int32_t main() {
+    // 1. 初始化 ACL
+    aclInit(nullptr);
+    int32_t deviceId = 0;
+    aclError ret = aclrtSetDevice(deviceId);
+    if (ret != ACL_SUCCESS) {
+        printf("aclrtSetDevice failed, ret=%d\n", ret);
+        return ret;
+    }
+
+    // 2. 获取设备核数（必须在 aclrtSetDevice 之后）
+    int64_t availableCoreNum = 8;  // 默认值
+    ret = aclrtGetDeviceInfo(deviceId, ACL_DEV_ATTR_VECTOR_CORE_NUM, &availableCoreNum);
+    if (ret != ACL_SUCCESS) {
+        printf("aclrtGetDeviceInfo failed, ret=%d\n", ret);
+        aclrtResetDevice(deviceId);
+        return ret;
+    }
+
+    // 3. 计算使用核数
+    uint32_t usedNumBlocks = (totalRows < availableCoreNum) ? totalRows : (uint32_t)availableCoreNum;
+
+    // 4. 后续处理...
+}
+```
+
+**矩阵算子示例**：
+```cpp
+// 矩阵计算算子使用 Cube Core 数量
+int64_t availableCoreNum = 8;
+aclrtGetDeviceInfo(deviceId, ACL_DEV_ATTR_CUBE_CORE_NUM, &availableCoreNum);
+```
+
+**错误示例**：
+```cpp
+int32_t main() {
+    // ❌ 错误：未调用 aclrtSetDevice 就调用 aclrtGetDeviceInfo
+    int64_t availableCoreNum = 8;
+    aclError ret = aclrtGetDeviceInfo(deviceId, ACL_DEV_ATTR_VECTOR_CORE_NUM, &availableCoreNum);
+    // 可能返回错误或获取到错误值
+}
+```
+
+---
+
+## 2. 常见错误
+
+| 错误类型 | 错误示例 | 后果 | 正确做法 |
+|---------|---------|------|---------|
+| **调用顺序错误** | 未调用 `aclrtSetDevice` 就调用 `aclrtGetDeviceInfo` | 获取核数失败或返回错误值 | 先 `aclrtSetDevice`，再获取资源 |
+| **写死核数** | `uint32_t numBlocks = 8;` | 不同设备性能不匹配 | 使用 `aclrtGetDeviceInfo` 动态获取 |
+| **API 选择错误** | 纯向量算子用 `ACL_DEV_ATTR_AICORE_CORE_NUM` | 未充分利用 Vector Core | 根据算子类型选择正确的 API |
+
+---
+
+## 3. 完整 Host 侧初始化流程
+
+```cpp
+int32_t main() {
+    // Step 1: 初始化 ACL
+    aclInit(nullptr);
+    
+    // Step 2: 设置设备
+    int32_t deviceId = 0;
+    aclError ret = aclrtSetDevice(deviceId);
+    CHECK_ACL(ret);
+
+    // Step 3: 获取设备核数（根据算子类型选择）
+    int64_t availableCoreNum = 8;
+    // 纯向量算子
+    ret = aclrtGetDeviceInfo(deviceId, ACL_DEV_ATTR_VECTOR_CORE_NUM, &availableCoreNum);
+    // 或矩阵算子：ACL_DEV_ATTR_CUBE_CORE_NUM
+    // 或混合算子：ACL_DEV_ATTR_AICORE_CORE_NUM
+    CHECK_ACL(ret);
+
+    // Step 4: 分配 GM 内存
+    size_t gmSize = ...;
+    void* gmPtr = nullptr;
+    ret = aclrtMalloc(&gmPtr, gmSize, ACL_MEM_MALLOC_HUGE_FIRST);
+    CHECK_ACL(ret);
+
+    // Step 5: 计算 Tiling 参数
+    MyTilingData tiling;
+    uint32_t numBlocks = (uint32_t)availableCoreNum;
+    computeTiling(tiling, totalRows, numBlocks);
+
+    // Step 6: 启动 Kernel
+    KernelCall(..., (uint8_t*)&tiling);
+
+    // Step 7: 清理资源
+    aclrtFree(gmPtr);
+    aclrtResetDevice(deviceId);
+    aclFinalize();
+
+    return 0;
+}
+```
+

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

@@ -0,0 +1,196 @@
+# LoadData 系列 API 使用指南
+
+L1 → L0 数据加载的 API 字段、对齐约束、NZ Layout 与 dtype 相关的关键差异。
+
+---
+
+## 目录
+
+1. [API 概览](#api-概览)
+2. [NZ Layout C0 大小随 dtype 变化](#nz-layout-c0-大小随-dtype-变化)
+3. [LoadData_2D_MX 系列（MX 块量化格式）](#loaddata_2d_mx-系列mx-块量化格式)
+4. [Multi-matrix 拼接到 L1 的 head offset 公式](#multi-matrix-拼接到-l1-的-head-offset-公式)
+5. [详细文档与示例位置](#详细文档与示例位置)
+
+---
+
+## API 概览
+
+| API 系列 | 用途 | 典型数据类型 |
+|---------|------|------------|
+| `LoadData_2D` / `LoadData_2D_V2` | L1 → L0 加载，基础数据通路 | 整数 / 浮点 |
+| `LoadData_2D_MX` | L1 → L0 加载 MX 块量化格式数据（配套 scale 同步加载） | mxfp8 / mxfp4 等 |
+| `LoadData_3D` | L1 → L0 加载，卷积 im2col 模式 | 卷积场景 |
+
+> 同一 API 在不同平台 / CANN 版本可能有 `LoadData_2D.md` / `LoadData_2D_MX.md` / `LoadData_2D_V2.md` / `LoadData_2D_BitMode.md` 等多个变体，功能略有差异。使用前用通配符搜 `find "$ASC_DEVKIT_DIR/docs/zh/api/" -name "LoadData*.md"` 列出全部变体。
+
+---
+
+## NZ Layout C0 大小随 dtype 变化
+
+L1 NZ Layout 中 C0 维度按字节宽度对齐（典型 32 字节 = 1 个 C0 datablock），所以**每个 C0 包含的元素数随 dtype 变化**：
+
+| dtype | sizeof | C0 元素数 | C0 字节数 |
+|-------|--------|----------|---------|
+| fp16 / bf16 | 2 字节 | **16 元素**（常量 `CUBE_BLOCK`） | 32 字节 |
+| fp8（mxfp8 / fp8_e4m3 / fp8_e5m2） | 1 字节 | **32 元素**（`FP8_C0_ELEMS`） | 32 字节 |
+| fp4（mxfp4） | 0.5 字节 | **64 元素** | 32 字节 |
+| int8 | 1 字节 | 32 元素 | 32 字节 |
+| int32 | 4 字节 | 8 元素 | 32 字节 |
+
+### 影响
+
+**两套参数结构体的字段单位不同，不要混用**（MX 路径下 `loadDataParams`（`LoadData2DParamsV2`）与 `loadMxDataParams`（`LoadData2DMxParams`）并列传入）：
+
+**`LoadData2DParamsV2`**（官方接口 `LoadData_2D_V2`）：
+
+| 字段 | 单位 | 含义 |
+|------|------|------|
+| `mStartPosition` / `mStep` | **16 个元素**（与 dtype 无关） | M 轴起始位置 / 搬运长度；取值范围 [0, 255]，`mStep=0` 为 NOP |
+| `kStartPosition` / `kStep` | **32 字节** | K 轴起始位置 / 搬运长度，等于 `K 维元素数 / C0_elements_for_dtype`；取值范围 [0, 255]，`kStep=0` 为 NOP |
+| `srcStride` / `dstStride` | **512 字节**（= 一个数据分形，与 dtype 无关） | K 方向相邻分形起始地址的间隔。**注意不是 32 字节的 C0 单位** |
+
+**`LoadData2DMxParams`**（官方接口 `LoadData_2D_MX`，仅 MX 量化路径）：
+
+| 字段 | 单位 | 含义 |
+|------|------|------|
+| `xStartPosition` / `xStep` | **1 个分形 = 32 字节** | X（M）轴起始位置 / 搬运长度；取值范围 [0, 255] |
+| `yStartPosition` / `yStep` | **32 字节** | Y（K）轴起始位置 / 搬运长度；`yStep=0` 为 NOP |
+| `srcStride` / `dstStride` | **32 字节** | X 方向相邻分形起始地址的间隔 |
+
+> **为什么 stride 单位是 512 字节**：数据分形大小恒为 512 字节、与 dtype 无关（b16 为 16×16、b8 为 16×32、b4 为 16×64、b32 为 16×8，元素宽度不同但乘积都是 512B），故 `LoadData2DParamsV2` 的 stride 以 512 字节为单位；MX 路径则以 32 字节分形为单位。
+
+### 典型踩坑
+
+照搬 fp16 路径的字段公式到 fp8：
+
+```cpp
+// fp16 路径（正确）：
+load.kStep = nActSize / CUBE_BLOCK;             // CUBE_BLOCK = 16（fp16 C0 元素数）
+load.kStartPosition = nOff / CUBE_BLOCK;
+
+// fp8 路径误用 fp16 公式：
+load.kStep = nActSize / CUBE_BLOCK;             // ❌ fp8 C0 是 32 不是 16
+load.kStartPosition = nOff / CUBE_BLOCK;
+
+// fp8 路径正确：
+load.kStep = nActSize / FP8_C0_ELEMS;           // ✅ FP8_C0_ELEMS = 32
+load.kStartPosition = nOff / FP8_C0_ELEMS;
+```
+
+误用 fp16 公式后：
+- LoadData 读取偏移错误（每条偏移到正确位置的 1/2 处）
+- 输出 NaN / inf，但 kernel 不崩（仍是合法地址）
+- 不同 dtype 切换时极易触发
+
+### 防御措施
+
+为每个 dtype 定义独立常量并显式用于公式：
+
+```cpp
+constexpr uint32_t CUBE_BLOCK = 16;           // fp16/bf16 C0 元素数
+constexpr uint32_t FP8_C0_ELEMS = 32;         // fp8 C0 元素数
+constexpr uint32_t FP4_C0_ELEMS = 64;         // fp4 C0 元素数
+```
+
+并在公式中显式使用对应常量，不混用。
+
+---
+
+## LoadData_2D_MX 系列（MX 块量化格式）
+
+LoadData_2D_MX 用于 MX 块量化格式（mxfp8 / mxfp4 等）的 L1 → L0 加载，数据本体 + scale 一次加载到 L0_A_MX / L0_B_MX。
+
+### K_BASE 与 yStep 整除性
+
+LoadData2DMxParams 的 `yStep` 单位是 32 字节 = 1 个 MX 块量化沿 K 方向的 32 个元素。
+
+K 方向多 K-pass 时，**K_BASE 必须满足 yStep 单位整除性**：
+
+```
+K_BASE % (32 / sizeof(dtype)) == 0
+```
+
+具体到不同 dtype：
+- fp8（mxfp8）：K_BASE % 32 == 0
+- fp4（mxfp4）：K_BASE % 64 == 0
+
+K_BASE 不满足整除性会导致 `yStartPosition` 分数化错位，该 K-pass 内 scale 读取偏移错误。
+
+### 单 K-pass vs 多 K-pass 选择
+
+- K 维元素数 ≤ 32（对 fp8） → 必须单 K-pass（`Mmad(.k = K, ...)` 一次完成）
+- K 维元素数 > 32 → 可多 K-pass，但 K_BASE 必须满足整除性
+
+### N-segment 切分时 scale 的 xStartPosition 必须跟随 N-offset
+
+当 B 矩阵需要按 N 方向分块加载到 L0B（N 方向尺寸超过 L0B 单次容量时触发），每个 N-segment 必须独立计算 scale 的起始位置：
+
+```cpp
+// ❌ scale 多 N-segment 复用同一起始位置
+mxLoad.xStartPosition = 0;                          // 第二个 N-segment 也读 N-segment 0 的 scale
+
+// ✅ scale xStartPosition 跟随 nOff
+mxLoad.xStartPosition = nOff / CUBE_BLOCK;          // 单位 = M-axis 分形数
+```
+
+误用后第一个 N-segment（nOff=0）输出正常，后续 N-segment 输出 NaN / inf。
+
+---
+
+## Multi-matrix 拼接到 L1 的 head offset 公式
+
+某些算子（multi-head MatMul、multi-head Attention 等）把多个矩阵拼接到同一片 L1 NZ buffer，做一次 LoadData 出去到 L0。每个矩阵在 L1 的起始 offset 必须按 NZ fractal 物理布局正确计算。
+
+### 数据载体的 head offset
+
+每个矩阵占 `(mEff / 16) × (K_dim / C0_elements)` 个 NZ fractal。head 间堆叠时的 element offset：
+
+```cpp
+head_offset_data = head_idx * mEff * C0_elements_for_dtype;
+```
+
+按 dtype 落到具体公式：
+
+```cpp
+// fp16 / bf16 数据载体
+head_offset_fp16 = head_idx * mEff * CUBE_BLOCK;       // CUBE_BLOCK = 16
+
+// fp8 数据载体
+head_offset_fp8 = head_idx * mEff * FP8_C0_ELEMS;      // FP8_C0_ELEMS = 32
+```
+
+### scale 载体的 head offset（B16 视图 + Dn2Nz 加载）
+
+MX 类格式的 scale 通常用 B16 视图（每 2 个 e8m0 合并为 1 个 half）+ Dn2Nz 加载到 L1。**scale 载体在 L1 的 M-fractal element count 与数据载体不同**：
+
+```cpp
+// scale 载体的 head offset（不同于数据载体！）
+head_offset_scale = head_idx * mEff * scaleK_b16;      // scaleK_b16 = (K 维元素数 / 32) / 2
+```
+
+### 典型踩坑
+
+- 把 fp16 公式直接搬到 fp8 数据载体：`head_idx * mEff * 16` 应改为 `head_idx * mEff * 32`
+- 把数据载体公式搬到 scale 载体：写 `head_idx * mEff * CUBE_BLOCK` 或 `head_idx * mEff * FP8_C0_ELEMS` 都错，scale 应该用 `head_idx * mEff * scaleK_b16`
+- 数据载体公式系数与 scale 载体公式系数**必须独立推导**，不可混用
+
+### 症状
+
+- 单 head 路径全部正确
+- multi-head（≥ 2）出现 head 维奇偶 NaN 模式（`[OK, BAD, BAD, OK]` / `[OK, BAD, OK, BAD]` 等）
+- 一处公式修对后模式变化（说明仍有其他公式错位）
+
+---
+
+## 详细文档与示例位置
+
+| 资源 | 路径 |
+|------|------|
+| API 文档（用通配符列出所有变体） | `find "$ASC_DEVKIT_DIR/docs/zh/api/" -name "LoadData_2D*.md"` |
+| LoadData2DParamsV2 字段对照 | `find "$ASC_DEVKIT_DIR/docs/zh/api/" -name "LoadData_2D_V2*.md"` |
+| Mmad 配套 API 文档 | `find "$ASC_DEVKIT_DIR/docs/zh/api/" -name "Mmad*.md"` |
+| MX 路径 end-to-end 示例 | `asc-devkit/examples/01_simd_cpp_api/03_basic_api/03_matrix_compute/load_data_2dmx_l12l0/` |
+| 平台同步基座示例 | `asc-devkit/examples/01_simd_cpp_api/06_compatibility_guide/matmul_s4/`（A5 平台 mode=4 同步） |
+
+新增 LoadData 路径前必须查阅 API 文档 + 跑通对应 example，不要凭"和 fp16 一样"的假设直接照搬公式。