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

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/ascendc-api/moe-dispatch-combine/tiling-scheme/window-memory-layout.md

@@ -0,0 +1,199 @@
+# MoE Dispatch/Combine 窗口内存布局
+
+本文只记录 dispatch 数据区、dispatch 状态区、combine 数据区、combine 状态区的布局公式、地址规则和状态区相关的 UB 大小计算。
+
+进入本页前，默认已经明确：
+
+- dispatch / combine 的阶段划分和中间量语义
+- 通信 token 与 `expandIdx` / `epRecvCounts` / `epSendCounts` 的闭环关系
+- 是否采用 window + 状态协议，以及 shared expert、量化、mask 等路径是否参与主布局
+
+本页不重复控制流、接口契约和 API 一致性规则，只把这些语义落实成字节级布局。
+
+## Dispatch 数据区布局
+
+### 布局规则
+
+```
+排布维度：sourceRank → localExpert → tokenSlot
+```
+
+每个 tokenSlot 存放一个完整通信 token = payload（32B 对齐）+ triple（3 × int32）。
+
+### 基础常量
+
+```c++
+payloadBytes         = AlignUp(H * sizeof(dtype), 32)   // 32B 对齐
+tripleBytes          = 3 * sizeof(int32_t)               // = 12B，[srcRank, srcTokenIdx, srcTopKIdx]
+commTokenBytes       = payloadBytes + tripleBytes
+expertRegionBytes    = BS * commTokenBytes               // 单个 (srcRank, localExpert) 区域
+sourceRankRegionBytes = localExpertNum * expertRegionBytes
+rankDataBytes        = epWorldSize * sourceRankRegionBytes
+```
+
+### 地址公式
+
+```c++
+GM_ADDR dstDataAddr =
+    GetBaseWindAddrByRankId(ctx, dstRank, curRankId)
+    + (uint64_t)srcRank    * sourceRankRegionBytes
+    + (uint64_t)localExpert * expertRegionBytes
+    + (uint64_t)dstSlot    * commTokenBytes
+```
+
+其中 `dstSlot = curExpertCnt`，即该 token 在目标 expert 已接收 token 中的顺序序号。
+
+### Triple 写入位置
+
+```c++
+// payload 写完后，triple 紧随其后
+uint32_t tripleOffset = payloadBytes / sizeof(dtype);  // dtype 单位偏移
+// triple[0] = srcRankId, triple[1] = srcTokenIdx, triple[2] = srcTopKIdx
+```
+
+---
+
+## Dispatch 状态区布局
+
+### 布局规则
+
+```
+排布维度：localExpert → sourceRank → stateSlot
+```
+
+每个 stateSlot = 32B（8 × int32_t）。
+
+### Slot 格式
+
+```
+slot[0] = flag         (0=未就绪, 1=就绪)
+slot[1] = tokenCount   (该 srcRank → localExpert 的实际发送 token 数)
+slot[2..7] = padding   (仅用于 32B 对齐)
+```
+
+### 相关常量
+
+```c++
+STATE_SLOT_INT32   = 8                   // 每 slot 8 个 int32_t
+STATE_SLOT_BYTES   = 32                  // = 8 * 4
+STATE_READY_OFFSET = 0                   // flag 在 slot 中的下标
+STATE_TOKEN_OFFSET = 1                   // tokenCount 在 slot 中的下标
+
+totalStateElems    = localExpertNum * rankDim * STATE_SLOT_INT32
+totalStateBytes    = localExpertNum * rankDim * STATE_SLOT_BYTES
+```
+
+### 地址公式
+
+```c++
+GM_ADDR dstStateAddr =
+    GetBaseWindStateAddrByRankId(ctx, dstRank, curRankId)
+    + ((uint64_t)localExpert * rankDim + (uint64_t)srcRank) * STATE_SLOT_BYTES
+```
+
+等待阶段读取本地状态区：
+
+```c++
+GM_ADDR localStateBase = GetStatusDataSpaceGm(ctx)
+// slot[localExpert][srcRank] 地址：
+localStateBase + (localExpert * rankDim + srcRank) * STATE_SLOT_BYTES
+```
+
+---
+
+## Combine 数据区布局
+
+### 布局规则
+
+```
+排布维度：srcTokenIdx → slotIdx (K + sharedExpertNum slots per token)
+前 K 个 slot：MoE expert 结果（按 topK 顺序）
+后 sharedExpertNum 个 slot：共享专家结果
+```
+
+### 基础常量
+
+```c++
+slotCountPerToken    = K + sharedExpertNum
+payloadBytes         = H_expand * sizeof(ExpandXType)
+slotBytes            = AlignUp(payloadBytes, winAlignBytes)
+tokenRegionBytes     = slotCountPerToken * slotBytes
+rankCombineBytes     = BS * tokenRegionBytes
+```
+
+### 地址公式
+
+```c++
+GM_ADDR dataAddr =
+    GetBaseWindAddrByRankId(ctx, dstRank, curRankId)
+    + (uint64_t)srcTokenIdx * tokenRegionBytes
+    + (uint64_t)srcSlotIdx  * slotBytes
+```
+
+其中 `srcSlotIdx = srcTopKIdx`（MoE slot）或 `K + sharedExpertSlotIdx`（共享专家 slot）。
+
+---
+
+## Combine 状态区布局
+
+### 布局规则
+
+```
+排布维度：srcTokenIdx → slotIdx (同数据区)
+```
+
+每个状态槽大小由实现决定，最小为 32B。
+
+### 基础常量
+
+```c++
+stateStrideBytes      = 32    // 单个状态槽
+tokenStateRegionBytes = slotCountPerToken * stateStrideBytes
+```
+
+### Slot 格式
+
+```
+slot[0] = readyFlag   (0=未就绪, 1=就绪)
+slot[1..7] = padding
+```
+
+等待条件：
+
+```c++
+// 每个 token 等待自己需要的所有 slot 就绪
+targetReadyCount(token) = K + sharedExpertNum   // 无 mask 时
+// 有 xActiveMask 或 zero expert 时需相应减少
+```
+
+### 地址公式
+
+```c++
+GM_ADDR stateAddr =
+    GetBaseWindStateAddrByRankId(ctx, dstRank, curRankId)
+    + (uint64_t)srcTokenIdx * tokenStateRegionBytes
+    + (uint64_t)srcSlotIdx  * stateStrideBytes
+```
+
+---
+
+## 状态区相关 UB 大小
+
+```c++
+// 写单个状态 slot（SetRemoteStatus 使用）
+stateWriteBuf  = STATE_SLOT_INT32 * sizeof(int32_t)  = 32B
+
+// 读全量本地状态区（WaitRemoteStatus 使用）
+stateReadBuf   = localExpertNum * rankDim * STATE_SLOT_INT32 * sizeof(int32_t)
+
+// 重置全量本地状态区（ClearLocalStatus 使用）
+stateResetBuf  = localExpertNum * rankDim * STATE_SLOT_INT32 * sizeof(int32_t)
+```
+
+多核后等待阶段只读自己负责的状态段时，`stateReadBuf` 大小可相应缩减为"本核负责段大小"。
+
+## 下一跳
+
+- 分核数量公式：`multi-core-formulas.md`
+- 获取 window 基址的接口：`../api-rules/mte-address-access.md`
+- 双缓冲四区协议：`double-buffer-protocol.md`

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/all_to_all_matmul/CMakeLists.txt

