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

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/adapters/ascendc/binary-tree.md

@@ -0,0 +1,260 @@
+# 二分缓存树
+
+> 本范式所有 reduce 算子（sum/mean/max/min/prod/any/all）统一使用二分缓存树。对 sum/mean 有精度收益（浮点累加误差从 O(M) 降到 O(log M)），对 max/min/any/all 结果不变（满足结合律），prod 因 fp 舍入不满足结合律、结果可能有差异，但统一路径简化了模板设计。
+
+## 一、背景与问题
+
+假设要对 N=10000 个 fp32 数求和，结果为 1 个数。NPU 的 UB（Unified Buffer）单次只能载入 B=512 个数，无法一次性装入全部数据。
+
+因此必须分块处理：将 10000 个数分成 M=⌈N/B⌉=20 块（前 19 块各 512 个，最后 1 块 272 个），逐块载入 UB、用向量指令 reduce 成 1 个部分和，最后把 M=20 个部分和合并成最终结果。
+
+**核心问题：如何合并这 20 个部分和，使浮点累加误差尽可能小？**
+
+---
+
+## 二、为什么用二分树
+
+### 2.1 顺序累加的精度问题
+
+最直观的做法是维护一个累加器，每算完一块就加上去：
+
+```
+s = 0
+for i in 0..M-1:
+    s = s + chunk_sum[i]    // 顺序累加
+```
+
+随着 `s` 逐渐增大，后续 `chunk_sum[i]` 相对于 `s` 越来越小。浮点加法中，两个量级差异大的数相加会丢失有效位，**误差随累加次数线性增长，为 O(M)**。
+
+### 2.2 树形归约的优势
+
+二分树把 M 个部分和两两配对、逐层合并，树高仅 log₂(M)：
+
+```
+第0层:  s0   s1   s2   s3   s4   s5   s6   s7   ...  (16个部分和)
+         \  /     \  /     \  /     \  /
+第1层:    a0       a1       a2       a3         ...  (8个)
+           \      /           \      /
+第2层:      b0                 b1               ...  (4个)
+             \               /
+第3层:          c0            c1                     (2个)
+                 \          /
+第4层:              d0                              (1个 = 最终结果)
+```
+
+每一层相加的两个数量级相近，有效位损失小。**误差增长为 O(log M)**。
+
+当 M=20 时，顺序累加误差 ~O(20)，二分树 ~O(log₂16)=O(4)，精度显著提升。
+
+---
+
+## 三、非 2 幂的处理：主尾配对
+
+二分树要求叶子数为 2 的幂，但 M=20 不是 2 的幂。
+
+取 P = 严格小于 M 的最大 2 幂 = 16，尾段 T = M − P = 4。
+
+将尾段 4 块与主段前 4 块**两两配对合并**，每对产生 1 个部分和：
+
+```
+Phase A (配对, i=0..3):
+    chunk[i] 与 chunk[i+P] 配对
+    → 载入两块 → 逐元素相加成 1 块 → reduce → 1 个部分和
+
+Phase B (独立, i=4..15):
+    chunk[i] 单独处理
+    → 载入 → reduce → 1 个部分和
+```
+
+配对后，树的输入数恰好为 P=16（2 幂），形成完美二叉树。
+
+> **为什么取"严格小于"而非"≤"**：当 M 本身为 2 幂时（如 M=16），取 P=M/2=8 而非 M=16，树深少 1 层，缓存空间省一个 fp32 槽；代价是需多做 M/2 次配对（Phase A）。M 非 2 幂时（如 M=20），两种取法结果相同。用一点计算换空间更划算。
+
+> 配对时两块逐元素相加成一个块再 reduce，而非各自 reduce 后再加两个标量——这样元素级配对精度更好，且只调一次 reduce。尾块可能不足 B 个数（如最后一个 272），与主块配对时将尾块的有效元素逐元素加到主块对应位置即可（等价于尾块补零到 B 再逐元素相加），不影响求和结果。
+
+---
+
+## 四、顺序循环中的树形归约
+
+### 4.1 核心挑战
+
+NPU 单核顺序执行，无法真正并行做树形归约。传统树形归约需保存全部叶子（第0层 s0..s_{P-1}），当 P 较大时 UB 空间不够。需要一个机制：**在顺序循环中，把每个部分和写到正确的树层级，用 L=log₂(P)+1 个 cache 槽轮转复用，替代保存全部叶子的空间开销**。
+
+### 4.2 多级缓存
+
+在 UB 中开辟 L 个缓存槽，L = log₂(P) + 1 = 5（level 0..4）：
+
+| 层级 | 含义 | 覆盖范围 | 写入频率 |
+|------|------|---------|---------|
+| cache[0] | 1 个部分和 | 1 块 | 每 1 次迭代 |
+| cache[1] | 2 个部分和的合并 | 2 块 | 每 2 次迭代 |
+| cache[2] | 4 个部分和的合并 | 4 块 | 每 4 次迭代 |
+| cache[3] | 8 个部分和的合并 | 8 块 | 每 8 次迭代 |
+| cache[4] | 全部 16 个部分和的合并 | 16 块 | 最后 1 次（树根）|
+
+### 4.3 写入层级规则
+
+迭代序号 i 的二进制表示中，**末尾连续 1 的个数**决定写入层级：
+
+```
+level(i) = i 的二进制末尾连续 1 的个数
+```
+
+直觉：这与二进制计数器的进位传播一致——当低位全为 1 时，加 1 会触发连续进位，进位传播到第几位，就对应写入第几层。
+
+前 16 次迭代（P=16）的层级分配：
+
+| i | 二进制 | 末尾 1 个数 | 写入层级 | 动作 |
+|---|--------|-----------|---------|------|
+| 0 | 0000 | 0 | cache[0] | 直接写入 |
+| 1 | 0001 | 1 | cache[1] | 吸收 cache[0]，写入 |
+| 2 | 0010 | 0 | cache[0] | 直接写入 |
+| 3 | 0011 | 2 | cache[2] | 吸收 cache[0,1]，写入 |
+| 4 | 0100 | 0 | cache[0] | 直接写入 |
+| 5 | 0101 | 1 | cache[1] | 吸收 cache[0]，写入 |
+| 6 | 0110 | 0 | cache[0] | 直接写入 |
+| 7 | 0111 | 3 | cache[3] | 吸收 cache[0,1,2]，写入 |
+| ... | ... | ... | ... | ... |
+| 15 | 1111 | 4 | cache[4] | 吸收 cache[0,1,2,3]，写入（树根）|
+
+### 4.4 写入时的吸收规则
+
+写入 cache[k] 前，先把 cache[0], cache[1], ..., cache[k-1] 全部吸收（相加），再覆盖写 cache[k]：
+
+```
+写入 cache[k]:
+    result = 当前部分和
+    for j = 0 to k-1:
+        result = result + cache[j]    // 吸收所有低层
+    cache[k] = result                  // 覆盖写本层
+```
+
+**为什么必须正序（j=0→k-1）吸收？** cache[j] 覆盖 2^j 块的数据量，正序吸收保证每步相加的两个数量级匹配：result(1块) + cache[0](1块) → result 变 2 块量级 → result(2块) + cache[1](2块) → result 变 4 块量级 → ……每步 result 与 cache[j] 覆盖范围相同，精度最优。若倒序（j=k-1→0），result(1块) 直接加 cache[k-1](2^(k-1) 块)，量级悬殊，小数被吃有效位，破坏二分树的精度优势。顺序不能变。
+
+**为什么 cache[k] = result 是覆盖而不是 cache[k] = cache[k] + result 累加？** cache[k] 此前保存的是上一轮同层写入的旧值（已被更高层吸收过）。若累加，会把过期旧值叠进当前结果，导致重复计算。
+
+### 4.5 树填充过程（P=16）
+
+以 S 表示每次迭代产生的部分和：
+
+```
+i=0:  cache[0]=S                                   树: [S, _, _, _, _]
+i=1:  cache[1]=S+cache[0]                          树: [_, S, _, _, _]
+i=2:  cache[0]=S                                   树: [S, _, _, _, _]
+i=3:  cache[2]=S+cache[0]+cache[1]                 树: [_, _, S, _, _]
+i=4:  cache[0]=S                                   树: [S, _, S, _, _]
+i=5:  cache[1]=S+cache[0]                          树: [_, S, S, _, _]
+i=6:  cache[0]=S                                   树: [S, _, S, _, _]
+i=7:  cache[3]=S+cache[0]+cache[1]+cache[2]        树: [_, _, _, S, _]
+...
+i=15: cache[4]=S+cache[0]+cache[1]+cache[2]+cache[3]  树: [_, _, _, _, S] ← 根
+```
+
+迭代结束后，cache[4]（最高层）包含全部 16 个输入的累加和，也就是所有 20 块的最终结果。
+
+---
+
+## 五、数据流图
+
+```
+GM: 10000 个 fp32
+     │
+     │  分块载入 (每块 B=512)
+     ▼
+ ┌──────────────────────────────────────────────────────┐
+ │  chunk[0]  chunk[1]  ...  chunk[15]  │  chunk[16..19] │
+ │  ─────── 主段 P=16 块 ──────────  │  ─尾段 T=4 块─ │
+ └────┬────────┬─────────────┬────────┴──────┬─────────┘
+      │        │             │               │
+      │   Phase A (i<T): chunk[i] 与 chunk[i+P] 配对     │
+      │       → 载入两块 → 逐元素相加成 1 块 → reduce     │
+      │   Phase B (i≥T): chunk[i] 独立处理               │
+      │       → 载入 → reduce                            │
+      │        │             │               │
+      ▼        ▼             ▼               │
+   每块/每对载入 UB → 向量 reduce → 1 个 fp32  │
+      │        │             │               │
+      ▼        ▼             ▼               │
+ ┌────────────────────────────────────────┐  │
+ │       二分缓存树 (UB, 仅 5 个 fp32)      │  │
+ │                                        │  │
+ │  cache[0]  cache[1]  cache[2]  ...  cache[4] │
+ │                                        │  │
+ │  按"末尾 1 个数"规则确定写入层级,         │  │
+ │  写入前吸收所有低层, 覆盖写本层           │  │
+ └────────────────────────────────────────┘  │
+                   │                        │
+                   ▼                        │
+           cache[4] = 最终总和 ◄──────────────┘
+```
+
+---
+
+## 六、伪码
+
+### 6.1 辅助函数
+
+```
+// FindNearestPower2: 严格小于 value 的最大 2 的幂。 value 为 0 或 1 时特例
+// 例: value=0→0, 2→1, 3→2, 4→2, 8→4, 16→8, 20→16
+FindNearestPower2(value):
+    if value == 0: return 0
+    if value <= 2: return 1
+    return 1 << floor(log2(value - 1))
+
+// GetCacheID: 二进制末尾连续 1 的个数 = 写入层级
+// 例: 0→0, 1→1, 2→0, 3→2, 4→0, 5→1, 6→0, 7→3, 8→0
+GetCacheID(idx):
+    return count_ones(idx ^ (idx + 1)) - 1
+
+// DoCaching: 吸收所有低层后覆盖写本层
+DoCaching(k, result):
+    for j = 0 to k-1:
+        result = result + cache[j]           // 正序吸收所有低层
+    cache[k] = result                         // 覆盖写本层
+
+// GetCacheRoot: 取缓存树根节点（最高层）
+GetCacheRoot(P):
+    L = log2(P) + 1
+    return cache[L-1]
+```
+
+### 6.2 主流程
+
+```
+输入: N=10000 个数, UB 容量 B=512
+M = ceil(N / B)              // 20, 总块数
+P = FindNearestPower2(M)     // 16, 主段长度(2幂)
+T = M - P                    // 4,  尾段长度
+L = log2(P) + 1              // 5,  缓存树层数
+
+for i = 0 to P-1:
+    // ── 1. 载入并求和 ──
+    if i < T:                                // Phase A: 主尾配对
+        load chunk[i]    → tmpBuf[0]
+        load chunk[i+P]  → tmpBuf[1]
+        tmpBuf[0] = tmpBuf[0] + tmpBuf[1]    // 逐元素相加成 1 块
+        result = reduce(tmpBuf[0])           // 1 个 fp32
+    else:                                    // Phase B: 独立
+        load chunk[i]    → reduce → result
+
+    // ── 2. 写入缓存树 ──
+    k = GetCacheID(i)                        // 末尾连续1的个数 = 写入层级
+    DoCaching(k, result)                     // 吸收所有低层，覆盖写 cache[k]
+
+answer = GetCacheRoot(P)                     // 树根 = 最终结果
+```
+
+---
+
+## 七、设计要点总结
+
+1. **主尾配对解决非 2 幂**：把 M 拆成 P（严格小于 M 的最大 2 幂）+ T，尾段 T 块与主段前 T 块配对合并，使树输入数为 P（2 幂），形成完美二叉树。M 为 2 幂时取 P=M/2，树深少 1，空间更省。
+
+2. **末尾 1 规则编码树结构**：顺序循环中，迭代序号 i 的二进制末尾连续 1 的个数决定写入层级，使顺序执行天然形成树形归约的依赖关系，无需显式建树。
+
+3. **吸收低层再覆盖写**：写入 cache[k] 前吸收所有低层 cache[0..k-1]，然后覆盖。低层旧值已被吸收，覆盖不影响正确性，且不需要额外缓冲。
+
+4. **精度提升**：树形归约每层相加的两个数量级相近，误差为 O(log P) 而非顺序累加的 O(M)。
+
+5. **空间极小**：缓存树仅需 L=log₂(P)+1 个 fp32，远小于保存全部中间结果的开销。

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

