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

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/knowledge/patterns/regbase_kernel_dataflow_patterns.md

@@ -0,0 +1,164 @@
+---
+title: Regbase Kernel Dataflow Patterns
+purpose: Explain the three-layer regbase structure: outer kernel shell, UB-level CopyIn/Compute/CopyOut flow, and VF/reg-compute body.
+read_when:
+  - You are structuring a new regbase kernel or reading an existing reference implementation.
+  - The task needs a clear separation between shell logic, UB staging, and VF micro-instructions.
+not_for:
+  - Host runtime setup only
+  - Pure precision debugging
+keywords:
+  - dataflow
+  - copyin compute copyout
+  - VF
+  - reg compute
+next_reads:
+  - regbase_buffer_partitioning.md
+  - regbase_sync_patterns.md
+  - ../api/regbase_api_whitelist.md
+depth: foundation
+topic_type: pattern
+---
+
+# Regbase Kernel Dataflow Patterns
+
+This note explains the most important structural pattern in regbase work: the outer kernel shell, the UB-level tile flow, and the inner VF/reg-compute body are different layers and should be designed separately.
+
+## 1. The Three Working Layers
+
+For kernel-side implementation, read the operator in three layers:
+
+1. **Kernel shell**
+   - `__global__` entry
+   - `TILING_KEY_IS(...)`
+   - `TPipe`
+   - `Init` / `Process`
+2. **UB tile flow**
+   - `CopyIn -> Compute -> CopyOut`
+   - `GlobalTensor`, `LocalTensor`, `TQue`
+3. **VF body**
+   - `__VEC_SCOPE__`
+   - `RegTensor`
+   - `MaskReg`
+   - `Reg::*` / `MicroAPI::*` VF-safe loads such as `DataCopy<..., LoadDist::...>`
+   - arithmetic / compare / cast / select
+   - `Reg::*` / `MicroAPI::*` VF-safe stores such as `DataCopy<..., StoreDist::...>`
+
+Do not flatten these three layers into one description. The outer shell organizes work; the VF body performs the core register math.
+
+## 2. Minimal Outer-Shell Pattern
+
+```cpp
+extern "C" __global__ __aicore__ void op_entry(GM_ADDR x, GM_ADDR y, GM_ADDR workspace, GM_ADDR tiling)
+{
+    REGISTER_TILING_DEFAULT(TilingData);
+    GET_TILING_DATA_WITH_STRUCT(TilingData, tilingData, tiling);
+
+    TPipe pipe;
+    if (TILING_KEY_IS(101UL)) {
+        KernelOp op;
+        op.Init(x, y, workspace, &tilingData, &pipe);
+        op.Process();
+    }
+}
+```
+
+Reference shape:
+
+- a small unary regbase outer-shell implementation with one clear `TILING_KEY_IS(...)` branch and one compact `Init -> Process` flow
+
+## 3. Minimal UB-Level Flow Pattern
+
+```cpp
+__aicore__ inline void Process()
+{
+    for (uint32_t i = 0; i < tileNum_; i++) {
+        uint32_t count = (i == tileNum_ - 1) ? tailTileElementNum_ : TILE_LENGTH;
+        CopyIn(i, count);
+        Compute(count);
+        CopyOut(i, count);
+    }
+}
+```
+
+This level decides:
+
+- how the tile loop runs
+- where the tail is handled
+- where UB-stage ownership changes
+
+It does not yet explain the register math.
+
+## 4. Minimal VF Body Pattern
+
+```cpp
+__VEC_SCOPE__
+{
+    RegTensor<float> vin, vtmp, vout;
+    MaskReg mask;
+
+    for (uint16_t i = 0; i < vfLoopNum; i++) {
+        mask = UpdateMask<float>(size);
+        DataCopy<float, LoadDist::DIST_NORM>(vin, inAddr + i * VL);
+        Exp(vtmp, vin, mask);
+        Adds(vtmp, vtmp, 1.0f, mask);
+        Div(vout, vin, vtmp, mask);
+        DataCopy<float, StoreDist::DIST_NORM_B32>(outAddr + i * VL, vout, mask);
+    }
+}
+```
+
+Here:
+
+- `inAddr` and `outAddr` are UB addresses
+- load/store instructions move data between UB and register objects
+- the actual math stays register-centric
+
+Reference patterns:
+
+- a small regbase body that clearly separates UB staging from VF math
+- a fused register-chain implementation that is useful for studying VF composition, but not as a full outer-shell starter
+
+## 5. Dtype-Split Pattern
+
+A stable regbase pattern is to keep the outer shell mostly unchanged while splitting the VF body by dtype.
+
+Typical split:
+
+- fp32 path: direct load and compute
+- fp16 / bf16 path:
+  - load packed narrow type
+  - unpack or cast to fp32 register state
+  - compute in fp32 if needed
+  - cast back and pack for store
+
+This keeps routing visible and avoids mixing dtype-specific casts into the host packet.
+
+## 6. When The Pattern Needs To Grow
+
+The simple three-layer pattern is enough for:
+
+- unary activation
+- binary math
+- short fused chains
+- many light cast/compare/select tasks
+
+The pattern needs explicit extension when:
+
+- multiple source tiles are synchronized manually
+- MTE/vector overlap is manually orchestrated with flags
+- the operator has a strong reduction or transpose component
+- cross-core coordination becomes part of the design
+
+At that point, keep the same layers, but add the advanced sync and buffer rules from:
+
+- [[regbase_sync_patterns]]
+- [[regbase_buffer_partitioning]]
+
+## Related Documents
+
+- [[../regbase_development_guide]]
+- [[regbase_buffer_partitioning]]
+- [[regbase_sync_patterns]]
+- [[regbase_operator_patterns]]
+- [[../api/regbase_api_whitelist]]

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/knowledge/patterns/regbase_operator_patterns.md