@@ -0,0 +1,95 @@
+
+# ============================================================================
+# MC2 通算融合算子构建脚本（all_to_all_matmul）
+# ----------------------------------------------------------------------------
+# 该 CMakeLists 是 [REUSE] 标记文件——常规 MC2 算子不需要改这里的内容。
+# 仅在新增可执行目标时改两处：project() 名 + add_executable() 目标名 + 源文件。
+#
+# 关键设计：
+#   1. NPU_ARCH=dav-3510 是硬约束（仅支持 Ascend 950）；dav-2201 仅做校验兼容，会发 WARNING；
+#   2. cmake/ascend.cmake 必须在 project() 之前 include（设 BISHENG 编译器、ASCEND_HOME_PATH）；
+#   3. shmem.cmake 和 tensor_api.cmake 用 REQUIRED（不是 OPTIONAL）——
+#      OPTIONAL 在路径错时会静默跳过，导致 cann_samples::shmem / cann_samples::tensor_api 未定义，链接时报"target not found"；
+#   4. tensor_api 来自 asc-devkit（gitcode.com/cann/asc-devkit），与 ascendc-blaze-best-practice skill 共享同一来源；
+#   5. -xasc --npu-arch=dav-3510 是 bisheng 双路径编译的必需参数（host + kernel 同时编）。
+#
+# 进阶细节：references/codebase_map.md §4
+# ============================================================================
+
+cmake_minimum_required(VERSION 3.16)
+
+# NPU_ARCH 入参校验（与源工程父 CMakeLists 一致）
+set(VALID_NPU_ARCHS dav-3510 dav-2201)
+if(NOT DEFINED NPU_ARCH OR NPU_ARCH STREQUAL "")
+    message(FATAL_ERROR "NPU_ARCH is required. Example: cmake -S . -B build -DNPU_ARCH=dav-3510")
+endif()
+if(NOT "${NPU_ARCH}" IN_LIST VALID_NPU_ARCHS)
+    message(FATAL_ERROR "Unsupported NPU_ARCH: ${NPU_ARCH}. Supported values: dav-3510, dav-2201")
+endif()
+if(NOT NPU_ARCH STREQUAL "dav-3510")
+    message(WARNING "Unsupported NPU_ARCH=${NPU_ARCH}, expected dav-3510")
+endif()
+
+# 关键：cmake/ascend.cmake 必须在 project() 之前 include（设置 BISHENG 编译器、ASCEND_HOME_PATH）
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/ascend.cmake REQUIRED)
+
+find_package(ASC)
+project(all_to_all_matmul LANGUAGES C CXX ASC)
+
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# third_party: shmem + tensor_api（首次 cmake 配置时由各自 .cmake 自动 git clone，无需 submodule）
+# 关键：用 REQUIRED 而非 OPTIONAL —— OPTIONAL 会在路径错误时静默跳过，
+#       导致 cann_samples::shmem / cann_samples::tensor_api target 未定义，
+#       后续 target_link_libraries 报 "target not found"，定位困难
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/shmem.cmake REQUIRED)
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/tensor_api.cmake REQUIRED)
+
+# Blaze 头文件路径：新 kernel (qbmm_mx_kernel.h) 依赖 blaze/gemm/block/block_mmad_qbmm_mx.h，
+# 该头文件位于 CANN toolkit 的 ascendc/common 目录下（ops_nn 与 ops_transformer 内容一致）。
+# 同时补齐 ASC toolkit 的 x86_64-linux 实际路径。
+# tensor_api 头文件由 cmake/tensor_api.cmake 通过 cann_samples::tensor_api 提供（自动 clone asc-devkit），
+# 不从 _BLAZE_COMMON_DIR/tensor_api 取（避免 toolkit 版与 asc-devkit 版混用）。
+# 注意 ASCEND_HOME_PATH 是环境变量（由 ascend.cmake 设给 ASCEND_DIR CMake 变量），这里用 $ENV{} 兜底。
+if(NOT DEFINED ASCEND_DIR)
+    set(ASCEND_DIR $ENV{ASCEND_HOME_PATH})
+endif()
+set(_ASC_ARCH_DIR "${ASCEND_DIR}/x86_64-linux")
+set(_BLAZE_COMMON_DIR "${ASCEND_DIR}/opp/built-in/op_impl/ai_core/tbe/impl/ops_nn/ascendc/common")
+
+add_executable(all_to_all_matmul src/all_to_all_matmul.cpp)
+target_compile_definitions(all_to_all_matmul PRIVATE SOURCE_DIR="${CMAKE_CURRENT_SOURCE_DIR}")
+target_include_directories(all_to_all_matmul PRIVATE
+    "${CMAKE_CURRENT_SOURCE_DIR}/include"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/kernel"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/tiling"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/block"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/tile"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/policy"
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/utils"
+    "${CMAKE_CURRENT_SOURCE_DIR}/common"
+    "${_BLAZE_COMMON_DIR}"
+    "${_ASC_ARCH_DIR}/asc/include"
+    "${_ASC_ARCH_DIR}/asc"
+)
+# 新增 .cpp 必须保留 -xasc --npu-arch=dav-3510（bisheng 把 .cpp 同时走 host 编译 + kernel 编译双路径）
+target_compile_options(all_to_all_matmul PRIVATE
+    "-xasc"
+    "--npu-arch=dav-3510"
+    "-w"
+    "-O3"
+)
+target_link_libraries(all_to_all_matmul
+    PRIVATE
+    cann_samples::tensor_api
+    cann_samples::shmem
+    dl
+    platform
+    tiling_api
+    ascendcl
+    runtime
+    stdc++
+)

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/all_to_all_matmul/cmake/ascend.cmake

