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

package/assets/ops-direct-invoke/skills/ascendc-simt-best-practices/references/macro-api.md

@@ -0,0 +1,65 @@
+# 内置宏参考
+
+> 快速参考导航 - 以下是本分类的完整宏定义列表
+
+# 内置宏
+
+涵盖 bfloat16、half、float 三种浮点类型的特殊值、数学常数和边界值。
+
+## bfloat16 特殊值 (asc_bf16.h)
+
+| 宏名 | 描述 |
+|------|------|
+| ASCRT_INF_BF16 | 正无穷大 |
+| ASCRT_MAX_NORMAL_BF16 | 最大表示值 |
+| ASCRT_MIN_DENORM_BF16 | 最小表示值 |
+| ASCRT_NAN_BF16 | NaN |
+| ASCRT_NEG_ZERO_BF16 | 负零 |
+| ASCRT_ONE_BF16 | 1.0 |
+| ASCRT_ZERO_BF16 | 正零 |
+
+## half 特殊值 (asc_fp16.h)
+
+| 宏名 | 描述 |
+|------|------|
+| ASCRT_INF_FP16 | 正无穷大 |
+| ASCRT_MAX_NORMAL_FP16 | 最大表示值 |
+| ASCRT_MIN_DENORM_FP16 | 最小表示值 |
+| ASCRT_NAN_FP16 | NaN |
+| ASCRT_NEG_ZERO_FP16 | 负零 |
+| ASCRT_ONE_FP16 | 1.0 |
+| ASCRT_ZERO_FP16 | 正零 |
+
+## float 特殊值 (math_constants.h)
+
+| 宏名 | 描述 |
+|------|------|
+| ASCRT_INF_F | 正无穷大 |
+| ASCRT_MAX_NORMAL_F | 最大表示值 |
+| ASCRT_MIN_DENORM_F | 最小表示值 |
+| ASCRT_NAN_F | NaN |
+| ASCRT_NEG_ZERO_F | 负零 |
+| ASCRT_ONE_F | 1.0 |
+| ASCRT_ZERO_F | 正零 |
+
+## 数学常数 (math_constants.h)
+
+| 宏名 | 描述 |
+|------|------|
+| ASCRT_SQRT_HALF_F | √0.5 |
+| ASCRT_SQRT_HALF_HI_F | √0.5 高位部分 |
+| ASCRT_SQRT_HALF_LO_F | √0.5 低位部分 |
+| ASCRT_SQRT_TWO_F | √2 |
+| ASCRT_THIRD_F | 1/3 |
+| ASCRT_PIO4_F | π/4 |
+| ASCRT_PIO2_F | π/2 |
+| ASCRT_PI_F | π |
+| ASCRT_TWOPI_F | 2π |
+| ASCRT_ONE_OVER_PI_F | 1/π |
+| ASCRT_TWO_OVER_PI_F | 2/π |
+| ASCRT_LN2_F | ln(2) |
+| ASCRT_LN10_F | ln(10) |
+| ASCRT_LOG2E_F | log2(e) |
+| ASCRT_LOG10E_F | log10(e) |
+| ASCRT_LN2_HI_F | ln(2) 高位部分 |
+| ASCRT_LN2_LO_F | ln(2) 低位部分 |

package/assets/ops-direct-invoke/skills/ascendc-simt-best-practices/references/multi-core-sync.md

@@ -0,0 +1,39 @@
+# 多核数据交换与同步
+
+## 多核之间交换数据
+
+如果需要多核之间交换数据，需要使用 **workspace**：
+
+1. **tiling 侧**：申请 workspace 大小
+2. **kernel 侧**：直接使用 workspace 指针
+
+### 防止时序问题
+
+- kernel 处需要调用 `SyncAll()` 接口
+- tiling 需要设置 `context->SetScheduleMode(1)`
+
+```cpp
+// Tiling 侧
+context->SetScheduleMode(1);  // 同步模式
+size_t workspaceSize = ...;   // 计算所需 workspace 大小
+context->SetWorkspaceSize(workspaceSize);
+
+// Kernel 侧
+__gm__ float* ws = (__gm__ float*)workspace;
+// ... 使用 workspace 交换数据 ...
+AscendC::SyncAll();  // 全核同步
+```
+
+## 多个 VF_CALL 之间的同步
+
+1. 同一个 kernel 内多个 `Simt::VF_CALL` 之间**仅能保证 block 内 VF 串行**
+2. **不能保证全核同步**
+3. 如果 `Simt::VF_CALL` 之间需要全核同步：
+   - 在同步的位置加上 `SyncAll()`
+   - tiling 设置 `context->SetScheduleMode(1)`
+
+## 头文件
+
+```cpp
+#include "simt_api/device_sync_functions.h"
+```