@@ -0,0 +1,138 @@
+---
+name: regbase_operator_patterns
+description: Ascend950 regbase-first 直调算子的核心结构模式，覆盖 VF / Reg-MicroAPI 计算链、参考实现借鉴边界、规约后处理和 membase 兼容边界。
+title: Regbase Operator Patterns
+purpose: Choose the overall regbase kernel shape, fusion boundary, and greenfield-vs-reference route before line-level coding.
+read_when:
+  - The task is already in the regbase branch and needs a first design route.
+  - You need to decide how much structure can be borrowed from an existing operator and what must stay greenfield.
+not_for:
+  - Detailed sync or build questions
+  - Exact API signatures
+keywords:
+  - regbase operator
+  - kernel shape
+  - fusion boundary
+  - reference reuse
+next_reads:
+  - ../regbase_development_guide.md
+  - regbase_kernel_dataflow_patterns.md
+  - ../dev-experience/regbase_kernel_case_notes.md
+depth: foundation
+topic_type: pattern
+type: knowledge_card
+platform: 950-regbase
+verified: false
+patterns: [operator, regbase, microapi_chain, fusion, direct_invoke]
+---
+
+# Ascend950 Regbase Operator Patterns
+
+This file is the canonical `patterns/` home for regbase operator patterns. Use it when the target implementation uses `regbase` and you need to decide the kernel shape before coding.
+
+## Applicability
+
+- Platform: `ascend950`
+- Branch: `regbase`
+- Scope: direct-invoke, single-project kernel work
+- Reuse rule: a candidate reference operator is optional; if none fits, keep the task in the regbase branch and design greenfield
+
+## Core Route
+
+1. Lock the math and dataflow first: pure elementwise, reduction plus post-process, broadcasted elementwise, or mixed fusion.
+2. Decide whether there is a useful existing implementation to inspect. If there is, adapt only the reusable structure; if not, stay greenfield and record the reuse boundary explicitly.
+3. Choose the tiling and branch form before final API selection.
+4. Keep regbase-specific compute chains in `__VEC_SCOPE__` whenever the intermediate state is small and stable enough.
+
+## Pattern 1: Single-Scope VF / Reg-MicroAPI Chain
+
+Best for short elementwise or post-process chains such as:
+
+- `cast -> muls -> add`
+- `mul -> add -> relu`
+- `sub(max) -> exp -> reciprocal`
+
+Design guidance:
+
+- Prefer one `__VEC_SCOPE__` for the hot path when the chain is linear and intermediate reuse is local.
+- Delay write-back until the chain has produced a stable output, instead of bouncing temporary values through extra storage.
+- Check API availability in `../api/index.md` before assuming a VF / Reg-MicroAPI chain is legal.
+
+## Pattern 2: Load Once, Compute Many
+
+Use this when one input tile can support several dependent operations after a single load:
+
+- reduction followed by normalization or scale/bias
+- elementwise preconditioning before a reduction
+- multi-output accumulation derived from the same loaded tile
+
+Design guidance:
+
+- Treat the load boundary as expensive and the reg/UB compute chain as cheap.
+- Keep the tile alive across consecutive operations when this removes duplicate GM traffic.
+- Split the design only when live buffers, temporary state, or precision constraints force it.
+
+## Pattern 3: Reduction Summary Plus Post-Process
+
+Common regbase fusion shape:
+
+1. Reduce a tile or row group into summary statistics.
+2. Keep the summary in fp32 if the chain is precision-sensitive.
+3. Apply the post-process immediately while the summary is still local.
+
+Typical cases:
+
+- RMSNorm / LayerNorm local phases
+- Softmax local max-sum-normalize chain
+- sum or max followed by broadcasted correction
+
+Use [[reduction_patterns]] for the reduction route and [Precision Guide](../pitfalls/precision_guide.md) to decide when the post-process must stay in fp32.
+
+## Pattern 4: Verified Reference Adaptation
+
+When a useful existing reference implementation exists:
+
+- reuse only the branch shape, tiling form, and proven control structure
+- record what was reused, what changed, and what must be rewritten
+- keep regbase API and dataflow decisions primary even if the reference came from an adjacent implementation family
+
+When no useful reference implementation exists:
+
+- do not invent reuse
+- stay in the regbase branch
+- use this patterns subtree plus `../../reference-ops/open_source_operator_table.md` only as reference-reading context
+
+## Pattern 5: Membase Compatibility Boundary
+
+`ascend910b / membase` remains a compatibility context, but this document is not a membase design guide.
+
+When a design starts leaning on:
+
+- `TPipe`
+- `TQue`
+- `DataCopyPad` as the central execution model
+- membase-style queue choreography
+
+then the task is no longer choosing a regbase pattern. At that point:
+
+- stop importing membase habits into the regbase design
+- re-check whether the branch or platform assumption is wrong
+- fall back to the local regbase references first: `../api/index.md`, `tiling_patterns.md`, and `../pitfalls/regbase_vs_membase_confusions.md`
+
+## Design Checklist
+
+- Is the kernel primarily a VF / Reg-MicroAPI chain, a reduction chain, a broadcast chain, or a hybrid?
+- Is the load boundary minimal, or are we reloading data that could stay local?
+- Is any claimed reuse backed by an inspected reference implementation?
+- Are fp32 summaries kept long enough for numerically sensitive post-processing?
+- Are membase-only habits leaking into the regbase design?
+
+## Related Documents
+
+- [[tiling_patterns]]
+- [[reduction_patterns]]
+- [[broadcast_patterns]]
+- [[kernel_design_patterns]]
+- [Precision Guide](../pitfalls/precision_guide.md)
+- [[../api/index]]
+- [[../../reference-ops/open_source_operator_table]]

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/knowledge/patterns/regbase_sync_patterns.md