@@ -0,0 +1,59 @@
+
+# find ascend toolkit
+if(UNIX)
+    set(_ascend_processor "${CMAKE_SYSTEM_PROCESSOR}")
+    if(NOT _ascend_processor)
+        set(_ascend_processor "${CMAKE_HOST_SYSTEM_PROCESSOR}")
+    endif()
+    if(NOT _ascend_processor)
+        execute_process(
+            COMMAND uname -m
+            OUTPUT_VARIABLE _ascend_processor
+            OUTPUT_STRIP_TRAILING_WHITESPACE
+        )
+    endif()
+    set(SYSTEM_PREFIX "${_ascend_processor}-linux")
+endif()
+
+if(DEFINED ENV{ASCEND_HOME_PATH})
+    set(ASCEND_DIR $ENV{ASCEND_HOME_PATH})
+else()
+    message(WARNING "Environment variable ASCEND_HOME_PATH is not set. Using default path.")
+    if("$ENV{USER}" STREQUAL "root")
+        message(STATUS "Running as root user, checking default root paths for Ascend toolkit.")
+        if(EXISTS /usr/local/Ascend/ascend-toolkit/latest)
+            set(ASCEND_DIR /usr/local/Ascend/ascend-toolkit/latest)
+        elseif(EXISTS /usr/local/Ascend/latest)
+            set(ASCEND_DIR /usr/local/Ascend/latest)
+        else()
+            message(FATAL_ERROR "Ascend toolkit not found in default root paths. Please set ASCEND_HOME_PATH.")
+        endif()
+    else()
+        message(STATUS "Running as non-root user, checking default user paths for Ascend toolkit.")
+        if(EXISTS $ENV{HOME}/Ascend/ascend-toolkit/latest)
+            set(ASCEND_DIR $ENV{HOME}/Ascend/ascend-toolkit/latest)
+        elseif(EXISTS $ENV{HOME}/Ascend/latest)
+            set(ASCEND_DIR $ENV{HOME}/Ascend/latest)
+        else()
+            message(FATAL_ERROR "Ascend toolkit not found in default user paths. Please set ASCEND_HOME_PATH.")
+        endif()
+    endif()
+endif()
+
+message(STATUS "Using Ascend toolkit path: ${ASCEND_DIR}")
+set(CMAKE_PREFIX_PATH ${ASCEND_DIR}/)
+set(BISHENG "${ASCEND_DIR}/${SYSTEM_PREFIX}/ccec_compiler/bin/bisheng" CACHE FILEPATH "Path to Bisheng compiler")
+message(STATUS "Bisheng compiler path: ${BISHENG}")
+
+# Configure the default toolchain before project() initializes the languages.
+if(NOT DEFINED CMAKE_C_COMPILER)
+    set(CMAKE_C_COMPILER "${BISHENG}" CACHE FILEPATH "C compiler" FORCE)
+endif()
+
+if(NOT DEFINED CMAKE_CXX_COMPILER)
+    set(CMAKE_CXX_COMPILER "${BISHENG}" CACHE FILEPATH "CXX compiler" FORCE)
+endif()
+
+if(NOT DEFINED CMAKE_LINKER)
+    set(CMAKE_LINKER "${BISHENG}" CACHE FILEPATH "Linker" FORCE)
+endif()

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/all_to_all_matmul/cmake/shmem.cmake