package/assets/ops-direct-invoke/skills/ascendc-simt-best-practices/references/overview.md

@@ -0,0 +1,128 @@
+# SIMT C API 总览
+
+SIMT API基于AI Core硬件能力，通过 `AscendC::Simt::VF_CALL` 启动SIMT VF子任务。每32个线程组成一个Warp，Warp内每个线程称为Lane（编号0~31）。
+
+## 头文件包含
+
+```cpp
+#include "simt_api/asc_simt.h"       // 通用（非half/bfloat16/fp8类型）
+#include "simt_api/asc_fp16.h"       // half/half2类型API
+#include "simt_api/asc_bf16.h"       // bfloat16/bfloat16x2_t类型API
+#include "simt_api/asc_fp8.h"        // hifloat8x2_t/float8_e4m3x2_t/float8_e5m2x2_t类型API
+```
+
+## API分类
+
+| 类别 | 功能 | 头文件 | 索引文件 |
+|------|------|--------|----------|
+| 核函数定义 | 启动SIMT VF子任务 | common_functions.h | `misc/asc_vf_call.md` |
+| 同步函数 | 线程同步与内存可见性 | device_sync_functions.h | `01_同步函数.md` |
+| 数学函数 | 三角/指数/对数/幂等运算 | math_functions.h | `02_数学函数.md` |
+| 精度转换 | 取整(rint/round/floor/ceil) | math_functions.h | `03_精度转换.md` |
+| 比较函数 | 判断有限数/NaN/Inf | math_functions.h | `04_比较函数.md` |
+| 原子操作 | UB/GM上的原子读写 | device_atomic_functions.h | `05_原子操作.md` |
+| Warp函数 | Warp内数据交换/归约 | device_warp_functions.h | `06_Warp函数.md` |
+| 类型转换 | float/half/bf16/int间转换 | device_functions.h | `07_类型转换.md` |
+| 向量构造 | make_int2/float2等 | vector_functions.h | `08_向量构造函数.md` |
+| Cache Hints | 带缓存提示的Load/Store | device_functions.h | `09_Cache_Hints.md` |
+| 调测接口 | printf/assert/trap | asc_simt.h | `10_调测接口.md` |
+| 内置宏 | 特殊值常量和数学常数 | asc_simt.h/asc_fp16.h/asc_bf16.h | `11_内置宏.md` |
+
+---
+
+## 核函数定义与启动
+
+### asc_vf_call
+
+在SIMD与SIMT混合编程场景，启动SIMT VF（Vector Function）子任务，通过参数配置，启动指定数目的线程，执行指定的SIMT核函数。
+
+> 注意：asc_vf_call启动SIMT VF子任务时，子任务函数不能是类的成员函数，推荐使用普通函数或类静态函数，且入口函数必须使用\_\_simt\_vf\_\_修饰宏。传递的参数只支持裸指针和常见基本数据类型，不支持传递结构体、数组等。
+
+**函数原型**:
+
+```cpp
+template <auto funcPtr, typename... Args>
+__aicore__ inline void asc_vf_call(dim3 threadNums, Args &&...args)
+```
+
+**模板参数**:
+
+| 参数名 | 描述 |
+|--------|------|
+| funcPtr | 用于指定SIMT入口核函数 |
+| Args | 定义可变参数，用于传递实参到SIMT入口核函数 |
+
+**参数说明**:
+
+| 参数名 | 输入/输出 | 描述 |
+|--------|-----------|------|
+| threadNums | 输入 | dim3结构{dimx,dimy,dimz}，指定SIMT线程块内线程数量。线程总数=dimx*dimy*dimz，必须<=2048 |
+| args | 输入 | 可变参数，传递实参到SIMT入口核函数 |
+
+**返回值**: 无
+
+**需要包含的头文件**: `#include "simt_api/common_functions.h"`
+
+**调用示例**:
+
+```cpp
+__simt_vf__ __launch_bounds__(2048) inline void SimtCompute(
+    __gm__ float* dst, __gm__ float* src0, __gm__ float* src1, int count) const
+{
+    for(int idx = threadIdx.x + blockIdx.x * blockDim.x; idx < count; idx += gridDim.x * blockDim.x)
+    {
+        dst[idx] = src0[idx] + src1[idx];
+    }
+}
+
+__global__ __aicore__ void SimtComputeShell(__gm__ float* x, __gm__ float* y, __gm__ float* z, const int size)
+{
+    __gm__ float* dst = x;
+    __gm__ float* src0 = y;
+    __gm__ float* src1 = z;
+    asc_vf_call<SimtCompute>(dim3{1024, 1, 1}, dst, src0, src1, size);
+}
+```
+
+---
+
+## SIMD与SIMT混合编程辅助函数
+
+以下函数用于SIMD与SIMT混合编程场景中的辅助操作。
+
+### GetRuntimeUBSize
+
+获取运行时UB空间的大小，单位为byte。开发者根据UB的大小来计算循环次数等参数值。
+
+**函数原型**: `__aicore__ inline uint32_t GetRuntimeUBSize()`
+
+**返回值**: 运行时UB空间的大小（字节）。Ascend 950PR/Ascend 950DT架构下，SIMD与SIMT混合场景中UB大小上限为216KB，非混合场景返回固定值248KB。
+
+**调用示例**:
+
+```cpp
+uint32_t totalLength = 126976;
+uint32_t tileLength = AscendC::GetRuntimeUBSize() / sizeof(half) / 2;
+uint32_t tileNum = totalLength / tileLength;
+```
+
+### BlockReduceMax / BlockReduceMin / BlockReduceSum
+
+对每个datablock内所有元素分别求最大值、最小值、求和。这些是SIMD层面的归约指令，在SIMD与SIMT混合编程场景中使用。
+
+- **BlockReduceMax**: 对每个datablock内所有元素求最大值
+- **BlockReduceMin**: 对每个datablock内所有元素求最小值
+- **BlockReduceSum**: 对每个datablock内所有元素求和（二叉树方式两两相加）
+
+支持的数据类型: half, float
+
+**函数原型** (mask连续模式):
+
+```cpp
+template <typename T, bool isSetMask = true>
+__aicore__ inline void BlockReduceMax(const LocalTensor<T>& dst, const LocalTensor<T>& src,
+    const int32_t repeatTime, const int32_t mask,
+    const int32_t dstRepStride, const int32_t srcBlkStride, const int32_t srcRepStride)
+```
+
+> 更多详细的参数说明（mask模式、stride语义等），请参考 AscendC SIMD API 文档。

