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

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/adapters/ascendc/tiling.md

@@ -0,0 +1,374 @@
+# broadcast 范式 standard Tiling 切分策略
+
+> UB 切分、多核切分、Workspace 分配的完整算法
+
+依赖输入：overview.md、dag-buffers.md、tiling-preprocess.md
+
+## 1 UB 切分轴
+
+**参考案例**: `example/examples-adam-design/adam_apply_one_assign_design.md` §5.2（UB 切分）
+**参考源码**: `example/examples-adam-code/op_host/arch35/adam_apply_one_assign_tiling_arch35.cpp`（FindSplitAxis 函数）
+
+> 详细描述ub切分逻辑
+
+**约束**：
+- 每份 UB buffer 大小需要 blocksize 对齐
+- 所有 UB buffer 总和，不能超过实际 UB 大小
+- 必须给出伪码实现
+- 必须考虑空tensor场景
+- 空 tensor 场景严禁 SetBlockDim(0)，若使用核数为0，也需要 SetBlockDim(1), kernel侧通过 usedCoreNum=0 短路处理
+
+### 1.1 切分原理
+
+Broadcast 场景使用 **UB 单切分**——以 effective_shape 为坐标系选择单根切分轴。
+
+被切分的轴 a = ubOuter × ubFactor。包含 ubFactor 在内的所有内侧轴为「UB 内轴」，一次加载进 UB；ubOuter 至最外侧轴为「UB 外轴」，是 UB 外的 for 循环。
+
+```
+UB 内轴 = 轴 k (贡献 ubFactor) + 轴 k+1..n-1 (全量)
+UB 外轴 = 轴 0..k-1 (全量循环) × ubOuter (轴 k 的分段循环)
+
+UB 内存占用 = ubFactor × ∏_{j>k} d_j
+必须满足: ubFactor × inner ≤ perBufElems
+```
+
+选轴算法——从最内轴向外扫描，累积内侧轴连乘 inner。当 `d_k × inner > perBufElems` 时，该轴无法全量放入——在此切分。
+
+```
+inner = 1
+for k from n-1 down to 0:
+    if d_k × inner > perBufElems:
+        split at k
+        ubFactor = perBufElems / inner
+        ubOuter = ceil(d_k / ubFactor)
+        break
+    inner *= d_k
+```
+
+永远至少有一根可切轴。
+
+### 1.2 切分公式
+
+```cpp
+// FindSplitAxis — 以 effective_shape 为坐标系选择单根切分轴
+// perBufElems = ((ubPerCore / physNodes) & ~31) / dtypeSize，dtypeSize 固定按 FP32（4 字节）算，不随输入 dtype 变化
+// Ops::Base::CeilDiv 需在 tiling 侧 #include "util/math_util.h"（位于 op_common/op_host 下）
+void FindSplitAxis(const std::vector<int64_t>& maxBroShape,
+                   int64_t dtypeSize, int64_t ubPerCore, int64_t physNodes, SplitResult &out)
+{
+    int64_t perBufBytes = (ubPerCore / physNodes) & UB_ALIGN_MASK;
+    int64_t perBufElems = perBufBytes / dtypeSize;
+    int64_t rank = static_cast<int64_t>(maxBroShape.size());
+    int64_t inner = 1;
+    for (int64_t k = rank - 1; k >= 0; k--) {
+        if (maxBroShape[k] * inner > perBufElems) {
+            out.ubFactor = perBufElems / inner;
+            out.ubOuter = Ops::Base::CeilDiv(maxBroShape[k], out.ubFactor);
+            int64_t rem = maxBroShape[k] % out.ubFactor;
+            out.ubTail = (rem == 0) ? out.ubFactor : rem;
+            out.ubSplitIdx = k;
+            return;
+        }
+        if (k == 0) {
+            // 全量装得下
+            out.ubSplitIdx = 0;
+            out.ubFactor = maxBroShape[0];
+            out.ubOuter = 1;
+            out.ubTail = out.ubFactor;
+            return;
+        }
+        inner *= maxBroShape[k];
+    }
+}
+```
+
+尾块：d_k 不能整除 ubFactor 时，最后一轮 ubTail = d_k % ubFactor（整除时为 ubFactor）。
+
+### 1.3 特殊场景
+
+- 末尾轴装不下：d_{n-1} > perBufElems → ubSplitIdx = n-1, ubFactor = perBufElems
+- 全量装得下：total ≤ perBufElems → ubSplitIdx = 0, ubFactor = d_0, ubOuter = 1
+- 空 tensor：`numel == 0` 直接返回，不走 kernel
+
+## 2 多核切分
+
+**参考源码**: `example/examples-adam-code/op_host/arch35/adam_apply_one_assign_tiling_arch35.cpp`（MultiCoreSplit 函数）
+
+**约束**：
+- 严禁 SetBlockDim(0)，空tensor场景若使用核数为0，也需要 SetBlockDim(1), kernel侧通过 usedCoreNum=0 短路处理
+- 设置的 BlockDim 严禁超过实际的物理核数
+- (范式融合约束) 使用核间均衡的切分策略，假设有如下字段：  
+    - totalTiles 用于切多核的总的tile块数
+    - coreNum 总的aiv核数
+    - usedCoreNum 实际使用的aiv核数
+    - mainTiles 主核分配的tile块数 (尾核分配的tile块数=mainTiles-1)
+    - mainCoreNum 主核数 (尾核数=usedCoreNum-mainCoreNum)  
+- 必须给出伪码实现
+
+### 2.1 切分原理
+
+多核切分以 UB 切分产出的 tile 为单元，将 `totalTiles = ubOuter × Π_{j<k} d_j` 平摊到多核。
+
+### 2.2 切分公式
+
+```cpp
+// MultiCoreSplit — tile 均衡分配
+bool MultiCoreSplit(const std::vector<int64_t>& maxBroShape,
+                    const SplitResult &ubSplit, int64_t maxCores, MultiCoreResult &out)
+{
+    int64_t k = ubSplit.ubSplitIdx;
+    int64_t outerProd = 1;
+    for (int64_t j = 0; j < k; j++) {
+        outerProd *= maxBroShape[j];
+    }
+    out.totalTiles = outerProd * ubSplit.ubOuter;
+
+    out.usedCoreNum  = (out.totalTiles < maxCores) ? out.totalTiles : maxCores;
+    out.mainTiles  = Ops::Base::CeilDiv(out.totalTiles, out.usedCoreNum);
+    out.mainCoreNum  = out.totalTiles - (out.mainTiles - 1) * out.usedCoreNum;
+    // 前 mainCoreNum 个核各处理 mainTiles 块，其余核各处理 mainTiles-1 块（母模板核间均衡切分公式）
+    return true;
+}
+```
+
+### 2.3 特殊场景
+
+- 空 tensor 场景：若使用核数为0，也需要 SetBlockDim(1)，kernel 侧通过 usedCoreNum=0 短路处理
+
+## 3 切分策略微调
+
+> 本章节是出于性能考虑，为了平衡ub切分与多核切分做的优化调整，如不需要，填 不涉及  
+> 不管使用ub优先还是多核优先的切分策略，都存在一定缺陷，可能核用的少、可能ub用的不够。
+
+### 3.1 微调方式
+
+不涉及。当前 UB 单切分以 effective_shape 为坐标系，功能全覆盖。部分场景非最优（多数入参远小于 effective_shape 时 padding 占比高），预留多切分扩展点。
+
+## 4 整体切分伪码
+
+**参考源码**: `example/examples-adam-code/op_host/arch35/adam_apply_one_assign_tiling_arch35.cpp`（底部 TilingPrepare/TilingFunc/DoTilingAndSet 三个函数）
+
+> 切分策略是一个整体，ub切分、多核切分可能是耦合的，这里给出样例
+
+```
+DoTiling():
+  1. GetCompileInfo()                → coreNum, ubSize（零值守卫：== 0 时报错返回）
+  2. GetOpParam()                    → inputShapes, outputShapes（指针用专用宏判空）
+  3. PadAndSqueeze()                 → maximumBroShape, normalInputShapes, normalOutputShapes
+  4. rank_ = maximumBroShape.size()
+  5. rank 上限校验                    → rank_ > RANK_8 时 OP_LOGE_FOR_INVALID_SHAPES_WITH_REASON 报错返回
+                                      （防止 delta = R - rank_ 为负数导致数组负索引）
+  6. CheckBroadcastShape()           → broadcast 兼容校验
+  7. perBufBytes = (ubSize / P) & ~31   # P 来自 DAG 分析结论
+  8. perBufElems = perBufBytes / 4   # 永远按 FP32 算，不随 dtype 变化
+  9. FindSplitAxis(maxBroShape, dtypeSize, ubSize, physNodes, split)
+  10. MultiCoreSplit(maxBroShape, split, coreNum, multicore)
+  11. CalTilingKey()                 → key = (rank <= RANK_4) ? RANK_4 : RANK_8
+  12. WriteTilingData()              → 填充 BroadcastTilingData<RANK>
+  13. SetWorkspace(0)                → Broadcast 不需要 workspace
+```
+
+## 5 切分后处理
+
+### 5.1 UB 大小计算
+
+> 简述是按buffer个数均匀分配，还是在 tiling 切分逻辑中实时计算(每个buffer大小不同)
+
+按 buffer 个数均匀分配：`perBufBytes = (UB / P) & ~31`（P 个 buffer 均分 UB，32B 对齐）。
+
+### 5.2 Workspace 分配
+
+```cpp
+size_t *ws = context->GetWorkspaceSizes(1);
+OP_CHECK_NULL_WITH_CONTEXT(context, ws);
+ws[0] = 0;
+```
+
+**约束**:
+- 必须设置，即使不需要使用workspace，也需要显示设置为0
+- 如果要使用workspace，必须额外分配 16MB，即总大小为 `16MB + 实际使用` (ascendc要求)
+- 如果涉及workspace使用，必须使用INFO级别日志打印分配大小。
+
+### 5.3 TilingKey 设置
+
+> 必须使用INFO级别日志打印 tilingkey 各模板参数
+
+```cpp
+int64_t mapped = (rank_ <= {OP_UPPER}_RANK_4) ? {OP_UPPER}_RANK_4 : {OP_UPPER}_RANK_8;
+ctx_->SetTilingKey(GET_TPL_TILING_KEY(mapped));
+```
+
+> `RANK_4/RANK_8` 为 struct.h 中定义的命名常量，禁止裸数字 4/8。
+
+### 5.4 TilingData 设置
+
+> 必须使用INFO级别日志打印 tilingdata各字段
+
+**Tiling 维测规范**：两条日志（外部参数 + TilingData 全量），使用 Arr2String helper，从 `tiling->` struct 数组打印（R 维全量含 padding），禁止从中间 vector（rank_ 维）打印。TilingData 全量含逐 input/output slot 的 shape/stride 数组循环打印（`for i in numIn/numOut` 各一条 OP_LOGI）。
+
+Broadcast 关键字段表（日志对照用）：
+
+| 日志字段 | 常见 bug |
+|---------|----------|
+| `maxBroShape` | padding 方向/值（前补=1 vs 后补=0），broadcast 轴是否被 squeeze |
+| `input[i].stride` | 播轴 stride=0，padding stride=0 |
+| `split(ubSplitIdx, ubFactor, ubOuter)` | ubSplitIdx 是否因 padding 错位 |
+| `rank→R` | 实际 rank vs 模板 RANK 映射 |
+
+### 5.5 ScheduleMode 设置
+
+**约束**:
+- SyncAll() 场景必须设置 SetScheduleMode(1)
+
+## 6 切分策略产出校验
+
+> 重要！为了校验agent是否真正理解了切分策略，需要产出所有的切分可能性。"人"来校验。
+
+**对范式开发者的要求**：
+- 1. 给一个 case, 枚举所有切分可能性，作为 golden。可以人工枚举，可以人与agent交互产生，不管怎样，需要"人"保证正确性。
+- 2. 删除 golden, agent读取本文档可以产出所有的切分可能，如果产出不了，需要不断改进范式质量，直到agent能产出与golden一致的结果
+- 3. golden 随本章节上库
+
+**golden 样例（Adam: fp32, P=5, UB=262144, coreNum=24）**：
+
+输入 shape 全同 `(256, 128, 64)`，PadAndSqueeze 后 `maxBroShape=(256,128,64)`, rank=3 → RANK=4。
+
+| 参数 | 值 | 计算 |
+|------|-----|------|
+| perBufBytes | 52416 | `(262144 / 5) & ~31` |
+| perBufElems | 13104 | `52416 / 4`（FP32） |
+| split.ubSplitIdx | 1 | d=2(64): 64*1=64 ≤ 13104 ✓; d=1(128): 128*64=8192 ≤ 13104 ✓; d=0(256): 256*8192 > 13104 ✗ → split at 0 |
+
+修正：split.ubSplitIdx=0（d=0 无法全量放入），ubFactor=13104/8192=1（取整后=1），ubOuter=ceil(256/1)=256。
+
+| 参数 | 值 |
+|------|-----|
+| split.ubSplitIdx | 0 |
+| split.ubFactor | 1 |
+| split.ubOuter | 256 |
+| split.ubTail | 1 |
+| totalTiles | 256 |
+| usedCoreNum | 24 |
+| mainTiles | 11 (ceil(256/24)=11) |
+| mainCoreNum | 16 (256-(11-1)*24=16) |
+
+前 16 个核各处理 11 个 tile，后 8 个核各处理 10 个 tile。
+
+**Python 交叉验证**（4 块纯逻辑，各出 Python 对比，随机 case 100 次）：
+
+| # | 验什么 | 关键检查点 |
+|---|--------|----------|
+| 1 | 计算流序列 | golden(原始公式) vs opt(融合+重排) vs kernel Process — 三者一致 |
+| 2 | 循环 count | `count = ubBlockLength × Π maxBroShape[d>ubSplitIdx]`；split 轴 = 最内维时 inner=1 |
+| 3 | 地址偏移 | 播轴 stride=0→offset 不贡献；padding stride=0→offset 不贡献；GM 偏移 = Σ coord×stride |
+| 4 | NDDMA 参数 | loopSize = 目标 shape（非源 shape）；五字段全填；最多 5 维；前补 dim→最外维 loopSize=1 |
+
+> **注意**：交叉验证的输入数据要和 kernel 看到的完全一致——Python 用 `maxBro`（rank_ 元素），kernel 用 `maxBroShape[RANK]`（R 元素含 padding）。差一个 padding 值就是 bug 盲区。
+
+---
+
+## 7 物理计算流验证 harness
+
+> 对应 design-spec.md §3.3.4「物理计算流验证」（非必须步骤）。
+> harness（verify.py 通用模板）与使用流程已上移至语言中立的通用知识层：[../../generic/verification.md](../../generic/verification.md)。
+> 用途：用 golden（spec 公式逐行翻译）与 opt（计算流伪码逐行翻译、独立实现）跑随机 case 对比，验证计算流设计正确性。
+
+
+## 8 Host 侧注册与 Tiling 整体结构
+
+> Host 侧注册宏、CompileInfo、TilingPrepare/TilingFunc/DoTilingAndSet 三函数的完整写法
+
+### 8.1 CompileInfo 结构体
+
+CompileInfo 在 TilingParse 阶段填充，缓存平台信息供 TilingFunc 使用：
+
+```cpp
+struct {OP}CompileInfo {
+    uint64_t coreNum;
+    uint64_t ubSize;
+};
+```
+
+### 8.2 TilingPrepare（TilingParse 回调）
+
+在编译期执行一次，从平台信息获取 coreNum 和 ubSize，写入 CompileInfo。**返回值必须做零值守卫**（coreNum==0 或 ubSize==0 会导致下游 FindSplitAxis/MultiCoreSplit 除零），用 `OP_CHECK_IF` 上报并返回失败：
+
+```cpp
+ge::graphStatus TilingPrepareFor{OP}(gert::TilingParseContext *context)
+{
+    fe::PlatFormInfos *platformInfo = context->GetPlatformInfo();
+    auto compileInfo = context->GetCompiledInfo<{OP}CompileInfo>();
+    OP_CHECK_NULL_WITH_CONTEXT(context, platformInfo);
+    OP_CHECK_NULL_WITH_CONTEXT(context, compileInfo);
+    auto ap = platform_ascendc::PlatformAscendC(platformInfo);
+    compileInfo->coreNum = ap.GetCoreNumAiv();
+    OP_CHECK_IF(compileInfo->coreNum == 0,
+        OP_LOGE(context->GetNodeName(), "coreNum is 0"),
+        return GRAPH_FAILED);
+    ap.GetCoreMemSize(platform_ascendc::CoreMemType::UB, compileInfo->ubSize);
+    OP_CHECK_IF(compileInfo->ubSize == 0,
+        OP_LOGE(context->GetNodeName(), "ubSize is 0"),
+        return GRAPH_FAILED);
+    return GRAPH_SUCCESS;
+}
+```
+
+### 8.3 TilingFunc 入口函数
+
+TilingFunc 是框架入口，创建 Tiling 类实例并调用 RunTiling，然后设置 workspace：
+
+```cpp
+static ge::graphStatus TilingFunc{OP}(gert::TilingContext *context)
+{
+    {OP}Tiling tiling(context);
+    auto ret = tiling.RunTiling();
+    if (ret != GRAPH_SUCCESS) {
+        return ret;
+    }
+    size_t *workspaces = context->GetWorkspaceSizes(1);
+    OP_CHECK_NULL_WITH_CONTEXT(context, workspaces);
+    workspaces[0] = 0;  // Broadcast 不需要 workspace
+    return GRAPH_SUCCESS;
+}
+```
+
+### 8.4 RunTiling 分发
+
+RunTiling 按 RANK 分叉到 DoTilingAndSet<4> 或 DoTilingAndSet<8>，设置 TilingKey：
+
+```cpp
+ge::graphStatus {OP}Tiling::RunTiling()
+{
+    ge::graphStatus ret = GetShapeInfo();
+    if (ret != GRAPH_SUCCESS) {
+        return ret;
+    }
+
+    int64_t mapped = (rank_ <= {OP_UPPER}_RANK_4) ? {OP_UPPER}_RANK_4 : {OP_UPPER}_RANK_8;
+    if (mapped == {OP_UPPER}_RANK_4) {
+        ret = DoTilingAndSet<{OP_UPPER}_RANK_4>();
+        ctx_->SetTilingKey(GET_TPL_TILING_KEY({OP_UPPER}_RANK_4));
+    } else {
+        ret = DoTilingAndSet<{OP_UPPER}_RANK_8>();
+        ctx_->SetTilingKey(GET_TPL_TILING_KEY({OP_UPPER}_RANK_8));
+    }
+    return ret;
+}
+```
+
+### 8.5 DoTilingAndSet 模板函数
+
+按 RANK 模板实例化，填充 TilingData 全字段、设置 BlockDim、打印维测日志。完整伪码见 §4。
+
+### 8.6 IMPL_OP_OPTILING 注册宏
+
+一行注册三件事：Tiling 函数、TilingParse 回调、CompileInfo 类型：
+
+```cpp
+IMPL_OP_OPTILING({OP}).Tiling(TilingFunc{OP}).TilingParse<{OP}CompileInfo>(TilingPrepareFor{OP});
+```
+
+**约束**：
+- `{OP}` = 算子名 CamelCase，与 `OP_ADD({OP})` 一致
+- CompileInfo 类型必须与 TilingPrepare 中 `GetCompiledInfo<>` 模板参数一致
+- TilingFunc 签名固定为 `static ge::graphStatus(gert::TilingContext*)`

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/adapters/dsl/capability-mapping.md