@@ -0,0 +1,49 @@
+# Reduction 范式 AscendC 能力映射
+
+> **层级**：AscendC 语言适配层。对 [../../generic/capability-contract.md](../../generic/capability-contract.md) 中全部能力谓词给出 AscendC 真值与 API 实体。
+
+## 1 谓词真值表
+
+| 谓词 | AscendC 真值 | API 实体 / 规则文档 |
+|------|------|------|
+| `REDUCE_OP` | `ReduceSum` / `ReduceMax` / `ReduceMin` / `ReduceProd` / `ReduceAny` / `ReduceAll` 高阶 API；Pattern 按 tail 类型选择（tail-R→`Pattern::Reduce::AR`，tail-A→`RA`）；srcShape 按 padded 值；`srcInnerPad=true` 恒成立；src/dst 与 sharedTmpBuffer 互不重叠 | [highlevel-api.md](highlevel-api.md) §1–§5 |
+| `REDUCE_OP_PRECISION` | 多路并行二叉树折叠（单 chunk 内；与范式级二分缓存树构成两级树） | [highlevel-api.md](highlevel-api.md) §6 |
+| `TREE_CACHE_CAPACITY` | **16 KB**（`cacheBuf`，二分缓存树专用，恒定值不得修改） | [overview.md](overview.md) §4.1.1、[templates/binary-base/tiling.md](templates/binary-base/tiling.md) §5.1 |
+| `COMPUTE_PRECISION` | **FP32（4 字节）**；b16 输入先扩位再归约；`maxDtypeSize = max(sizeof(D_T), sizeof(float))` | [common/cast-rules.md](../../../common/cast-rules.md) §4 |
+| `ALIGN_GRANULARITY` | **32 字节**（UB block / `ONE_BLK_SIZE`）；`bsElem = blockSize / sizeof(D_T)` | 平台接口 `GetUbBlockSize`（禁止写死 32） |
+| `CACHELINE_SIZE` | **256 B**（Ascend950） | 平台接口 `GetCacheLineSize`（禁止写死 256/512） |
+| `SINGLE_BUF_MAX` | **64 KB**（Empty 模板单 buf 封顶 `MAX_SINGLE_UB_BYTES`） | [templates/empty/dag-buffers.md](templates/empty/dag-buffers.md) §1.3 |
+| `FUSION_CHAIN_MAX_LEN` | **7**（超过 7 条 Vector 操作必须拆为多次 `asc_vf_call`） | [vf-fusion-rules.md](vf-fusion-rules.md) §1.1 |
+| `CONVERT_IN_CHAIN` | **true**（`Reg::Cast` 寄存器指令可串入 VF 链，不作为断点） | [common/cast-rules.md](../../../common/cast-rules.md) §4.3 |
+| `REG_CHAIN_FUSION` | **true**（`asc_vf_call` + RegBase 寄存器链，中间值不落 UB，P < L 合法） | [common/vf-programming-rules.md](../../../common/vf-programming-rules.md) |
+| `BUFFER_MODEL` | **TBuf 显式单缓冲**（禁 TQue）；Double Buffer 当前**不开启** | [templates/binary-base/dag-buffers.md](templates/binary-base/dag-buffers.md) §1.4 |
+| `SYNC_PRIMITIVE` | `SetFlag<HardEvent::XXX>` / `WaitFlag<HardEvent::XXX>` 成对使用；eventID 经 `GetTPipePtr()->FetchEventID()` 获取，不可硬编码；同类型事件可共用编号 | [common/sync-and-consistency.md](../../../common/sync-and-consistency.md) §2.2 |
+| `EXEC_UNITS` | MTE2（搬入）/ V（计算）/ MTE3（搬出）；事件命名 `源_目标`（`MTE2_V` / `V_MTE3` / `V_MTE2` / `MTE3_V` / `MTE3_MTE2`） | [common/sync-and-consistency.md](../../../common/sync-and-consistency.md) |
+| `CROSS_CORE_FENCE` | `SyncAll()`（Group Phase 1→2 全核同步）；host 侧必须 `SetScheduleMode(1)`，否则挂死 | [templates/binary-group/tiling.md](templates/binary-group/tiling.md) §5.5 |
+| `WORKSPACE_MODEL` | `ws[0] = GetLibApiWorkSpaceSize() + 用户部分`（Group：`usrWorkspaceBytes = rGroupCnt × aTotal × sizeof(fp32)`，`[rGroupCnt, aTotal]` fp32 dense 行优先） | [templates/binary-base/tiling.md](templates/binary-base/tiling.md) §5.2 |
+| `MULTICORE_BALANCE` | 大小核式：前 `aBigCoreCnt` 核多担 1 份，最大负载差 ≤ 1；`usedCoreNum = (aSmallCoreLoopCnt > 0) ? coreNum : aBigCoreCnt` | [templates/binary-base/tiling.md](templates/binary-base/tiling.md) §2.2 |
+| `SCHEDULE_2D` | **true**（Group：A×R 2D 分核，`ComputeGroupSplit()`，`aPerCore=1` 恒成立） | [templates/binary-group/tiling.md](templates/binary-group/tiling.md) §2 |
+| `BLOCK_DISPATCH_MIN` | **1**（`SetBlockDim` 严禁 0；EMPTY_A 用核数为 0 时仍 `SetBlockDim(1)`，kernel 侧 `usedCoreNum=0` 短路） | [templates/empty/tiling.md](templates/empty/tiling.md) §1.2 |
+
+## 2 通用术语 → AscendC 实体对照
+
+| 通用层术语 | AscendC 实体 |
+|------|------|
+| 片上 buffer / 片上容量 | UB / `GetCoreMemSize(CoreMemType::UB)` |
+| 树缓存 | `cacheBuf`（16KB，TBuf 分配） |
+| 归约指令 | `ReduceXxx`（带 `sharedTmpBuffer` 重载，`preReduceResultTail` 兼作 sharedTmpBuffer，buffer 固定 3 份） |
+| 搬入 / 搬出 | `DataCopyPad`（+ `LoopModeParams`，K 平台分级：K=2 全平台 / K∈[3,4] 仅 950 / K≥5 host for 拆分） |
+| 寄存器链融合 | `asc_vf_call` + `LoadAlign` / `StoreAlign` |
+| 精度转换 | `CastTrait` + `Reg::Cast`（b16↔fp32 配对 DIST 模式） |
+| 单缓冲管理 | `TBuf<TPosition::VECCALC>` + `pipe_->AllocTBuf` |
+| 编译期模板选择 | `ASCENDC_TPL_*` 宏（禁 `TILING_KEY_IS`） |
+| dtype 注入 | `DTYPE_<INPUT_NAME>` 编译宏（不进 TilingKey） |
+| kernel 入口分发 | `if constexpr (isEmptyTensor / isGroup)` 三路分发 |
+
+## 3 关键语言级附加约束
+
+1. 所有 API 可用性判定的唯一入口是 [API 白名单](../../../../knowledge/api/regbase_api_whitelist.md)；不得把"待验证"写成"已验证"
+2. 平台参数（coreNum / ubSize / blockSize / cacheLineSize / vectorSize）严禁写死，必须通过接口获取并做零值守卫
+3. `__global__` 模板参数仅含 TilingKey 的 bool（`isGroup` / `isEmptyTensor`），禁止加 `typename D_T`
+4. 三模板物理分文件：`<op>_base.h` / `<op>_group.h` / `<op>_empty.h` + `<op>_apt.cpp` 入口（同 arch35/ 目录）
+5. 归一化/合轴四步函数封装为独立函数（每函数有效行数 ≤ 50），可独立单元测试

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/adapters/ascendc/design-spec.md