@@ -0,0 +1,113 @@
+---
+title: Regbase Sync Patterns
+purpose: Choose synchronization by layer so UB handoff, VF lane control, and overlap logic are not mixed into one model.
+read_when:
+  - You need to reason about queue handoff, VF lane control, or explicit overlap flags.
+  - Failures look like synchronization bugs but the layer is still unclear.
+not_for:
+  - Operator classification
+  - Pure build-time problems
+keywords:
+  - synchronization
+  - queue handoff
+  - VF lane control
+  - SetFlag
+next_reads:
+  - ../api/regbase_api_sync.md
+  - regbase_kernel_dataflow_patterns.md
+  - regbase_buffer_partitioning.md
+depth: intermediate
+topic_type: pattern
+---
+
+# Regbase Sync Patterns
+
+This note explains synchronization by layer. The most common mistake is to use one sync model for every layer of the kernel.
+
+## 1. Default Rule
+
+Start with the lightest synchronization model that matches the layer you are working in.
+
+In many regbase operators:
+
+- UB stage handoff is handled by queue lifecycle or straightforward stage ordering
+- VF internals need lane control, not event synchronization
+- explicit `SetFlag` / `WaitFlag` only appear in more advanced overlap or ping-pong designs
+
+## 2. UB-Level Stage Handoff
+
+When the outer shell uses queue-based staging, the local readiness model is:
+
+- `EnQue`: a UB tile is ready for the next stage
+- `DeQue`: the next stage can consume the UB tile
+
+This is stage coordination for local pipeline flow. It is not the same thing as VF lane control.
+
+Use this level to reason about:
+
+- whether `CopyIn` has finished preparing the UB tile
+- whether `Compute` is done with the current UB tile
+- whether `CopyOut` can consume the finished UB tile
+
+## 3. VF-Level “Synchronization” Is Usually Not Event Sync
+
+Inside `__VEC_SCOPE__`:
+
+- `MaskReg` controls active lanes
+- `LoadDist` controls how UB data is loaded into registers
+- `StoreDist` controls how register results are written back
+
+None of those are event synchronization primitives.
+
+That means:
+
+- do not describe `MaskReg` as a sync mechanism
+- do not use `LoadDist` / `StoreDist` as if they were barriers
+- do not add `PipeBarrier` just because a VF loop has multiple instructions
+
+## 4. Explicit Event Flags Belong To Advanced Overlap Patterns
+
+Use `SetFlag` / `WaitFlag` when the design truly overlaps movement and compute manually and the reference implementation already uses that pattern.
+
+Representative pattern:
+
+```cpp
+SetFlag<HardEvent::V_MTE2>(pingPongID);
+WaitFlag<HardEvent::V_MTE2>(pingPongID);
+SetFlag<HardEvent::MTE2_V>(pingPongID);
+WaitFlag<HardEvent::MTE2_V>(pingPongID);
+```
+
+This style appears in advanced transformer kernels where multiple UB slices, ping-pong buffers, and MTE/vector overlap are orchestrated explicitly.
+
+Reference shape:
+
+- a multi-slice or ping-pong implementation that already proves explicit overlap is required
+
+Do not import this pattern into a light unary or short fused chain unless the operator really needs it.
+
+## 5. Cross-Core Flags Are A Separate Layer
+
+`CrossCoreSetFlag` and `CrossCoreWaitFlag` belong to true inter-core coordination.
+
+Use them only when:
+
+- one core depends on another core’s progress
+- the kernel design explicitly spans cross-core producer/consumer relationships
+
+Do not use them to patch a local UB ordering issue.
+
+## 6. Practical Decision Path
+
+1. Ask whether the issue is local stage readiness, VF lane control, explicit overlap, or cross-core coordination.
+2. For local stage readiness, start from queue lifecycle or stable stage ordering.
+3. For VF internals, use `MaskReg` and correct `LoadDist` / `StoreDist` semantics, not barriers.
+4. For explicit overlap, verify an existing regbase reference before introducing `SetFlag` / `WaitFlag`.
+5. For cross-core logic, only then consider cross-core flags.
+
+## Related Documents
+
+- [[../regbase_development_guide]]
+- [[regbase_kernel_dataflow_patterns]]
+- [[regbase_buffer_partitioning]]
+- [[../api/regbase_api_sync]]