@@ -0,0 +1,50 @@
+# Broadcast 范式 CANNBotDSL 能力映射
+
+> **层级**：CANNBotDSL 语言适配层。对 [../../generic/capability-contract.md](../../generic/capability-contract.md) 中全部能力谓词给出 CANNBotDSL（下文简称 DSL）真值与 API 实体。
+>
+> **真值状态声明**：本表首期基于已有 DSL API 职责分类与实现资料填写。材料只能证实到"职责类目存在"层面的谓词填类目事实并标注来源；无法证实的标**待验证**。待验证谓词的影响与收敛规则见 §3。
+
+## 1 谓词真值表
+
+| 谓词 | DSL 真值 | 依据 / 验证义务 |
+|------|------|------|
+| `CAP_BROADCAST_IN_TRANSFER` | **待验证** | DSL 存在数据搬运类目（`ops.memcpy`：DMA、copy engine、分块搬运、padding、`mem_copy`），但搬运是否支持广播轴 stride=0 随路展开未证实。验证义务：查 CANNBotDSL 搬运 API 的 stride/广播参数。若为 false，通用层数据流退化为独立广播步骤（P 值 +1，见 [../../generic/liveness-fusion.md](../../generic/liveness-fusion.md) 冲突处理） |
+| `CAP_REG_CHAIN_FUSION` | **待验证** | DSL 存在寄存器算术类目（`ops.reg`：寄存器算术、比较、mask、load/store），链式中间值是否驻留寄存器不落片上 buffer 未证实。验证义务：查 `ops.reg` 运算的数据落点语义 |
+| `CAP_FUSED_ARITH` | **待验证** | 寄存器算术类目存在，但"一条接口完成两步运算"的融合指令集合未证实。验证义务：查 `ops.reg` 融合类接口清单 |
+| `ALIGN_GRANULARITY` | **待验证** | Buffer/Channel 构造的对齐粒度未证实。验证义务：查 Buffer/Channel 构造 API 的对齐约束。影响：通用层 `perBufBytes` 对齐公式（[../../generic/splitting.md](../../generic/splitting.md)）暂以假设值代入并声明 |
+| `TRANSFER_MAX_DIMS` | **待验证** | 分块搬运的维数上限未证实。影响：通用层搬运策略分叉（全维单次 vs 逐段）暂不定型 |
+| `FUSION_CHAIN_MAX_LEN` | **待验证** | 依赖 `CAP_REG_CHAIN_FUSION` 的验证结果 |
+| `CONVERT_BREAKS_CHAIN` | **待验证** | 类型转换与寄存器链的关系未证实（标量 cast 已有类目，张量级 cast 落点未证实） |
+| `CONVERT_INPLACE` | **待验证** | 精度转换可否原地完成未证实。影响：转换中转 buffer 是否需要（P 值推导） |
+| `COMPUTE_PRECISION` | **待验证** | DSL 范式统一计算精度策略未证实，不排除按 dtype 原位计算。影响：`perBufElems` 公式的字节宽度取值 |
+| `BUFFER_MODEL` | **Buffer / Channel 双原语**：阶段内临时量用 Buffer 显式管理；跨阶段/跨角色生产消费用 Channel（acquire/commit/wait/release 数据流接口） | 已有 DSL Buffer/Channel 用法资料与 API 数据流类目；具体行为仍需核对目标 DSL 能力 |
+| `SYNC_PRIMITIVE` | 类目存在：pipe、barrier、busy wait、事件、buffer 同步、跨核同步（`ops.sync`）；Channel 自带 acquire/commit/wait/release 交接语义。**具体调用规则待验证** | 调用方提供的 DSL 同步 API 资料 |
+| `EXEC_UNITS` | **待验证** | 架构/平台信息类目（`ops.arch` / `ops.info`：block/core/subblock 索引、内存容量）存在，但搬入/计算/搬出执行单元划分及事件配对规则未证实。影响：通用层 sync-model 的事件对推导暂以 Channel 交接语义保守替代 |
+
+## 2 通用术语 → DSL 实体对照
+
+| 通用层术语 | DSL 实体 |
+|------|------|
+| 片上 buffer（阶段内临时量） | Buffer（指定 MemLoc / dtype / shape / 生命周期，当前阶段可反复读写） |
+| 片上 buffer（生产/消费交接） | Channel（produce/consume 成对，acquire/commit/wait/release） |
+| 设备侧计算 | `@kernel` / `@jit` 装饰的 DSL kernel 及其阶段方法 |
+| Host 侧调度 | 公开入口 + Host launcher（torch 张量作公开接口） |
+| 搬入 / 搬出 | 数据搬运类目（`ops.memcpy`：DMA、copy engine、layout/format transform、分块搬运、`mem_copy`） |
+| tile / 切分 | tiler（`tensor-types-and-layout` 类目） |
+| 寄存器计算 | `ops.reg` 类目（寄存器算术、比较、mask、load/store、规约） |
+| 多核 / 架构参数 | `ops.arch` / `ops.info` 类目（block/core/subblock 索引、内存容量） |
+| 编译期特化（RANK 分档） | constexpr / JIT / kernel 装饰器（`language-and-kernel` 类目）；具体特化机制待验证 |
+
+## 3 待验证谓词的使用与收敛规则
+
+1. **产出声明**：设计/代码产出引用任一待验证谓词支撑的通用层公式时，必须显式标注"该结论依赖待验证假设"并写出验证义务
+2. **禁止虚假确定**：不得把"职责类目存在"写成"能力已验证"——API 分类只描述代码职责，不证明硬件支持、算法适用性或运行时行为（API 分类的证据边界）
+3. **真值收敛**：CANNBotDSL 权威材料（wheel API 提取索引、官方文档、实测结论）就位后，逐项替换待验证真值并删除对应验证义务；某谓词长期填不出真值时，按 [../../generic/capability-contract.md](../../generic/capability-contract.md) §1 规则 3 修订通用层抽象而非绕过
+
+## 4 关键语言级附加约束
+
+1. **设备计算归属**：spec / DESIGN 规定在设备上完成的值计算、类型转换、布局搬运、掩码/尾块处理、最终输出合成，必须落在 CANNBotDSL kernel 内；禁止在公开入口、Host launcher 或其可达辅助函数中用 `torch` / `torch.nn.functional` 小算子（会触发设备算子或复制的操作，如 `torch.add`、`.to(dtype)`、`F.*`、隐式 copy 的视图变换）补全实现。Host 仅限：读取 shape/dtype/device 元数据、分配输出/workspace、建立零拷贝视图、发起 DSL kernel
+2. **Channel/Buffer 选择**：数据需要生产/消费同步才用 Channel；仅为当前阶段可反复读写的临时量用 Buffer；produce/consume 必须成对、不越生命周期，临时量没有交接语义时不硬建 Channel
+3. **Channel 深度非规范**：depth=1/2/3 是样例选择，按在飞任务数、资源预算与复用时序核定，不固定取值
+4. **尾块纪律**：不把无效尾行写入输出；布局表面相同不等于 Channel 兼容（NZ/ND 物理布局需逐项核对）
+5. **平台参数获取**：核数、内存容量等经架构/平台信息类目 API 获取，严禁写死

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/adapters/dsl/implementation-guide.md

