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

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/broadcast/example/xdivy_custom_package/CMakeLists.txt

@@ -0,0 +1,328 @@
+# -----------------------------------------------------------------------------------------------------------
+# 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.
+# -----------------------------------------------------------------------------------------------------------
+
+# =============================================================================
+# xdivy_custom_package/CMakeLists.txt
+# =============================================================================
+# Role: Top-level build script for the Xdivy vendor operator package.
+#        Orchestrates the full operator build pipeline from source compilation
+#        through op_build code generation, to final .run package archiving.
+#
+# Differences from add_custom_package/CMakeLists.txt:
+#   - Xdivy is a BROADCAST operator (2 inputs, broadcast-compatible shapes).
+#   - The kernel has a TPL parameter RANK (4 or 8) — two binary variants are
+#     produced automatically via ASCENDC_TPL_SEL in op_kernel/arch35/xdivy_struct.h.
+#   - Tiling uses IMPL_OP_OPTILING + TilingParse (not the simpler .SetTiling())
+#     because the tiling function needs platform info (core count + UB size)
+#     at compile time.
+#   - The kernel entry (xdivy.cpp) uses GET_TILING_DATA_WITH_STRUCT
+#     (not REGISTER_TILING_DEFAULT) because XdivyTilingData is a template.
+#   - Three dtypes supported: BF16, FLOAT16, FLOAT (vs add_custom's two).
+#
+# Contents:
+#   - CANN SDK path configuration (CANN_HOME, include/lib paths).
+#   - Source file grouping for tiling, graph, and API layers.
+#   - Step 1: Compile host-side sources into libascend_all_ops.so and run
+#     op_build to generate aic-*-ops-info.ini and autogen stub files.
+#   - Step 2: Overwrite op_build-generated stubs with hand-written
+#     implementations (op_proto.h). The auto-generated ACLNN stub is used
+#     as-is (no hand-written op_api layer needed).
+#   - Step 3/4: Build CMake OBJECT libraries (cust_optiling_obj, cust_opapi_obj,
+#     cust_proto_obj) for the tiling, API, and proto layers.
+#   - Step 5: Package all libraries into a vendor .run archive via
+#     npu_op_package / npu_op_library / npu_op_package_add.
+#   - Step 6: Compile the Ascend C device kernel sources via
+#     npu_op_kernel_sources / npu_op_kernel_library / npu_op_kernel_library.
+#
+# Operator name variants:
+#   - PascalCase:   Xdivy
+#   - snake_case:   xdivy
+#   - UPPER_SNAKE:  XDIVY
+#   - camelCase:    xdivy
+#
+# To create a new operator (e.g. FooBar), replace:
+#   Xdivy → FooBar
+#   xdivy → foo_bar
+#   XDIVY → FOO_BAR
+#   xdivy → fooBar
+#   package_name from "Xdivy" to "FooBar"
+# =============================================================================
+
+# --- Minimum CMake version required for OBJECT libraries and modern targets ---
+cmake_minimum_required(VERSION 3.16.0)
+
+# --- Project declaration ---
+project(custom_op_prj)
+
+# --- MUST come before any ASC macro/function usage: loads Ascend CMake helpers ---
+find_package(ASC REQUIRED)
+
+# --- Target Ascend compute unit (chip architecture identifier) ---
+set(ASCEND_COMPUTE_UNIT ascend950)
+
+# --- Vendor package name (PascalCase), used in npu_op_package and install paths ---
+set(package_name Xdivy)
+
+# =============================================================================
+# CANN SDK paths
+# =============================================================================
+# CANN_HOME: root of the CANN installation; change this when deploying on a
+# different machine or CANN version.  The same path is hardcoded in test
+# CMakeLists.txt files — keep them in sync when migrating.
+set(CANN_HOME /home/developer/Ascend/cann-9.1.0)
+
+# CANN_INC: base include directory (e.g. register/, exe_graph/, graph/).
+set(CANN_INC ${CANN_HOME}/include)
+
+# CANN_ARCH_INC: arch-specific include directory (e.g. aclnn/, acl/, ge/).
+set(CANN_ARCH_INC ${CANN_HOME}/x86_64-linux/include)
+
+# CANN_LIB: shared/static libraries directory.
+set(CANN_LIB ${CANN_HOME}/lib64)
+
+# AUTO_GEN_DIR: directory where op_build writes generated code.
+set(AUTO_GEN_DIR ${CMAKE_BINARY_DIR}/autogen)
+
+# =============================================================================
+# Source file grouping
+# =============================================================================
+
+# host_tiling_srcs: tiling-related host sources.
+#   xdivy_def.cpp          — OP_ADD(Xdivy) operator definition & AICore config.
+#   xdivy_infershape.cpp   — IMPL_OP_INFERSHAPE: broadcast output shape inference.
+#   xdivy_tiling_arch35.cpp — TilingFuncXdivy: broadcast multi-core tiling.
+file(GLOB host_tiling_srcs
+    op_host/xdivy_def.cpp
+    op_host/xdivy_infershape.cpp
+    op_host/arch35/xdivy_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).
+# NOTE: REG_OP(Xdivy) lives in op_graph/xdivy_proto.h; the auto-generated
+#   op_proto.cc consumes it, so no hand-written proto.cc translation unit
+#   is needed.
+file(GLOB host_graph_srcs
+    op_graph/xdivy_graph_infer.cpp
+)
+
+# opapi_srcs: ACLNN-level operator API sources.
+# Uses the op_build-generated stub at ${AUTO_GEN_DIR}/aclnn_xdivy.cpp
+#   which implements aclnnXdivyGetWorkspaceSize / aclnnXdivy via
+#   the Nnopbase* framework (no hand-written L0 needed).
+set(opapi_srcs
+    ${AUTO_GEN_DIR}/aclnn_xdivy.cpp
+)
+
+# =============================================================================
+# Step 1: op_build — generate aic-*-ops-info.ini and autogen stubs
+# =============================================================================
+# The CANN op_build tool takes a .so containing OP_ADD / IMPL_OP / REG_OP
+# registrations and emits:
+#   aic-<package>-ops-info.ini   — operator metadata (inputs/outputs, attrs).
+#   op_proto.h / op_proto.cc     — auto-generated proto stubs.
+#   aclnn_xdivy.h/.cpp           — auto-generated ACLNN API stubs (used as-is).
+# The op_proto.h stub is then *overwritten* in Step 2 with hand-written code.
+file(MAKE_DIRECTORY ${AUTO_GEN_DIR})
+
+# Compiler flags for the host-side .so that op_build reads.
+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_ARCH_INC}/pkg_inc
+    -D BUILD_SOC_VERSION=Ascend950
+)
+
+# Linker flags for the host-side .so.
+set(HOST_OPS_LINK_FLAGS
+    -L ${CANN_LIB}
+    -lexe_graph -lregister -ltiling_api -lc_sec
+    -Wl,-rpath,${CANN_LIB}
+)
+
+# Compile libascend_all_ops.so: aggregates all registration objects into one
+# shared library that op_build can introspect.
+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()
+
+# Run op_build: it introspects libascend_all_ops.so and writes generated files
+# into AUTO_GEN_DIR.  OPS_PRODUCT_NAME sets the chip name embedded in .ini.
+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 autogen stubs with hand-written implementations
+# =============================================================================
+
+# Overwrite op_proto.h: REG_OP(Xdivy) with INPUT/OUTPUT declarations.
+# (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/xdivy_proto.h
+    ${AUTO_GEN_DIR}/op_proto.h
+    COPYONLY
+)
+
+# =============================================================================
+# Step 3: Global properties for npu_op_library
+# =============================================================================
+
+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
+# =============================================================================
+
+# --- cust_optiling_obj: tiling-layer 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_ARCH_INC}/pkg_inc
+)
+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: ACLNN API-layer sources (op_build autogen stub) ---
+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: proto registration sources (tiling + graph infer) ---
+# Compiles host_tiling_srcs + host_graph_srcs (xdivy_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_ARCH_INC}/pkg_inc
+)
+target_compile_options(cust_proto_obj PRIVATE -fPIC)
+target_compile_definitions(cust_proto_obj PRIVATE
+    _GLIBCXX_USE_CXX11_ABI=0
+)
+
+# =============================================================================
+# Step 5: Vendor packaging (npu_op_package + npu_op_library + npu_op_package_add)
+# =============================================================================
+
+npu_op_package(${package_name}
+    TYPE RUN
+    CONFIG
+        INSTALL_PATH ${CMAKE_BINARY_DIR}
+)
+
+# --- cust_optiling: tiling shared library ---
+npu_op_library(cust_optiling TILING)
+target_sources(cust_optiling PUBLIC $<TARGET_OBJECTS:cust_optiling_obj>)
+
+# --- cust_opapi: ACLNN API shared library ---
+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)
+
+# --- cust_op_proto: graph proto shared library ---
+npu_op_library(cust_op_proto GRAPH)
+target_sources(cust_op_proto PUBLIC $<TARGET_OBJECTS:cust_proto_obj>)
+
+# npu_op_package_add: registers the three libraries inside the .run package.
+npu_op_package_add(${package_name}
+    LIBRARY
+        cust_optiling
+        cust_opapi
+        cust_op_proto
+)
+
+# =============================================================================
+# Step 6: Kernel — Ascend C device-side kernel compilation
+# =============================================================================
+
+# npu_op_kernel_sources: declares the device kernel source files.
+#   OP_TYPE Xdivy: binds these kernel sources to the Xdivy operator.
+#   KERNEL_DIR op_kernel: directory containing xdivy.cpp.
+#   KERNEL_FILE xdivy.cpp: the kernel implementation entry point.
+#
+# Note: the kernel template parameter RANK (4 or 8) is handled automatically
+# by the ASCENDC_TPL_SEL declaration in op_kernel/arch35/xdivy_struct.h — the
+# build system emits a separate kernel binary for each selection, and the
+# runtime dispatches to the right one based on SetTilingKey.
+npu_op_kernel_sources(ascendc_kernels
+    OP_TYPE Xdivy
+    KERNEL_DIR op_kernel
+    KERNEL_FILE xdivy.cpp
+)
+
+# npu_op_kernel_library: assembles compiled kernel objects into a kernel .so.
+npu_op_kernel_library(ascendc_kernels
+    SRC_BASE ${CMAKE_CURRENT_SOURCE_DIR}
+    TILING_LIBRARY cust_optiling
+)
+
+# Add the kernel library to the vendor package.
+npu_op_package_add(${package_name}
+    LIBRARY
+        ascendc_kernels
+)

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/broadcast/example/xdivy_custom_package/README.md