package/assets/ops-direct-invoke/skills/ascendc-simt-best-practices/references/tensorlist-handling.md

@@ -0,0 +1,92 @@
+# TensorList 动态输入处理
+
+## 概述
+
+`ListTensorDesc` 是昇腾 C 算子开发中用于描述动态输入/动态输出列表的核心数据结构，主要用于核函数直调场景下手动管理多个 Tensor 的元信息与数据指针。
+
+## ListTensorDesc 内存布局
+
+```
+ListTensorDesc:
+├── ptrOffset (uint64_t)           // dataPtr 的偏移量
+├── tensorDesc[0] (TensorDesc)      // 第 0 个 tensor 的描述
+│   ├── dim (uint32_t)
+│   ├── index (uint32_t)
+│   └── shape[SHAPE_DIM] (uint64_t[])  // SHAPE_DIM 固定为 8
+├── tensorDesc[1] (TensorDesc)
+│   └── ...
+└── dataPtr[TENSOR_DESC_NUM] (uintptr_t[])  // 数据指针数组
+```
+
+## Host 侧获取 tensorlist 信息
+
+```cpp
+int32_t INPUT_IDX = 0;
+auto computeNodeInfoPtr = tilingContext_->GetComputeNodeInfo();
+auto idxInstanceInfoPtr = computeNodeInfoPtr.GetInputInstanceInfo(INPUT_IDX);
+uint64_t tensorNum = idxInstanceInfoPtr->GetInstanceNum();
+
+for (uint64_t i = 0; i < tensorNum; i++) {
+    auto idxTensorShapePtr = tilingContext_->GetDynamicInputShape(INPUT_IDX, i);
+    auto idxTensorShape = idxTensorShapePtr->GetStorageShape();
+    auto idxTensorDtypePtr = tilingContext_->GetDynamicInputDesc(INPUT_IDX, i);
+    auto idxDtype = idxTensorDtypePtr->GetDataType();
+}
+```
+
+### Host 侧 API
+
+| API | 说明 |
+|-----|------|
+| `GetInputInstanceInfo(ir_index)` | 获取输入实例化对象 |
+| `GetInstanceNum()` | 获取动态输入中实际 tensor 个数 |
+| `GetDynamicInputShape(dynamicInputIndex, tensorIndex)` | 获取指定 tensor 的 shape |
+| `GetDynamicInputDataType(dynamicInputIndex, tensorIndex)` | 获取指定 tensor 的 dtype |
+
+## Device 侧解析（方式一：SIMT VF 内部解析）
+
+```cpp
+// 获取第 idx 个 tensor 的 GM 地址
+__simt_callee__ inline __gm__ T* SimtGetTensorAddr(GM_ADDR tensorListPtr, int64_t idx) {
+    __gm__ uint64_t* dataAddr = reinterpret_cast<__gm__ uint64_t*>(tensorListPtr);
+    uint64_t tensorPtrOffset = *dataAddr;
+    __gm__ uint64_t* tensorPtr = dataAddr + (tensorPtrOffset >> 3);
+    return reinterpret_cast<__gm__ T*>(*(tensorPtr + idx));
+}
+
+// 获取第 idx 个 tensor 的第 dim 维大小
+__simt_callee__ inline uint64_t SimtGetTensorShape(GM_ADDR tensorListPtr, int64_t idx, uint32_t dim) {
+    uint32_t dimSize = *(reinterpret_cast<__gm__ uint64_t*>(tensorListPtr) + 1) & 0xffffffff;
+    uint32_t descStructSize = 1 + dimSize;
+    __gm__ uint64_t* shapeAddrStart = reinterpret_cast<__gm__ uint64_t*>(tensorListPtr) + 1 + descStructSize * idx;
+    __gm__ uint64_t* shapePtr = shapeAddrStart + 1 + dim;
+    return *shapePtr;
+}
+```
+
+## Device 侧解析（方式二：SIMT VF 外部解析）
+
+```cpp
+#include "kernel_operator_list_tensor_intf.h"
+
+using namespace AscendC;
+ListTensorDesc xList(reinterpret_cast<__gm__ void*>(x));
+
+// 获取各 tensor 地址
+__gm__ T* input0Addr = xList.GetDataPtr<T>(0);
+__gm__ T* input1Addr = xList.GetDataPtr<T>(1);
+
+// 获取各 tensor shape
+TensorDesc<T> desc;
+xList.GetDesc(desc, 0);
+uint64_t input0dim0 = desc.GetShape(0);
+```
+
+## 选择建议
+
+| tensor 个数 | 推荐方式 | 原因 |
+|------------|---------|------|
+| 有限且已知 | host 侧获取 shape → tilingdata 传递 | 简单直接 |
+| 不限或大量 | kernel 内直接解析 | 避免 tilingdata 传递大量 shape |
+
+> **注意**：tensor 的地址信息必须在 kernel 侧进行解析，禁止在 host 侧解析后通过 tilingdata 传递。