@@ -0,0 +1,52 @@
+# Broadcast 范式 CANNBotDSL 实现指引
+
+> **层级**：CANNBotDSL 语言适配层叶子文档。通用层算法见 [../../generic/index.md](../../generic/index.md)；谓词真值见 [capability-mapping.md](capability-mapping.md)。
+>
+> 本指引结合 DSL 公开入口、Host、Kernel 的职责和 Broadcast 通用层模型。具体 API 签名与设备能力以调用方提供的 DSL 资料为准，本文不复制 API 签名。
+
+## 1 数据流骨架 → DSL 三层结构映射
+
+通用层三段式数据流（[../../generic/scene.md](../../generic/scene.md) §3）落到 DSL 的入口/Host/Kernel 三层：
+
+| 通用层阶段 | DSL 落地 | 关键约束 |
+|------|------|------|
+| 段 1 搬入（随路广播） | Host launcher 分配输出/workspace 后，kernel 内经数据搬运类目 API 完成 GM → 片上 | 随路广播依赖 `CAP_BROADCAST_IN_TRANSFER`（待验证）；为 false 时退化为独立广播步骤，P 值 +1，按 [../../generic/liveness-fusion.md](../../generic/liveness-fusion.md) 重推 buffer 布局 |
+| 段 2 计算 | `@kernel` 内寄存器运算（`ops.reg`）逐元素计算 | 链式中间值驻留寄存器依赖 `CAP_REG_CHAIN_FUSION`（待验证）；为 false 时中间值落 Buffer，按通用层存活节点模型重推 P 值 |
+| 段 3 搬出 | kernel 内片上 → GM 独立搬出 | 有效行数写入，不把无效尾行写入输出 |
+
+## 2 代码组织（三层职责）
+
+| 层 | 职责 | 边界 |
+|------|------|------|
+| 公开入口 | 检查公开 dtype / shape / layout / device 参数组合；准备输出并委托 Host/Kernel | 不把设备计算藏在入口或可达辅助函数 |
+| Host launcher | 静态配置、输出/workspace 分配、布局归一化、launch 分开组织 | 只做元数据 / 分配 / 零拷贝视图；torch 调用若触发设备算子或复制即越界（见 [capability-mapping.md](capability-mapping.md) §4 规则 1） |
+| Kernel | 按真实数据所有权拆阶段方法，避免单个巨型 `__call__` | Broadcast 纯 Vector 路径通常无 Cube/Vector 交接，不因样例结构给纯 Vector 算子加 CrossCore Channel |
+
+## 3 Buffer/Channel 规划
+
+1. buffer 数量按通用层 [../../generic/liveness-fusion.md](../../generic/liveness-fusion.md) 的 P 值推导：Broadcast standard 路径 P = 输入数 + 输出数 + 融合压缩后的中间值数
+2. 阶段内中间量用 Buffer（无交接语义不建 Channel）；仅真实生产/消费交接处用 Channel，produce/consume 成对、不越生命周期
+3. Channel 深度按在飞任务数与资源预算核定（depth=1/2/3 均为合法样例选择，非规范）
+4. 单 buffer 容量按通用层 [../../generic/splitting.md](../../generic/splitting.md) 公式：`perBufBytes = floor(片上容量/P)`，对齐粒度以 [capability-mapping.md](capability-mapping.md) `ALIGN_GRANULARITY` 真值为准（待验证，代入时声明假设）
+
+## 4 shape 归一化与切分的 DSL 落地
+
+1. 补 1 / 去 1 / 归一 / 合轴四步算法（[../../generic/shape-preprocessing.md](../../generic/shape-preprocessing.md)）在 Host launcher 侧用纯元数据操作完成（shape 运算、视图建立），不触发设备计算
+2. 片上单切分与多核切分（[../../generic/splitting.md](../../generic/splitting.md)）的切分参数由 Host 计算后传入 kernel，或经 tiler 表达；具体机制以 DSL API 实际支持为准（待验证）
+3. 多核切分的核数经架构/平台信息类目 API 获取，严禁写死
+
+## 5 尾块与同步
+
+1. 尾块处理（掩码/有效行）在 kernel 内完成；不把无效尾行写入输出
+2. Buffer/Channel 交接遵守 acquire/commit/wait/release 成对语义；跨执行单元事件的配对规则依赖 `SYNC_PRIMITIVE` / `EXEC_UNITS` 真值（待验证），就位前同步设计按 Channel 自带交接语义保守设计并标注假设
+
+## 6 产出与验证义务
+
+每个 DSL 实现决策按如下格式回答（micro-patterns 纪律）：
+
+```
+适用前提 → 最小代码位置/伪代码 → 生命周期或同步不变量 → 对应 Unit 测试
+```
+
+- 数学语义与形状以当前算子规格为准，Buffer 容量、Channel 深度和同步关系按实际数据流及资源预算推导。
+- 引用待验证谓词的结论，按 [capability-mapping.md](capability-mapping.md) §3 声明假设并给出验证义务

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/adapters/dsl/index.md