@@ -0,0 +1,26 @@
+# Reduction 范式 Ascend C 设计约束
+
+## 输入与输出
+
+输入为算子公式、公开接口、形状与类型范围、目标平台事实，以及当前设计问题。输出为适用场景、模板参数、TilingData、资源与同步约束和验证要点；文档文件名与章节组织由调用方指定。
+
+## 按主题读取
+
+- 模板与数据结构：[overview](overview.md)。
+- 输入与轴处理：[tiling-preprocess](tiling-preprocess.md)。
+- 入口与分发：[kernel-entrance](kernel-entrance.md)。
+- 存活节点与融合：[survival-node](survival-node.md)。
+- 缓存树：[binary-tree](binary-tree.md)。
+- 归约 API：[highlevel-api](highlevel-api.md)。
+- Base 切分：[tiling](templates/binary-base/tiling.md)。
+- Base Kernel：[kernel-template](templates/binary-base/kernel-template.md)。
+- 多次独立归约：[tuple-reduce](tuple-reduce.md)。
+
+## 一致性检查
+
+- 分支覆盖与规格范围一致；TilingKey 的取值与 Kernel 模板实例对应。
+- TilingData 每个字段的 Host 来源与 Kernel 消费含义一致。
+- 逻辑存活节点从数学依赖推导；物理 Buffer 数量结合融合、临时空间与生命周期计算，资源预算与切分参数一致。
+- 搬入、计算、搬出各阶段的尾块、布局和同步规则有明确依据。
+- API 验证状态查阅 [API 白名单](../../../../knowledge/api/regbase_api_whitelist.md)，未知项输出为待验证。
+- 精度验证使用独立参考结果，并覆盖实际分支与边界。

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/paradigms/reduction/adapters/ascendc/example/euclidean_norm_package/CMakeLists.txt