package/assets/ops-direct-invoke/skills/ops-design-paradigms/references/knowledge/patterns/tiling_input_validation.md

@@ -0,0 +1,267 @@
+---
+name: tiling_input_validation
+description: Tiling 入口异常值校验模式，覆盖 dtype/format/维度/attr/shape 五类校验，适用于所有范式。
+title: Tiling Input Validation Patterns
+purpose: Provide reusable validation functions that reject illegal inputs at tiling entry, before FindSplitAxis.
+read_when:
+  - The tiling function needs to reject unsupported dtype, format, or dimension.
+  - The operator has attrs that require value-range checking.
+  - The operator needs shape consistency or broadcast compatibility validation.
+  - L2 exception test cases need a corresponding tiling-side rejection path.
+not_for:
+  - Kernel-side runtime validation (this is host-side tiling only)
+  - API constraint lookup (use api/ subtree instead)
+keywords:
+  - validation
+  - dtype check
+  - format check
+  - dimension check
+  - attr range
+  - shape consistency
+  - exception
+  - L2
+next_reads:
+  - tiling_patterns.md
+  - regbase_operator_patterns.md
+  - ../dev-experience/tiling_review_notes.md
+depth: foundation
+topic_type: pattern
+type: knowledge_card
+platform: common
+verified: false
+patterns: [validation, dtype, format, dimension, attr, shape]
+---
+
+# Tiling Input Validation Patterns
+
+> 异常值校验是 Tiling 入口的硬门禁，在输入预处理（如 `PadAndSqueeze`）之后、`FindSplitAxis` 之前执行。
+> 每个校验函数返回 `bool`，通过 `OP_CHECK_IF` 拦截不合法输入并返回 `GRAPH_FAILED`。
+>
+> **校验顺序**：dtype → format → 维度上限 → attr 值域 → shape（broadcast 兼容 or 一致性）。
+>
+> **GEIR cast 说明**：GEIR 图通路中编译器可能插入 Cast 节点将 dtype 转换为算子支持的类型。
+> Tiling 函数从 `TilingContext` 获取的 dtype **已经是 cast 后的结果**，必定落入 spec.yaml
+> §2.2 支持列表——因此 tiling 侧只需校验入口实际 dtype 是否在支持列表中，不需要额外容忍
+> 未 cast 的中间 dtype。
+
+
+## 1. 数据类型校验
+
+每个输入有独立的 dtype 支持范围（来自 spec.yaml §2.2，按 input 逐行列出）。
+
+```c++
+bool CheckDtypeSupport(
+    gert::TilingContext* ctx, int64_t numInputs,
+    const std::vector<std::set<ge::DataType>>& supportedDtypesPerInput)
+{
+    for (int64_t i = 0; i < numInputs; i++) {
+        auto desc = ctx->GetInputDesc(i);
+        OP_CHECK_NULL_WITH_CONTEXT(ctx, desc);
+        ge::DataType dt = desc->GetDataType();
+        if (supportedDtypesPerInput[i].find(dt) == supportedDtypesPerInput[i].end()) {
+            OP_LOGE_FOR_INVALID_DTYPE_WITH_REASON(ctx->GetNodeName(), "input[" + std::to_string(i) + "]",
+                                                      ge::TypeUtils::DataTypeToSerialString(dt).c_str(),
+                                                      "dtype not in the supported list");
+            return false;
+        }
+    }
+    return true;
+}
+```
+
+## 2. 数据格式校验
+
+校验每个 input/output 的 format 在算子支持列表中。
+
+> **CANN API 注意**：`CompileTimeTensorDesc::GetFormat()` 返回 `const StorageFormat&`，
+> 不是 `ge::Format`。需用 `GetStorageFormat()` 取运行时 format，或 `GetOriginFormat()`
+> 取原始 format。Tiling 侧校验运行时 format 即可。
+
+```c++
+bool CheckFormatSupport(
+    gert::TilingContext* ctx, int64_t numInputs, int64_t numOutputs,
+    const std::set<ge::Format>& supportedFormats)
+{
+    for (int64_t i = 0; i < numInputs; i++) {
+        auto desc = ctx->GetInputDesc(i);
+        OP_CHECK_NULL_WITH_CONTEXT(ctx, desc);
+        ge::Format fmt = desc->GetStorageFormat();
+        if (supportedFormats.find(fmt) == supportedFormats.end()) {
+            OP_LOGE_FOR_INVALID_FORMAT_WITH_REASON(ctx->GetNodeName(), "input",
+                ("[" + std::to_string(i) + "] " + ge::TypeUtils::FormatToSerialString(fmt)).c_str(),
+                "format not in the supported list");
+            return false;
+        }
+    }
+    for (int64_t i = 0; i < numOutputs; i++) {
+        auto desc = ctx->GetOutputDesc(i);
+        OP_CHECK_NULL_WITH_CONTEXT(ctx, desc);
+        ge::Format fmt = desc->GetStorageFormat();
+        if (supportedFormats.find(fmt) == supportedFormats.end()) {
+            OP_LOGE_FOR_INVALID_FORMAT_WITH_REASON(ctx->GetNodeName(), "output",
+                ("[" + std::to_string(i) + "] " + ge::TypeUtils::FormatToSerialString(fmt)).c_str(),
+                "format not in the supported list");
+            return false;
+        }
+    }
+    return true;
+}
+```
+
+## 3. 超出维度的 tensor 校验
+
+校验每个 input/output 的 rank 不超过 `maxRank`（与 TilingKey 模板划分一致，Broadcast 范式 `maxRank=8`）。
+
+```c++
+bool CheckMaxDimensions(
+    const std::vector<std::vector<int64_t>>& inputShapes,
+    const std::vector<std::vector<int64_t>>& outputShapes,
+    int64_t maxRank)
+{
+    for (size_t i = 0; i < inputShapes.size(); i++) {
+        if ((int64_t)inputShapes[i].size() > maxRank) {
+            OP_LOGE_FOR_INVALID_SHAPEDIM_WITH_REASON("CheckMaxDimensions", "input",
+                ("[" + std::to_string(i) + "] rank " + std::to_string(inputShapes[i].size())).c_str(),
+                ("rank must not exceed " + std::to_string(maxRank)).c_str());
+            return false;
+        }
+    }
+    for (size_t i = 0; i < outputShapes.size(); i++) {
+        if ((int64_t)outputShapes[i].size() > maxRank) {
+            OP_LOGE_FOR_INVALID_SHAPEDIM_WITH_REASON("CheckMaxDimensions", "output",
+                ("[" + std::to_string(i) + "] rank " + std::to_string(outputShapes[i].size())).c_str(),
+                ("rank must not exceed " + std::to_string(maxRank)).c_str());
+            return false;
+        }
+    }
+    return true;
+}
+```
+
+## 4. 算子属性字段值域校验
+
+按算子 DESIGN §2.1 定义的 attr 取值范围逐 attr 校验。有 attr 的算子（如 `lp_norm_v2` 的 `p`/`axes`/`keepdim`）必须实现；无 attr 的算子（如 `adam`/`xdivy`）跳过。
+
+以下为 int 型 attr 的参考实现（bool/float 型同理，替换 getter 为 `GetBool`/`GetFloat`）：
+
+```c++
+struct AttrRange {
+    const char* name;
+    int64_t     index;
+    int64_t     defaultVal;
+    int64_t     minVal;
+    int64_t     maxVal;
+};
+
+bool CheckAttrValueRange(
+    gert::TilingContext* ctx,
+    const std::vector<AttrRange>& intAttrRanges)
+{
+    auto attrs = ctx->GetAttrs();
+    OP_CHECK_NULL_WITH_CONTEXT(ctx, attrs);
+    for (const auto& r : intAttrRanges) {
+        const int64_t* p = attrs->GetInt(r.index);
+        int64_t val = (p != nullptr) ? *p : r.defaultVal;
+        if (val < r.minVal || val > r.maxVal) {
+            OP_LOGE_FOR_INVALID_VALUE_WITH_REASON(ctx->GetNodeName(), r.name,
+                std::to_string((long)val).c_str(),
+                ("value must be in range [" + std::to_string(r.minVal) + ", " + std::to_string(r.maxVal) + "]").c_str());
+            return false;
+        }
+    }
+    return true;
+}
+```
+
+枚举型 attr（如 `reduction` 取值 `{0,1,2}`）可改用 `std::vector<int64_t> enumValues` + `std::find` 校验。
+
+## 5. shape 一致性校验
+
+**非 broadcast 算子**（输入 shape 必须完全一致）使用此函数替代 `CheckBroadcastShape`。
+**Broadcast 算子**两者都保留：先 `CheckShapeConsistency`（若通过则无需广播），再 `CheckBroadcastShape`（处理需要广播的情况）。
+
+```c++
+bool CheckShapeConsistency(
+    const std::vector<std::vector<int64_t>>& inputShapes)
+{
+    if (inputShapes.size() < 2) return true;
+    const auto& ref = inputShapes[0];
+    for (size_t i = 1; i < inputShapes.size(); i++) {
+        if (inputShapes[i].size() != ref.size()) {
+            OP_LOGE_FOR_INVALID_SHAPEDIM_WITH_REASON("CheckShapeConsistency", "input",
+                ("[" + std::to_string(i) + "] rank " + std::to_string(inputShapes[i].size())).c_str(),
+                ("rank must equal input[0] rank " + std::to_string(ref.size())).c_str());
+            return false;
+        }
+        for (size_t d = 0; d < ref.size(); d++) {
+            if (inputShapes[i][d] != ref[d]) {
+                OP_LOGE_FOR_INVALID_SHAPES_WITH_REASON("CheckShapeConsistency", "input",
+                        ("[" + std::to_string(i) + "] dim[" + std::to_string(d) + "] " + std::to_string((long)inputShapes[i][d])).c_str(),
+                        ("dim must equal input[0] dim " + std::to_string((long)ref[d])).c_str());
+                return false;
+            }
+        }
+    }
+    return true;
+}
+```
+
+## 调用约定
+
+> **头文件**：使用 `ge::TypeUtils::DataTypeToSerialString` / `FormatToSerialString` 需 `#include "graph/utils/type_utils.h"`。
+
+在 `GetShapeInfo()` 中输入预处理（`PadAndSqueeze`）之后、`CheckBroadcastShape` 之前，按固定顺序调用：
+
+```c++
+// 算子支持的 dtype/format/maxRank — 来自 spec.yaml §2.2/§2.3 和 DESIGN §3.1
+static const std::set<ge::DataType> SUPPORTED_DTYPES  = {ge::DT_FLOAT16, ge::DT_BF16, ge::DT_FLOAT};
+static const std::set<ge::Format>   SUPPORTED_FORMATS = {ge::FORMAT_ND};
+constexpr int64_t MAX_RANK = 8;
+
+OP_CHECK_IF(
+    !CheckDtypeSupportAndCombination(ctx_, (int64_t)rawInputShapes_.size(), SUPPORTED_DTYPES),
+    OP_LOGE_FOR_INVALID_DTYPE_WITH_REASON(ctx_->GetNodeName(), "inputs", "unsupported", "dtype check failed"),
+    return ge::GRAPH_FAILED);
+
+OP_CHECK_IF(
+    !CheckFormatSupport(ctx_, (int64_t)rawInputShapes_.size(),
+                        (int64_t)rawOutputShapes_.size(), SUPPORTED_FORMATS),
+    OP_LOGE_FOR_INVALID_FORMAT_WITH_REASON(ctx_->GetNodeName(), "inputs/outputs", "unsupported", "format check failed"),
+    return ge::GRAPH_FAILED);
+
+OP_CHECK_IF(
+    !CheckMaxDimensions(rawInputShapes_, rawOutputShapes_, MAX_RANK),
+    OP_LOGE_FOR_INVALID_SHAPEDIM_WITH_REASON(ctx_->GetNodeName(), "inputs/outputs", "exceeded", "dimension check failed"),
+    return ge::GRAPH_FAILED);
+
+// attr 校验（若有 attr）:
+// OP_CHECK_IF(
+//     !CheckAttrValueRange(ctx_, {{...}}),
+//     OP_LOGE_FOR_INVALID_VALUE_WITH_REASON(ctx_->GetNodeName(), "attr", "out of range", "attr check failed"),
+//     return ge::GRAPH_FAILED);
+
+// shape 校验 — broadcast 型用 CheckBroadcastShape（范式特有）；
+//          非 broadcast 型用 CheckShapeConsistency。
+OP_CHECK_IF(
+    !CheckBroadcastShape(normalInputShapes_, normalOutputShapes_, rank_),
+    OP_LOGE_FOR_INVALID_SHAPES_WITH_REASON(ctx_->GetNodeName(), "input/output shapes",
+        "incompatible", "check broadcast shape failed, shapes must be broadcast-compatible"),
+    return ge::GRAPH_FAILED);
+```
+
+## Checklist
+
+- [ ] dtype 校验：不支持类型 + 组合一致性（≥2 输入时）
+- [ ] format 校验：输入 + 输出
+- [ ] 维度上限校验：输入 + 输出，maxRank 来自模板划分
+- [ ] attr 值域校验（若有 attr）：每个 attr 逐一校验
+- [ ] shape 校验：broadcast 型 → CheckBroadcastShape；非 broadcast 型 → CheckShapeConsistency
+- [ ] 校验顺序：dtype → format → 维度 → attr → shape
+- [ ] GEIR cast：tiling 侧只校验入口实际 dtype，不额外容忍未 cast 的 dtype
+
+## Related Documents
+
+- [[tiling_patterns]]
+- [[regbase_operator_patterns]]
+- [[../api/index]]
+- [[../dev-experience/tiling_review_notes]]