@@ -0,0 +1,33 @@
+# Broadcast 范式 CANNBotDSL 语言适配层
+
+> **层级**：CANNBotDSL 语言适配层（adapters/dsl/）。语言中立的算法与模型见 [../../generic/index.md](../../generic/index.md)；范式入口与语言路由见 [../../patterns.md](../../patterns.md)。
+
+## 1 定位
+
+本目录承载 Broadcast 范式中**强耦合 CANNBotDSL（下文简称 DSL）**的知识：DSL 实体映射、能力谓词真值、代码组织与实现约束。开发语言为 `dsl` 时，与通用知识层组合消费：
+
+```
+通用算法/模型（generic/）× DSL 实现细节（本目录）→ CANNBotDSL 设计与代码产出
+```
+
+## 2 能力映射
+
+本语言对通用层能力谓词的真值与 DSL 实体见 [capability-mapping.md](capability-mapping.md)。通用层算法中引用的谓词（对齐粒度、随路广播能力、融合链长等）一律以该文件填值为准；标注**待验证**的谓词不得当作已验证真值使用，须在产出中显式声明假设。
+
+## 3 阅读路径
+
+| 任务阶段 | 入口 | 内容 |
+|------|------|------|
+| 方案设计 | [../../generic/index.md](../../generic/index.md)（通用层算法）→ [capability-mapping.md](capability-mapping.md)（谓词真值） | 场景模型 / shape 归一化 / 切分 / 存活节点等语言中立算法，叠加 DSL 能力真值与落地差异 |
+| DSL 代码组织与实现 | [implementation-guide.md](implementation-guide.md) | 通用层数据流骨架到 DSL 入口/Host/Kernel 三层的映射、Buffer/Channel 规划、尾块与同步 |
+
+## 4 补充输入
+
+设计需要公开 DSL API 资料、目标设备能力和已有实现参考时，由调用方提供相应资料。只依据实际提供的证据选择 API、资源和同步写法；缺少证据时列出待确认事实。
+
+## 5 消费规则
+
+1. 语言路由命中本适配层后，**只读本适配层 + 通用层**，不加载 ascendc 适配层、不参考其 API 与代码模板
+2. 单个子问题最多展开 5 个叶子文档；仍未闭环则拆分子问题
+3. 能力谓词以 [capability-mapping.md](capability-mapping.md) 为准；**待验证**谓词支撑的设计结论必须在产出中声明假设并给出验证义务，禁止写成已验证事实
+4. **设计文档生成**：使用 `references/paradigms/general-methodology-dsl.md` 通用方法与通用层知识，并按 [capability-mapping.md](capability-mapping.md) §4 和 [implementation-guide.md](implementation-guide.md) 补充 DSL 实现约束。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/broadcast/generic/capability-contract.md