package/assets/ops-direct-invoke/skills/ascendc-simt-best-practices/references/thread-stride-pattern.md

@@ -0,0 +1,49 @@
+# 线程排布统一编程模式
+
+## 标准模式
+
+SIMT 算子采用统一的线程排布 for 循环模式，每个线程以 stride 间隔遍历数据：
+
+```cpp
+for (uint64_t index = static_cast<uint64_t>(
+         AscendC::Simt::GetBlockIdx() * AscendC::Simt::GetThreadNum() + AscendC::Simt::GetThreadIdx());
+     index < count;
+     index += (AscendC::Simt::GetThreadNum() * AscendC::Simt::GetBlockNum())) {
+    // 每个线程处理 stride 间隔的元素
+}
+```
+
+## 索引计算 API
+
+| API | 说明 |
+|-----|------|
+| `AscendC::Simt::GetThreadIdx()` | 当前线程索引 |
+| `AscendC::Simt::GetThreadNum()` | 纯线程总数 |
+| `AscendC::Simt::GetBlockIdx()` | 当前核索引 |
+| `AscendC::Simt::GetBlockNum()` | 核总数 |
+
+## 索引计算分解
+
+```
+初始 index = blockIdx * threadNum + threadIdx
+步进 stride = threadNum * blockNum
+```
+
+- 初始 index：将线程在全局中的起始位置线性化
+- 步进 stride：所有核所有线程的总数，确保每个元素只被一个线程处理
+
+## Select 算子示例
+
+```cpp
+template <typename T>
+__simt_vf__ __aicore__ LAUNCH_BOUND(2048) inline void OpSelectSimt(
+    int32_t needCoreNum, int32_t threadNum, int64_t currentCoreElements,
+    __gm__ uint8_t* condition, __gm__ T* x1, __gm__ T* x2, __gm__ T* y) {
+    for (uint64_t index = static_cast<uint64_t>(
+             AscendC::Simt::GetBlockIdx() * AscendC::Simt::GetThreadNum() + AscendC::Simt::GetThreadIdx());
+         index < count;
+         index += (AscendC::Simt::GetThreadNum() * AscendC::Simt::GetBlockNum())) {
+        y[index] = condition[index] ? x1[index] : x2[index];
+    }
+}
+```