@@ -0,0 +1,75 @@
+if(TARGET cann_samples_shmem)
+    return()
+endif()
+
+find_package(Git QUIET)
+
+set(SHMEM_PATH "${PROJECT_SOURCE_DIR}/third_party/shmem")
+set(SHMEM_GIT_URL "https://gitcode.com/cann/shmem.git" CACHE STRING "SHMEM 仓库地址")
+set(SHMEM_GIT_TAG "v1.5.0" CACHE STRING "SHMEM 仓库版本标签")
+
+if(NOT EXISTS "${SHMEM_PATH}/CMakeLists.txt" AND NOT GIT_FOUND)
+    message(FATAL_ERROR
+        "Git is required to initialize third_party/shmem automatically."
+    )
+endif()
+
+# shmem 来源：gitcode.com/cann/shmem v1.5.0，由 cmake 首次配置时自动 clone。
+# 不用 git submodule（避免根目录 .gitmodules），改为在 custom_target 里 git clone。
+# 版本由 SHMEM_GIT_TAG 锁定；工程被 cp -r 到任意目录后首次 cmake 也能自动拉取。
+set(SHMEM_PREPARE_COMMANDS)
+if(GIT_FOUND AND NOT EXISTS "${SHMEM_PATH}/CMakeLists.txt")
+    list(APPEND SHMEM_PREPARE_COMMANDS
+        COMMAND ${GIT_EXECUTABLE} clone --branch ${SHMEM_GIT_TAG} --depth 1 ${SHMEM_GIT_URL} "${SHMEM_PATH}"
+    )
+endif()
+
+add_custom_target(cann_samples_shmem_dependencies
+    ${SHMEM_PREPARE_COMMANDS}
+    COMMAND ${CMAKE_COMMAND} -E env
+        ASCEND_HOME_PATH=${ASCEND_DIR}
+        ASCEND_TOOLKIT_HOME=${ASCEND_DIR}
+        cmake -S "${SHMEM_PATH}" -B "${SHMEM_PATH}/build" -DCMAKE_BUILD_TYPE=RELEASE -DSOC_TYPE=Ascend950 -DCMAKE_C_FLAGS=-w -DCMAKE_CXX_FLAGS=-w
+    COMMAND ${CMAKE_COMMAND} --build "${SHMEM_PATH}/build" --target install --parallel
+    WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}"
+    COMMENT "Initializing and building third_party/shmem"
+    VERBATIM
+)
+
+add_library(cann_samples_shmem_bootstrap_uid SHARED IMPORTED GLOBAL)
+set_target_properties(cann_samples_shmem_bootstrap_uid PROPERTIES
+    IMPORTED_LOCATION "${SHMEM_PATH}/install/shmem/lib/aclshmem_bootstrap_uid.so"
+)
+add_dependencies(cann_samples_shmem_bootstrap_uid cann_samples_shmem_dependencies)
+
+add_library(cann_samples_shmem_bootstrap_config_store SHARED IMPORTED GLOBAL)
+set_target_properties(cann_samples_shmem_bootstrap_config_store PROPERTIES
+    IMPORTED_LOCATION "${SHMEM_PATH}/install/shmem/lib/aclshmem_bootstrap_config_store.so"
+)
+add_dependencies(cann_samples_shmem_bootstrap_config_store cann_samples_shmem_dependencies)
+
+add_library(cann_samples_shmem INTERFACE)
+add_library(cann_samples::shmem ALIAS cann_samples_shmem)
+add_dependencies(cann_samples_shmem cann_samples_shmem_dependencies)
+
+target_include_directories(cann_samples_shmem INTERFACE
+    "${SHMEM_PATH}/install/shmem/include"
+    "${SHMEM_PATH}/install/shmem/src"
+    "${SHMEM_PATH}/install/shmem/src/device"
+    "${SHMEM_PATH}/install/shmem/src/host_device"
+)
+
+target_link_directories(cann_samples_shmem INTERFACE
+    "${SHMEM_PATH}/install/shmem/lib"
+)
+
+target_link_libraries(cann_samples_shmem INTERFACE
+    shmem
+    shmem_utils
+    cann_samples_shmem_bootstrap_uid
+    cann_samples_shmem_bootstrap_config_store
+)
+
+target_link_options(cann_samples_shmem INTERFACE
+    "LINKER:-rpath,${SHMEM_PATH}/install/shmem/lib"
+)

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/all_to_all_matmul/cmake/tensor_api.cmake