@@ -0,0 +1,41 @@
+# Broadcast 范式能力谓词契约
+
+> **层级**：通用知识层（generic/），语言中立。
+>
+> 通用层算法中依赖硬件/语言能力的量，统一抽象为**能力谓词**。通用层文档只引用谓词名，不出现任何具体语言 API。每个语言适配层必须在其 `capability-mapping.md` 中对全部谓词给出真值。
+
+## 1 使用规则
+
+1. **通用层**：算法描述中遇到能力依赖点时，引用本文档中的谓词名，不写具体数值或 API 名
+2. **适配层**：`adapters/<lang>/capability-mapping.md` 逐项填写谓词真值与对应的 API 实体
+3. **可填性检验**：新语言适配层必须能对每个谓词给出真值。填不出真值说明通用层抽象有缺陷，应修订抽象而非绕过
+4. **冲突处理**：同一能力点若适配层真值与通用层假设冲突（如某语言搬运不支持随路广播），以适配层真值为准，并在该能力点标注设计影响（如退化为独立广播步骤、P 值增加）
+
+## 2 谓词定义表
+
+| 谓词 | 类型 | 含义 | 影响的通用层知识点 |
+|------|------|------|------------------|
+| `CAP_BROADCAST_IN_TRANSFER` | bool | 搬入单元是否支持广播轴随路展开（源侧 stride=0 原地重读，搬运时直接展开到目标形态） | scene 数据流路线；liveness-fusion 搬运随路广播不占额外 buffer |
+| `CAP_REG_CHAIN_FUSION` | bool | 计算单元是否支持寄存器链融合（链式中间值留在寄存器，不落片上 buffer） | liveness-fusion 中 P < L 的合法性 |
+| `CAP_FUSED_ARITH` | list | 硬件融合指令集合（一条指令完成两步运算、目的操作数就地覆写、省 1 个中间 buffer） | liveness-fusion 融合决策的候选集 |
+| `ALIGN_GRANULARITY` | bytes | 片上 buffer 大小的对齐粒度 | splitting perBufBytes 公式 |
+| `TRANSFER_MAX_DIMS` | int | 多维搬运单条指令的维数上限 | splitting 维度分层；搬运策略分叉（全维单次 vs 逐段） |
+| `FUSION_CHAIN_MAX_LEN` | int | 单条融合链的操作数上限 | liveness-fusion 融合判据 1 |
+| `CONVERT_BREAKS_CHAIN` | bool | 精度转换操作是否打断融合链 | liveness-fusion 融合判据 2；compute-flow dtype 分路径步骤数 |
+| `CONVERT_INPLACE` | bool | 精度转换可否原地完成（src/dst 同一块 buffer） | liveness-fusion 额外 buffer 需求（转换中转 buffer） |
+| `COMPUTE_PRECISION` | type | 范式统一采用的计算精度类型 | splitting perBufElems 公式；liveness-fusion 转换策略 |
+| `BUFFER_MODEL` | enum | 片上 buffer 管理模型（显式单缓冲 / 队列式管理） | sync-model 手动同步需求；liveness-fusion 单缓冲策略 |
+| `SYNC_PRIMITIVE` | desc | 跨执行单元同步原语及其事件管理规则 | sync-model 同步点落地方式 |
+| `EXEC_UNITS` | desc | 执行单元划分（搬入单元 / 计算单元 / 搬出单元） | sync-model RAW/WAR 事件对 |
+
+## 3 谓词使用示例
+
+通用层 splitting 文档中的写法：
+
+> `perBufBytes = floor(片上容量 / P)` 按 `ALIGN_GRANULARITY` 向下对齐
+
+AscendC 适配层（capability-mapping.md）中的填值：
+
+> `ALIGN_GRANULARITY` = 32 字节（`ONE_BLK_SIZE`）
+
+DSL 适配层若对齐粒度为 16 字节，则填 16，通用层公式无需任何修改。