package/assets/ops-direct-invoke/skills/ascendc-simt-best-practices/references/vf-call.md

@@ -0,0 +1,51 @@
+# VF_CALL 启动模式
+
+## 调用语法
+
+```cpp
+AscendC::Simt::VF_CALL<VFFunction>(AscendC::Simt::Dim3(thread_num), args...);
+```
+
+- `VFFunction`：要启动的 SIMT VF 函数（带模板参数）
+- `Dim3(thread_num)`：启动线程数，必须是编译期常量
+- `args...`：传递给 VF 函数的参数
+
+## 完整示例
+
+### Add 算子
+
+```cpp
+template <typename T>
+__simt_vf__ __aicore__ LAUNCH_BOUND(512) inline void OpComputeSimt(
+    uint64_t count, __gm__ T* x1, __gm__ T* x2, __gm__ T* y) {
+    for (uint64_t index = static_cast<uint64_t>(
+             AscendC::Simt::GetBlockIdx() * AscendC::Simt::GetThreadNum() + AscendC::Simt::GetThreadIdx());
+         index < count;
+         index += (AscendC::Simt::GetThreadNum() * AscendC::Simt::GetBlockNum())) {
+        y[index] = x1[index] + x2[index];
+    }
+}
+
+template <typename T>
+__aicore__ inline void Process(uint64_t count, GM_ADDR x1, GM_ADDR x2, GM_ADDR y) {
+    __gm__ T* x1_gm = (__gm__ T*) x1;
+    __gm__ T* x2_gm = (__gm__ T*) x2;
+    __gm__ T* y_gm = (__gm__ T*) y;
+    AscendC::Simt::VF_CALL<OpComputeSimt<T>>(
+        AscendC::Simt::Dim3(512), count, x1_gm, x2_gm, y_gm);
+}
+```
+
+### 纯 SIMT 算子 GM 地址传递
+
+纯 SIMT 算子应直接使用传入的 `GM_ADDR` 参数，避免申请 GlobalTensor 后 GetPhyAddr：
+
+```cpp
+// ✅ 推荐：直接转换
+__gm__ T* x_gm = (__gm__ T*) x;
+
+// ❌ 避免：不必要的 GlobalTensor 中转
+GlobalTensor<T> xGlobal;
+xGlobal.SetGlobalBuffer((__gm__ T*)x, count);
+auto phyAddr = xGlobal.GetPhyAddr();
+```