@@ -0,0 +1,48 @@
+
+if(TARGET cann_samples_tensor_api)
+    return()
+endif()
+
+find_package(Git QUIET)
+
+set(TENSOR_API_PATH "${PROJECT_SOURCE_DIR}/third_party/tensor_api")
+set(TENSOR_API_GIT_URL "https://gitcode.com/cann/asc-devkit.git" CACHE STRING "tensor_api 仓库地址")
+set(TENSOR_API_GIT_TAG "ad3d3bf04dddfb94370c534c39bdd305d8e38d88" CACHE STRING "tensor_api 仓库 commit (feature/tensor_api_from_9.0.0)")
+
+if(NOT EXISTS "${TENSOR_API_PATH}/include/tensor_api/tensor.h" AND NOT GIT_FOUND)
+    message(FATAL_ERROR
+        "Git is required to initialize third_party/tensor_api automatically."
+    )
+endif()
+
+# tensor_api 来源：gitcode.com/cann/asc-devkit（feature/tensor_api_from_9.0.0 分支，commit ad3d3bf），
+# 与 ascendc-blaze-best-practice skill 共享同一来源。
+# 不用 git submodule（避免根目录 .gitmodules），改为在 custom_target 里 git clone + checkout。
+# 关键：include path 设为 clone 根目录，使代码中 #include "include/tensor_api/tensor.h"
+#       解析到 ${TENSOR_API_PATH}/include/tensor_api/tensor.h；
+#       impl/ 头文件也由该路径解析（${TENSOR_API_PATH}/impl/tensor_api/...）。
+# 注意：tag 用 commit hash 而非分支名，因为 asc-devkit 的 tensor_api 在 feature 分支上，
+#       无独立 tag；--depth 1 + 指定 commit 需要 fetch 该 commit，故不加 --depth。
+set(TENSOR_API_PREPARE_COMMANDS)
+if(GIT_FOUND AND NOT EXISTS "${TENSOR_API_PATH}/include/tensor_api/tensor.h")
+    list(APPEND TENSOR_API_PREPARE_COMMANDS
+        COMMAND ${GIT_EXECUTABLE} clone ${TENSOR_API_GIT_URL} "${TENSOR_API_PATH}"
+        COMMAND ${GIT_EXECUTABLE} -C "${TENSOR_API_PATH}" checkout ${TENSOR_API_GIT_TAG}
+    )
+endif()
+
+add_custom_target(cann_samples_tensor_api_dependencies
+    ${TENSOR_API_PREPARE_COMMANDS}
+    WORKING_DIRECTORY "${PROJECT_SOURCE_DIR}"
+    COMMENT "Initializing third_party/tensor_api"
+    VERBATIM
+)
+
+add_library(cann_samples_tensor_api INTERFACE)
+add_library(cann_samples::tensor_api ALIAS cann_samples_tensor_api)
+add_dependencies(cann_samples_tensor_api cann_samples_tensor_api_dependencies)
+
+target_include_directories(cann_samples_tensor_api INTERFACE
+    "${TENSOR_API_PATH}"
+    "${TENSOR_API_PATH}/include"
+)