@@ -0,0 +1,289 @@
+# ----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# ----------------------------------------------------------------------------------------------------------
+
+# =============================================================================
+# euclidean_norm_package/CMakeLists.txt
+# =============================================================================
+#
+# ROLE: Top-level CMake build script for the EuclideanNorm vendor operator package.
+#   Orchestrates the complete build pipeline for a CANN custom operator:
+#   1. Compile host-side sources (tiling, graph, proto) into libascend_all_ops.so
+#   2. Run op_build (CANN's operator build tool) to auto-generate stubs
+#   3. Overwrite auto-generated op_proto stubs with hand-written implementations
+#   4. Build object libraries (tiling, opapi, proto) separately
+#   5. Package everything into an NPU vendor operator package via npu_op_package
+#   6. Build Ascend C kernel sources via npu_op_kernel_library
+#
+# OPERATOR NAME VARIANTS:
+#   PascalCase   : EuclideanNorm      (used in OP_TYPE, class names, package_name)
+#   snake_case   : euclidean_norm     (used in filenames, function names, namespaces)
+#   UPPER_SNAKE  : EUCLIDEAN_NORM     (used in header guards, TPL macros)
+#   camelCase    : euclideanNorm      (unused in this package, shown for completeness)
+# =============================================================================
+
+cmake_minimum_required(VERSION 3.16.0)
+project(custom_op_prj)
+
+# find_package(ASC REQUIRED) loads the CANN ASC CMake module,
+# which provides macros: npu_op_package, npu_op_library, npu_op_kernel_sources, etc.
+find_package(ASC REQUIRED)
+
+# Target hardware compute unit. 'ascend950' targets the Ascend 950 series NPU.
+set(ASCEND_COMPUTE_UNIT ascend950)
+
+# Package name in PascalCase. This must match the OP_TYPE registered in code.
+set(package_name EuclideanNorm)
+
+# CANN installation root. Contains headers, libraries, tools, and opp files.
+# For a new environment, update this to the actual CANN installation path.
+set(CANN_HOME /home/developer/Ascend/cann-9.1.0)
+set(CANN_INC ${CANN_HOME}/include)
+set(CANN_ARCH_INC ${CANN_HOME}/x86_64-linux/include)
+set(CANN_LIB ${CANN_HOME}/lib64)
+
+# Auto-generated files directory. op_build writes generated stubs here.
+set(AUTO_GEN_DIR ${CMAKE_BINARY_DIR}/autogen)
+
+# -----------------------------------------------------------------------------
+# Additional include paths required by EuclideanNorm (reduce-class operator):
+#   - op_common / op_common/op_host: CANN shared op utilities (log, infershape
+#     reduce util, shape/math/platform util).
+# -----------------------------------------------------------------------------
+set(CANN_OP_COMMON_INC ${CANN_ARCH_INC}/op_common)
+set(CANN_OP_COMMON_HOST_INC ${CANN_ARCH_INC}/op_common/op_host)
+
+# =============================================================================
+# SOURCE FILE COLLECTION
+# =============================================================================
+
+# host_tiling_srcs: Host-side tiling, shape inference, and operator definition.
+# These are compiled into libascend_all_ops.so for op_build consumption.
+# NOTE: euclidean_norm_infershape.cpp registers InferShape (and the axes
+#   value-dependency) via IMPL_OP_INFERSHAPE;
+file(GLOB host_tiling_srcs
+    op_host/euclidean_norm_def.cpp
+    op_host/euclidean_norm_infershape.cpp
+    op_host/arch35/euclidean_norm_tiling_arch35.cpp
+)
+
+# host_graph_srcs: Graph-side inference registration (InferDataType) sources.
+# Used by the graph engine (GE) at graph build time.  These sources are
+# compiled into cust_proto_obj (see STEP 4 proto_srcs).
+file(GLOB host_graph_srcs
+    op_graph/euclidean_norm_graph_infer.cpp
+)
+
+# opapi_srcs: ACLNN (Ascend C Library Neural Network) API sources.
+# Uses the op_build-generated stub at ${AUTO_GEN_DIR}/aclnn_euclidean_norm.cpp
+#   which implements aclnnEuclideanNormGetWorkspaceSize / aclnnEuclideanNorm via
+#   the Nnopbase* framework (no hand-written L0 needed).
+set(opapi_srcs
+    ${AUTO_GEN_DIR}/aclnn_euclidean_norm.cpp
+)
+
+# =============================================================================
+# STEP 1: op_build — Auto-generates aic-*-ops-info.ini and stub files
+# =============================================================================
+file(MAKE_DIRECTORY ${AUTO_GEN_DIR})
+
+# Compiler flags for host-side shared library.
+set(HOST_OPS_CXX_FLAGS
+    -g -fPIC -shared -std=c++17 -D_GLIBCXX_USE_CXX11_ABI=0 -O0
+    -I ${CMAKE_CURRENT_SOURCE_DIR}
+    -I ${CMAKE_CURRENT_SOURCE_DIR}/op_kernel
+    -I ${CANN_INC}
+    -I ${CANN_ARCH_INC}
+    -I ${CANN_OP_COMMON_INC}
+    -I ${CANN_OP_COMMON_HOST_INC}
+    -I ${CANN_ARCH_INC}/pkg_inc
+    -I ${CANN_HOME}/x86_64-linux/pkg_inc/base
+    -D BUILD_SOC_VERSION=Ascend950
+)
+
+# Linker flags for host-side shared library.
+#   -lops_base: Ops::Base::* utilities (SetUnknownRank, IsUnknownRank, etc.)
+#     required by reduce-class operators.  Not needed by add_custom_package.
+set(HOST_OPS_LINK_FLAGS
+    -L ${CANN_LIB}
+    -lexe_graph -lregister -ltiling_api -lc_sec -lops_base
+    -Wl,-rpath,${CANN_LIB}
+)
+
+message(STATUS "Opbuild: compiling libascend_all_ops.so ...")
+execute_process(
+    COMMAND ${CMAKE_CXX_COMPILER} ${HOST_OPS_CXX_FLAGS}
+            ${host_tiling_srcs} ${host_graph_srcs}
+            ${HOST_OPS_LINK_FLAGS}
+            -o ${AUTO_GEN_DIR}/libascend_all_ops.so
+    RESULT_VARIABLE _build_ret
+    OUTPUT_VARIABLE _build_out
+    ERROR_VARIABLE  _build_err
+)
+if(NOT _build_ret EQUAL 0)
+    message(FATAL_ERROR "Failed to compile libascend_all_ops.so: ${_build_err}")
+endif()
+
+message(STATUS "Opbuild: running op_build ...")
+execute_process(
+    COMMAND
+        ${CMAKE_COMMAND} -E env
+            "OPS_PRODUCT_NAME=${ASCEND_COMPUTE_UNIT}"
+            "LD_LIBRARY_PATH=${CANN_LIB}:$ENV{LD_LIBRARY_PATH}"
+        ${CANN_HOME}/tools/opbuild/op_build
+            ${AUTO_GEN_DIR}/libascend_all_ops.so
+            ${AUTO_GEN_DIR}
+            "--compute_unit=${ASCEND_COMPUTE_UNIT}"
+    RESULT_VARIABLE _opb_ret
+    OUTPUT_VARIABLE _opb_out
+    ERROR_VARIABLE  _opb_err
+)
+if(NOT _opb_ret EQUAL 0)
+    message(FATAL_ERROR "op_build failed: ${_opb_err}")
+endif()
+message(STATUS "Opbuild done.")
+
+# =============================================================================
+# STEP 2: Overwrite auto-generated op_proto header with hand-written declaration
+# (REG_OP lives in the header; the auto-generated op_proto.cc consumes it,
+#  so no hand-written proto.cc translation unit is needed)
+# =============================================================================
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/op_graph/euclidean_norm_proto.h
+    ${AUTO_GEN_DIR}/op_proto.h
+    COPYONLY
+)
+
+# =============================================================================
+# STEP 3: Set global properties for npu_op_library macros
+# =============================================================================
+set_property(GLOBAL PROPERTY ASCENDC_AUTO_GEN_PATH ${AUTO_GEN_DIR})
+set_property(GLOBAL PROPERTY _ASC_PKG_${package_name}_CODE_GEN_DIRS ${AUTO_GEN_DIR})
+
+# =============================================================================
+# STEP 4: Object libraries for separate compilation
+# =============================================================================
+
+# cust_optiling_obj: Tiling object library.
+# Contains host tiling sources.
+add_library(cust_optiling_obj OBJECT ${host_tiling_srcs})
+target_include_directories(cust_optiling_obj PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}
+    ${CMAKE_CURRENT_SOURCE_DIR}/op_kernel
+    ${CANN_INC}
+    ${CANN_ARCH_INC}
+    ${CANN_OP_COMMON_INC}
+    ${CANN_OP_COMMON_HOST_INC}
+    ${CANN_ARCH_INC}/pkg_inc
+    ${CANN_HOME}/x86_64-linux/pkg_inc/base
+)
+target_compile_options(cust_optiling_obj PRIVATE -fPIC)
+target_compile_definitions(cust_optiling_obj PRIVATE
+    BUILD_SOC_VERSION=Ascend950
+    OP_TILING_LIB
+    _GLIBCXX_USE_CXX11_ABI=0
+)
+
+# cust_opapi_obj: Operator API object library.
+add_library(cust_opapi_obj OBJECT ${opapi_srcs})
+target_include_directories(cust_opapi_obj PRIVATE
+    ${AUTO_GEN_DIR}
+    ${CANN_HOME}/include/aclnn
+    ${CANN_INC}
+    ${CANN_ARCH_INC}
+    ${CANN_ARCH_INC}/aclnn
+    ${CANN_ARCH_INC}/aclnnop
+    ${CANN_HOME}/x86_64-linux/pkg_inc/aicpu
+)
+target_compile_options(cust_opapi_obj PRIVATE -fPIC)
+target_compile_definitions(cust_opapi_obj PRIVATE
+    _GLIBCXX_USE_CXX11_ABI=0
+)
+
+# cust_proto_obj: Graph proto object library.
+# Compiles host_tiling_srcs + host_graph_srcs (euclidean_norm_graph_infer.cpp's
+# InferDataType registration lives here via host_graph_srcs).
+set(proto_srcs ${host_tiling_srcs} ${host_graph_srcs})
+add_library(cust_proto_obj OBJECT ${proto_srcs})
+target_include_directories(cust_proto_obj PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}
+    ${CMAKE_CURRENT_SOURCE_DIR}/op_kernel
+    ${CANN_INC}
+    ${CANN_ARCH_INC}
+    ${CANN_OP_COMMON_INC}
+    ${CANN_OP_COMMON_HOST_INC}
+    ${CANN_ARCH_INC}/pkg_inc
+    ${CANN_HOME}/x86_64-linux/pkg_inc/base
+)
+target_compile_options(cust_proto_obj PRIVATE -fPIC)
+target_compile_definitions(cust_proto_obj PRIVATE
+    _GLIBCXX_USE_CXX11_ABI=0
+)
+
+# =============================================================================
+# STEP 5: Vendor packaging via npu_op_package and npu_op_library
+# =============================================================================
+npu_op_package(${package_name}
+    TYPE RUN
+    CONFIG
+        INSTALL_PATH ${CMAKE_BINARY_DIR}
+)
+
+npu_op_library(cust_optiling TILING)
+target_sources(cust_optiling PUBLIC $<TARGET_OBJECTS:cust_optiling_obj>)
+# ops_base: provides Ops::Base::SetUnknownRank etc. used by infershape code
+# (compiled into host_tiling_srcs).  Not needed by add_custom_package.
+target_link_directories(cust_optiling PUBLIC ${CANN_LIB})
+target_link_libraries(cust_optiling PUBLIC ops_base)
+
+npu_op_library(cust_opapi ACLNN)
+target_sources(cust_opapi PUBLIC $<TARGET_OBJECTS:cust_opapi_obj>)
+target_include_directories(cust_opapi PRIVATE
+    ${CANN_HOME}/include/aclnn
+)
+target_link_directories(cust_opapi PUBLIC ${CANN_LIB})
+target_link_libraries(cust_opapi PUBLIC opapi)
+
+npu_op_library(cust_op_proto GRAPH)
+target_sources(cust_op_proto PUBLIC $<TARGET_OBJECTS:cust_proto_obj>)
+target_link_directories(cust_op_proto PUBLIC ${CANN_LIB})
+target_link_libraries(cust_op_proto PUBLIC ops_base)
+
+npu_op_package_add(${package_name}
+    LIBRARY
+        cust_optiling
+        cust_opapi
+        cust_op_proto
+)
+
+# =============================================================================
+# STEP 6: Kernel compilation
+# =============================================================================
+npu_op_kernel_sources(ascendc_kernels
+    OP_TYPE EuclideanNorm
+    KERNEL_DIR op_kernel
+    KERNEL_FILE arch35/euclidean_norm_apt.cpp
+)
+
+npu_op_kernel_library(ascendc_kernels
+    SRC_BASE ${CMAKE_CURRENT_SOURCE_DIR}
+    TILING_LIBRARY cust_optiling
+)
+
+# Kernel-side include path for shared ascendc common headers (platform_util.h).
+# These headers live in the OPP built-in implementation tree and are not in the
+# kernel compiler's default system include paths.  Required by reduce-class
+# operators that use Ops::Base device utilities.
+npu_op_kernel_options(ascendc_kernels ALL OPTIONS
+    -I$ENV{ASCEND_OPP_PATH}/built-in/op_impl/ai_core/tbe/impl/ops_nn/ascendc/common)
+
+npu_op_package_add(${package_name}
+    LIBRARY
+        ascendc_kernels
+)