package/assets/ops-direct-invoke/skills/ascendc-simt-best-practices/references/vf-declaration.md

@@ -0,0 +1,39 @@
+# VF 函数声明模式
+
+## 声明规范
+
+```cpp
+__simt_vf__ __aicore__ LAUNCH_BOUND(thread_num) inline void YourKernel(...);
+```
+
+- 必须使用 `__simt_vf__` 标记
+- `LAUNCH_BOUND(thread_num)` 可选，默认 1024
+- 线程数必须是编译期常量（`constexpr` 或字面量）
+
+## 参数类型支持
+
+| 类型类别 | 支持类型 |
+|---------|---------|
+| 指针类型 | `__gm__ T*`, `__ubuf__ T*` |
+| 标量类型 | bool, int8_t, int16_t, int32_t, int64_t, uint8_t, uint16_t, uint32_t, uint64_t, float, half, bfloat16_t |
+| 返回值 | 必须是 void |
+
+## 完整声明示例
+
+```cpp
+template <typename T>
+__simt_vf__ __aicore__ LAUNCH_BOUND(512) inline void OpComputeSimt(
+    uint64_t count, __gm__ T* x1, __gm__ T* x2, __gm__ T* y) {
+    // SIMT kernel 实现
+}
+```
+
+## 常量线程数声明
+
+```cpp
+constexpr uint32_t THREAD_NUM = 512;
+
+__simt_vf__ __aicore__ LAUNCH_BOUND(THREAD_NUM) inline void OpComputeSimt(...);
+```
+
+- `LAUNCH_BOUND(THREAD_NUM)` 与 `Simt::Dim3(THREAD_NUM)` 必须使用同一个 `constexpr` 常量

package/assets/ops-direct-invoke/skills/ascendc-simt-best-practices/references//347/274/226/350/257/221/344/270/216/350/277/220/350/241/214.md