package/assets/ops-direct-invoke/skills/ascendc-mc2-best-practice/references/foundations/blaze-shmem/all_to_all_matmul/common/host_utils/acl_utils.h

@@ -0,0 +1,73 @@
+
+/**
+ * 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 acl_utils.h
+ * \brief RAII wrapper for ACL runtime initialization, device setup, and stream cleanup.
+ */
+#pragma once
+
+#include <cstdint>
+
+#include "acl/acl.h"
+
+#include "common_utils.h"
+
+class AclRtSession {
+public:
+    explicit AclRtSession(int32_t deviceId) : deviceId_(deviceId) {}
+
+    void Init()
+    {
+        CHECK_COND(aclInit(nullptr) == ACL_SUCCESS, "Failed to initialize ACL runtime.");
+        aclInitialized_ = true;
+
+        uint32_t deviceCount = 0;
+        CHECK_COND(aclrtGetDeviceCount(&deviceCount) == ACL_SUCCESS, "Failed to query ACL device count.");
+        CHECK_COND(deviceCount > 0U, "No ACL devices are available.");
+        CHECK_COND(deviceId_ >= 0 && static_cast<uint32_t>(deviceId_) < deviceCount, "ACL device id is out of range.");
+
+        CHECK_COND(aclrtSetDevice(deviceId_) == ACL_SUCCESS, "Failed to set the ACL device.");
+        deviceSet_ = true;
+        CHECK_COND(aclrtCreateStream(&stream_) == ACL_SUCCESS, "Failed to create the ACL stream.");
+    }
+
+    aclrtStream GetStream() const
+    {
+        return stream_;
+    }
+
+    ~AclRtSession()
+    {
+        if (stream_ != nullptr) {
+            (void)aclrtDestroyStream(stream_);
+            stream_ = nullptr;
+        }
+        if (deviceSet_) {
+            (void)aclrtResetDevice(deviceId_);
+            deviceSet_ = false;
+        }
+        if (aclInitialized_) {
+            (void)aclFinalize();
+            aclInitialized_ = false;
+        }
+    }
+
+    AclRtSession(const AclRtSession&) = delete;
+    AclRtSession& operator=(const AclRtSession&) = delete;
+
+private:
+    int32_t deviceId_;
+    aclrtStream stream_{nullptr};
+    bool deviceSet_{false};
+    bool aclInitialized_{false};
+};
+