@@ -0,0 +1,163 @@
+# xdivy_custom_package
+
+Xdivy broadcast operator: element-wise `y = (x1 == 0) ? 0 : (x1 / x2)` with NumPy-style broadcasting. This package is the **broadcast operator reference template** — it extends `add_custom_package`'s minimal same-shape pattern with the additional machinery needed for broadcast support (broadcast shape inference, multi-axis tiling, TPL rank dispatch, register-fused VF).
+
+## Formula
+
+```
+out = x1 / x2   when x1 != 0
+out = 0         when x1 == 0
+```
+
+- Inputs: `x1` (dividend), `x2` (divisor) — broadcast-compatible shapes, dtypes `BF16 / FLOAT16 / FLOAT`.
+- Output: `y` — shape = `broadcastMax(x1.shape, x2.shape)`, same dtype as inputs.
+
+## Directory Structure
+
+```
+xdivy_custom_package/
+├── CMakeLists.txt          # Top-level build: compiles host so, runs op_build, packages kernel
+├── op_host/                # Host-side operator registration & tiling
+│   ├── xdivy_def.cpp              # OP_ADD(Xdivy): I/O signature, dtype, AICore config
+│   ├── xdivy_infershape.cpp       # IMPL_OP_INFERSHAPE: broadcast output shape inference
+│   └── arch35/                    # dav-3510 (Ascend950) specific
+│       ├── xdivy_tiling_arch35.h   # XdivyTiling class + helper declarations
+│       └── xdivy_tiling_arch35.cpp # TilingFuncXdivy: PadAndSqueeze→FindSplitAxis→MultiCoreSplit
+├── op_kernel/              # Device-side Ascend C kernel
+│   ├── xdivy.cpp                    # Kernel entry (templated __global__ __aicore__)
+│   └── arch35/                    # dav-3510 (Ascend950) specific
+│       ├── xdivy_tiling_struct.h   # XdivyTilingData<R> template (shared host + kernel)
+│       ├── xdivy_kernel.h          # XdivyKernel<T,RANK> class (broadcast NdDma + VF)
+│       └── xdivy_struct.h          # ASCENDC_TPL macros (RANK = 4 or 8 dispatch)
+├── op_graph/               # Graph Engine (GE) IR registration
+│   ├── xdivy_proto.h              # REG_OP(Xdivy): INPUT/OUTPUT declarations
+│   └── xdivy_graph_infer.cpp      # IMPL_OP(InferDataType): output dtype = input dtype
+└── tests/                  # Integration tests
+    ├── tiling/   # TilingFunc unit test (no device needed) — broadcast scenarios
+    ├── geir/     # GE graph compile + execute test — broadcast verification
+    └── aclnn/    # End-to-end ACLNN API test (autogen stub) — broadcast verification
+```
+
+## Key Concepts: Broadcast Operator vs. Element-wise
+
+| Aspect | add_custom (element-wise) | xdivy (broadcast) |
+|---|---|---|
+| Inputs | x, y (must be same shape) | x1, x2 (broadcast-compatible) |
+| Output shape | = input shape | = broadcastMax(x1, x2) |
+| InferShape | Copy x's shape | Compute broadcastMax(x1, x2) |
+| Tiling complexity | Single axis split (totalLength) | Multi-axis: PadAndSqueeze → FindSplitAxis → MultiCoreSplit |
+| Kernel addressing | Contiguous DataCopyPad | NdDma with broadcast strides |
+| Kernel TPL params | None | RANK ∈ {4, 8} (rank-dispatched binaries) |
+| Buffer count (P) | 3 (always) | 3 (FP32) or 4 (FP16/BF16 cast path) |
+| Compute | Add inline | Register-fused VF (Div→Compare→Select) |
+
+## Key Conventions for Agents
+
+### arch35 Directory (`op_host/arch35/`, `op_kernel/arch35/`)
+
+`arch35` = NpuArch `dav-3510` = SoC `Ascend950`. All arch-specific code goes under `arch35/`:
+
+| Directory | Purpose | Files |
+|---|---|---|
+| `op_host/arch35/` | Tiling (host-side) | `*_tiling_arch35.h`, `*_tiling_arch35.cpp` |
+| `op_kernel/arch35/` | Kernel (device-side) | `*_tiling_struct.h`, `*_kernel.h`, `*_struct.h` |
+
+Arch-agnostic files stay at the root of `op_host/` or `op_kernel/`:
+- `op_host/*_def.cpp`, `op_host/*_infershape.cpp`
+- `op_kernel/*.cpp` (kernel entry point — `KERNEL_FILE` in CMakeLists.txt)
+
+### File Naming Convention
+
+| Layer | Pattern | Example |
+|---|---|---|
+| Host def | `{snake}_def.cpp` | `xdivy_def.cpp` |
+| Host infershape | `{snake}_infershape.cpp` | `xdivy_infershape.cpp` |
+| Host tiling (arch35) | `arch35/{snake}_tiling_arch35.{h,cpp}` | `arch35/xdivy_tiling_arch35.cpp` |
+| Kernel entry | `{snake}.cpp` | `xdivy.cpp` |
+| Kernel class (arch35) | `arch35/{snake}_kernel.h` | `arch35/xdivy_kernel.h` |
+| Tiling struct (arch35) | `arch35/{snake}_tiling_struct.h` | `arch35/xdivy_tiling_struct.h` |
+| TPL struct (arch35) | `arch35/{snake}_struct.h` | `arch35/xdivy_struct.h` |
+| Graph | `{snake}_proto.h`, `{snake}_graph_infer.cpp` | `xdivy_proto.h`, `xdivy_graph_infer.cpp` |
+
+### CMakeLists.txt Key Points
+
+- `host_tiling_srcs` includes `op_host/arch35/*_tiling_arch35.cpp`
+- `opapi_srcs` uses the op_build-generated ACLNN stub (`${AUTO_GEN_DIR}/aclnn_xdivy.cpp`, Nnopbase framework) — no hand-written op_api layer
+- `KERNEL_FILE` points to the root-level `*.cpp` (not files under `arch35/`)
+- `KERNEL_DIR` is `op_kernel` (the Ascend C compiler resolves `arch35/` includes from there)
+- TPL kernel binary variants (RANK=4 and RANK=8) are produced automatically based on `ASCENDC_TPL_SEL` in `op_kernel/arch35/xdivy_struct.h`
+
+## Broadcast Tiling Pipeline
+
+The host-side tiling function (`op_host/arch35/xdivy_tiling_arch35.cpp`) runs this pipeline:
+
+```
+GetShapeInfo
+  ├── read input/output shapes from TilingContext (const gert::Shape& reference, no copy)
+  ├── whitelist-check dtype {fp32, fp16, bf16}, then dtypeSize = ge::GetSizeByDataType(dtype)
+  │     (2 for fp16/bf16, 4 for fp32)
+  └── classify dtype → physNodes P (3 for fp32, 4 for fp16/bf16 cast path)
+
+PadAndSqueeze  (host-side, namespace Xdivy)
+  ├── right-align shapes (pad shorter with 1s)
+  └── drop broadcast-only dims (where every input/output has size 1)
+       → maxBroShape + normalised input/output shapes
+
+CheckBroadcastShape  (host-side, namespace Xdivy)
+  └── per-dim compatibility check: non-1 dim sizes must match across all
+      inputs/outputs (defense-in-depth behind InferShape; must pass before BroadcastMergeAxis)
+
+RunTiling rank dispatch
+  ├── rank = maxBroShape.size()
+  ├── if rank ≤ 4: R=4, SetTilingKey(GET_TPL_TILING_KEY(XDIVY_RANK_4))
+  └── else:         R=8, SetTilingKey(GET_TPL_TILING_KEY(XDIVY_RANK_8))
+
+DoTilingAndSet<R>
+  ├── perBufBytes = (UB / P) & UB_ALIGN_MASK   (32-byte aligned)
+  ├── FindSplitAxis: pick innermost dim that overflows perBufBytes
+  ├── MultiCoreSplit: distribute tiles across cores
+  ├── PrecomputeStrides (broadcast-aware)
+  └── fill XdivyTilingData<R> (leading-1 padding to fixed rank R)
+```
+
+## Kernel VF (Vector Function) Fused Compute
+
+The kernel's compute (`XdivyVF` in `op_kernel/arch35/xdivy_kernel.h`) is register-fused:
+
+```
+S1: Div(x1, x2)         → regDiv
+S2: Compare(x1, 0, EQ)  → maskEq   (regZero = x1 - x1)
+S3: Select(maskEq, 0, regDiv) → regFinal
+```
+
+Chain length 3 ≤ 7 (the hardware limit), so intermediate values stay in registers and never touch UB. This is the key optimisation that makes the broadcast kernel bandwidth-efficient.
+
+## Building and Testing
+
+From the `operators/` directory (one level up):
+
+```bash
+# Build + install the operator package.
+./build.sh xdivy_custom_package
+
+# Run tests (each script will invoke build.sh as needed for aclnn/geir):
+cd xdivy_custom_package/tests/tiling && ./run.sh   # No device needed
+cd xdivy_custom_package/tests/geir   && ./run.sh   # Needs NPU
+cd xdivy_custom_package/tests/aclnn  && ./run.sh   # Needs NPU
+```
+
+## Adapting This Template for a New Broadcast Operator
+
+To create a new broadcast operator (e.g. `MulBroadcast` computing `y = x1 * x2` with broadcast):
+
+1. **Copy the package** and rename all files / namespaces:
+   - `xdivy` → `mul_broadcast`, `Xdivy` → `MulBroadcast`, `XDIVY` → `MUL_BROADCAST`
+2. **Update the compute** in `op_kernel/arch35/xdivy_kernel.h`:
+   - Replace `XdivyVF` with your operator's fused compute (e.g. `AscendC::Reg::Mul` for Mul).
+   - Adjust the buffer count `NUM_BUF` if your compute needs more/fewer live buffers.
+3. **Update dtype support** in:
+   - `op_host/xdivy_def.cpp` (`.DataType({...})` list)
+   - `op_graph/xdivy_proto.h` (`TensorType({...})` list)
+4. **Rename kernel symbol** in `op_kernel/xdivy.cpp` (`__global__ __aicore__ void xdivy` → `mul_broadcast`) AND the `opFile.value` binding in `op_host/xdivy_def.cpp` AND `KERNEL_FILE` in `CMakeLists.txt`.
+5. **Adjust `MAX_INPUT_SLOTS` / `MAX_OUTPUT_SLOTS`** in `op_kernel/arch35/xdivy_tiling_struct.h` if your operator has more inputs/outputs.
+6. **Update test data patterns** in `tests/{geir,aclnn}/*.cpp` to match your operator's expected outputs.

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/broadcast/example/xdivy_custom_package/op_graph/xdivy_graph_infer.cpp

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+
+/*!
+ * \file xdivy_graph_infer.cpp
+ * \brief Xdivy 算子的 graph 侧推理注册（InferDataType）。
+ *
+ *   - 与 op_host/xdivy_infershape.cpp 分工：shape 推理（broadcast 输出 shape =
+ *     broadcastMax(x1, x2)）留在 op_host 侧 IMPL_OP_INFERSHAPE；输出 dtype 推理
+ *     （y 跟随 x1 直通）在本文件 IMPL_OP(Xdivy).InferDataType(...) 注册。
+ */
+#include "register/op_impl_registry.h"
+#include "op_common/log/log.h"
+
+namespace ops {
+using namespace ge;
+
+static constexpr int64_t IDX_0 = 0;
+
+// Xdivy: 输出 y dtype 跟随输入 x1 dtype（fp16 / bf16 / fp32 直通）
+static ge::graphStatus InferDataTypeXdivy(gert::InferDataTypeContext* context)
+{
+    OP_LOGD(context->GetNodeName(), "Begin to do InferDataTypeXdivy");
+    const ge::DataType x1Dtype = context->GetInputDataType(IDX_0);
+    context->SetOutputDataType(IDX_0, x1Dtype);
+    OP_LOGD(context->GetNodeName(), "End to do InferDataTypeXdivy");
+    return ge::GRAPH_SUCCESS;
+}
+
+IMPL_OP(Xdivy).InferDataType(InferDataTypeXdivy);
+} // namespace ops

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/broadcast/example/xdivy_custom_package/op_graph/xdivy_proto.h

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+
+// Xdivy GE IR 原型注册 — 声明算子在图引擎中的节点签名 (2入1出)
+#ifndef XDIVY_PROTO_H_
+#define XDIVY_PROTO_H_
+
+#include "graph/operator_reg.h"
+#include "graph/types.h"
+
+namespace ge {
+
+/**
+ * REG_OP(Xdivy): registers a GE IR node type named "Xdivy".
+ *
+ *   .INPUT(x1, TensorType({DT_BF16, DT_FLOAT16, DT_FLOAT})): dividend, named
+ *     "x1", accepts bf16 / float16 / float32.
+ *   .INPUT(x2, TensorType({DT_BF16, DT_FLOAT16, DT_FLOAT})): divisor, named
+ *     "x2", accepts the same types.
+ *   .OUTPUT(y, TensorType({DT_BF16, DT_FLOAT16, DT_FLOAT})): result tensor,
+ *     named "y", same type as inputs.
+ *   .OP_END_FACTORY_REG(Xdivy): completes the factory registration so the
+ *     node can be instantiated via op::Xdivy("name").
+ *
+ * Formula:  y = (x1 == 0) ? 0 : (x1 / x2)
+ */
+REG_OP(Xdivy)
+    .INPUT(x1, TensorType({DT_BF16, DT_FLOAT16, DT_FLOAT, DT_DOUBLE, DT_COMPLEX64, DT_COMPLEX128}))
+    .INPUT(x2, TensorType({DT_BF16, DT_FLOAT16, DT_FLOAT, DT_DOUBLE, DT_COMPLEX64, DT_COMPLEX128}))
+    .OUTPUT(y, TensorType({DT_BF16, DT_FLOAT16, DT_FLOAT, DT_DOUBLE, DT_COMPLEX64, DT_COMPLEX128}))
+    .OP_END_FACTORY_REG(Xdivy)
+
+} // namespace ge
+
+#endif // XDIVY_PROTO_H_