@@ -0,0 +1,158 @@
+# 编译与运行
+
+异构编译场景下算子编译与运行的速查，涵盖 AI Core SIMT 与 AI CPU 两类核函数的 bisheng 命令行 / CMake 编译方式。内容整理自 CANN 官方 Ascend C 编程指南，完整官方文档见文末。
+
+## 异构编译
+
+基于昇腾处理器的异构系统包含 Host CPU 与 NPU Device 两部分。应用程序通常由 Host 代码（标准 C/C++）与 Device 侧核函数（Ascend C）组成。Host 代码与核函数可编写在同一个 `.asc` 源文件中，由毕昇编译器（可执行文件 `bisheng`）编译生成可执行文件，该编译方式称为**异构编译**。异构编译场景中，Host 侧通过内核调用符 `<<<...>>>` 启动核函数：
+
+```cpp
+// main.asc：Host 代码与核函数位于同一源文件
+__global__ __aicore__ void add_custom(__gm__ float* x, __gm__ float* y, __gm__ float* z)
+{
+    // kernel 实现
+}
+
+int main()
+{
+    // aclInit / aclrtSetDevice / aclrtCreateStream 等初始化
+    add_custom<<<numBlocks, nullptr, stream>>>(x, y, z);
+    aclrtSynchronizeStream(stream);
+    // 资源释放
+    return 0;
+}
+```
+
+> [debug-api.md](debug-api.md) 中 AI CPU 的 assert/printf 等调测接口仅支持通过 `<<<...>>>` 调用，即用于异构编译场景。
+
+## AI Core SIMT 编译
+
+### bisheng 命令行
+
+在 AI Core SIMD 编译命令的基础上增加 `--enable-simt` 选项：
+
+```shell
+bisheng <source_file>.asc -o <output_file> --npu-arch=dav-<npu architecture> --enable-simt
+```
+
+编译流程：Host 代码编译成 Host 二进制，SIMT 代码编译成 SIMT 二进制并链接成 Fatbin 文件，再与 Host 二进制合并生成可执行二进制。
+
+常用编译命令汇总：
+
+| 编译方式 | AI Core SIMT 编译命令 |
+|-|-|
+| 异构编译 | `bisheng <source_file>.asc -o <output_file> --npu-arch=dav-<npu architecture> --enable-simt` |
+| 单独编译 | `bisheng -dc <source_file>.asc -o <output_file>.o --npu-arch=dav-<npu architecture> --enable-simt` |
+| 动态库编译 | `bisheng -shared <source_file>.asc -o <output_file>.so --npu-arch=dav-<npu architecture> --enable-simt -fPIC` |
+| 静态库编译 | `bisheng -lib <source_file>.asc -o <output_file>.a --npu-arch=dav-<npu architecture> --enable-simt` |
+
+常用编译选项：
+
+| 选项 | 是否必需 | 说明 |
+|------|----------|------|
+| --npu-arch | 是 | 指定 AI 处理器架构，取值 `dav-<arch-version>`，架构版本号与产品型号的对应关系见官方文档 |
+| --enable-simt | 否 | SIMT 编程场景，指定 SIMT 方式编译 |
+| -c | 否 | 编译生成目标文件 |
+| -dc | 否 | 编译生成 relocatable 目标文件，启用跨编译单元的设备代码链接 |
+| -shared | 否 | 编译生成动态链接库 |
+| -lib | 否 | 编译生成静态链接库 |
+| -fPIC | 否 | 生成位置无关代码（动态库场景） |
+
+### CMake 方式
+
+在 `find_package(ASC)` 前将 `CMAKE_ASC_ENABLE_SIMT` 设置为 ON 启用 SIMT 编译模式（编译命令中自动注入 `--enable-simt`）：
+
+```cmake
+# 指定 NPU 架构版本，可通过 -DCMAKE_ASC_ARCHITECTURES=dav-xxxx 覆盖
+set(CMAKE_ASC_ARCHITECTURES "dav-3510" CACHE STRING "NPU architecture")
+# 启用 SIMT 编译模式，需要在 find_package(ASC) 前设置
+set(CMAKE_ASC_ENABLE_SIMT ON)
+
+find_package(ASC)
+project(kernel_samples LANGUAGES ASC)
+
+add_executable(demo
+    add_custom.asc
+)
+```
+
+## AI CPU 算子编译
+
+AI CPU 算子需要同时包含 `.aicpu` 文件（核函数定义）与 `.asc` 文件（Host 侧通过内核调用符调用核函数）才能编译生成可执行文件。
+
+### bisheng 命令行
+
+以 Hello World 打印样例为例：
+
+```cpp
+// hello_world.aicpu：AI CPU 核函数定义
+#include "aicpu_api.h"
+
+__global__ __aicpu__ uint32_t hello_world(void *args)
+{
+    AscendC::printf("Hello World!!!\n");
+    return 0;
+}
+```
+
+```cpp
+// main.asc：Host 侧通过内核调用符调用 AI CPU 核函数
+extern __global__ __aicpu__ uint32_t hello_world(void *args);
+
+// 启动核函数
+hello_world<<<numBlocks, nullptr, stream>>>(&args, sizeof(KernelArgs));
+```
+
+编译命令：
+
+```shell
+bisheng -O2 hello_world.aicpu --cce-aicpu-L${INSTALL_DIR}/lib64/device/lib64 --cce-aicpu-laicpu_api -I${INSTALL_DIR}/asc/include/aicpu_api -c -o hello_world.aicpu.o
+bisheng --npu-arch=dav-2201 main.asc -c -o main.asc.o
+bisheng hello_world.aicpu.o main.asc.o -o demo
+```
+
+`${INSTALL_DIR}` 请替换为 CANN 软件安装后文件存储路径。以 root 用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。
+
+要点：
+
+- 编译 `.aicpu` 时，通过 `-I` 指定依赖头文件路径；通过 `--cce-aicpu-laicpu_api` 为 Device 链接依赖库 libaicpu_api.a，通过 `--cce-aicpu-L` 指定库路径。
+- 编译 `.asc` 时，通过 `--npu-arch` 指定对应的架构版本号。
+- 单独编译 AI CPU 算子生成动态库/静态库时，需手动链接依赖库（如 ascendc_runtime、ascendcl、runtime 等）。
+
+### CMake 方式
+
+```cmake
+cmake_minimum_required(VERSION 3.16)
+find_package(ASC REQUIRED)
+find_package(AICPU REQUIRED)
+
+# ASC 表示使用毕昇编译器编译 Ascend C，AICPU 表示使用毕昇编译器编译 AI CPU 算子
+project(kernel_samples LANGUAGES ASC AICPU CXX)
+
+add_executable(demo
+    hello_world.aicpu
+    main.asc
+)
+
+# 存在 ASC 与 AI CPU 两种语言时，需指定链接器语言
+set_target_properties(demo PROPERTIES LINKER_LANGUAGE ASC)
+
+target_compile_options(demo PRIVATE
+    # --npu-arch 指定 NPU 架构版本；该选项仅对 ASC 语言生效
+    $<$<COMPILE_LANGUAGE:ASC>:--npu-arch=dav-2201>
+)
+```
+
+## 运行流程
+
+异构编译生成的可执行文件，典型运行流程为：
+
+1. `aclInit` / `aclrtSetDevice` / `aclrtCreateStream` 初始化资源；
+2. Host Memory 与 Device Memory 之间拷贝输入数据；
+3. 通过 `<<<...>>>` 启动 Device 侧核函数，`aclrtSynchronizeStream` 等待执行完成；
+4. 将结果数据从 Device Memory 拷回 Host Memory；
+5. `aclrtDestroyStream` / `aclrtResetDevice` / `aclFinalize` 释放资源。
+
+## 官方文档
+
+《编译与运行》完整内容（毕昇编译器、AI Core/AI CPU 算子编译、RTC 运行时编译、异步执行、约束说明等）请通过 `ascendc-docs-search` skill 查阅 `$ASC_DEVKIT_DIR/docs/zh/guide/programming_guide/compilation_and_execution/`。

package/assets/ops-direct-invoke/skills/ascendc-simt-tiling-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ascendc-simt-tiling-design
+description: AscendC SIMT 算子切分设计指南。提供 SIMT 算子独有的核数切分、线程数设置、DCache/UB空间分配方法。SIMT切分与SIMD完全不同（线程级并行 vs 向量级UB切分），本skill聚焦SIMT切分范式。触发：设计SIMT算子Tiling策略、设置SIMT线程数、规划SIMT核数切分时。
+---
+
+# SIMT 算子切分设计指南
+
+SIMT 算子的切分设计与 SIMD 有本质差异。SIMD 以 UB 切分 + Buffer 规划为核心，SIMT 以核数切分 + 线程数设置为核心，不涉及 UB 切分和 Buffer 规划。
+
+> **SIMD 算子 Tiling 设计**请参考 `ascendc-tiling-design` skill。
+
+## SIMT vs SIMD 切分差异速查
+
+| 要素 | SIMD | SIMT |
+|------|------|------|
+| 多核切分 | 按 UB 单次处理量切分 | 按元素总量切分（ceil(总量/单核最少元素数)） |
+| 单核并行 | UB Buffer + 向量指令 | 线程数（constexpr 编译期常量） |
+| 数据搬运 | 需显式 Load/Store | 支持直接读写 GM |
+| UB 使用 | 全量使用 | 仅核内共享场景使用，DCache >= 32KB |
+| Buffer 规划 | inQueue/outQueue/tmpBuf | TBuf（仅在需要共享内存时使用） |
+
+详细设计指南：[references/guide.md](references/guide.md)
+
+## 核心设计要素
+
+### 1. 核数切分策略
+
+- 总核数 = ceil(输出元素总数 / 单核最少处理元素数)
+- 单核最少处理元素数建议 1024，需对 warp(32) 对齐
+- 通过 tiling 侧 `SetBlockDim` 设置核数
+
+### 2. 线程数设置策略
+
+- 默认 1024，最大 2048，必须是 `constexpr` 编译期常量
+- `LAUNCH_BOUND(N)` 与 `Simt::Dim3(N)` 必须使用同一个常量
+- 禁止从 tiling 数据动态获取线程数
+
+### 3. DCache 与 UB 空间分配
+
+- SIMT 算子 DCache 必须 >= 32KB
+- 可用 UB = 256KB - 8KB - 32KB = 216KB
+- tiling 侧通过 `SetLocalMemorySize` 设置