ascendc-operator-project-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AscendC 算子工程初始化

AscendC Operator Project Initialization

Skill类型：流程导向型（多阶段工作流，阶段检查点）

快速创建 Ascend-Kernel 算子工程，所有算子统一生成在

csrc/ops

目录下，并保证后续可直接进入设计/编码/编译测试阶段。

Skill Type: Process-oriented (multi-stage workflow with stage checkpoints)

Quickly create an Ascend-Kernel operator project, where all operators are uniformly generated under the

csrc/ops

directory, ensuring that subsequent design/coding/compilation testing stages can be directly entered.

核心原则

Core Principles

单一目录：所有算子统一生成在
```
csrc/ops
```
目录下
安全优先：自动检查目录是否存在，避免覆盖现有文件
命名规范：严格要求snake_case命名格式
项目检测：优先使用现有ascend-kernel项目，不存在则复制模板
结果可验证：输出目录结构、注册变更点、构建测试命令
防坑内建：显式提示 CMake 三处更新、
```
EXEC_KERNEL_CMD
```
左值要求、环境依赖

Single Directory: All operators are uniformly generated under the
```
csrc/ops
```
directory
Security First: Automatically check if the directory exists to avoid overwriting existing files
Naming Convention: Strictly require snake_case naming format
Project Detection: Prioritize using existing ascend-kernel projects; copy the template if it does not exist
Verifiable Results: Output directory structure, registration change points, and build/test commands
Built-in Pitfall Prevention: Explicitly prompt for three CMake updates, left-value requirements for
```
EXEC_KERNEL_CMD
```
, and environment dependencies

工作流程

Workflow

dot

digraph project_init {
    rankdir=TB;
    node [shape=box];

    start [label="用户请求创建算子" shape=ellipse];
    detect_ascend_kernel [label="检测ascend-kernel项目是否存在" shape=diamond];
    detect_ops [label="检测csrc/ops/目录是否存在" shape=diamond];
    copy_template [label="复制ascend-kernel项目模板到当前目录"];
    create_ops_dir [label="创建csrc/ops目录"];
    collect [label="收集算子信息"];
    check_path [label="检查目标算子路径是否存在" shape=diamond];
    show_exists [label="提示路径已存在，询问是否更换"];
    show_result [label="展示目录结构和下一步指引"];

    start -> detect_ascend_kernel;
    detect_ascend_kernel -> detect_ops [label="存在"];
    detect_ascend_kernel -> copy_template [label="不存在"];
    copy_template -> collect;
    detect_ops -> collect [label="存在ops/"];
    detect_ops -> create_ops_dir [label="不存在ops/"];
    create_ops_dir -> collect;
    collect -> check_path;
    check_path -> show_exists [label="存在"];
    show_exists -> collect [label="更换名称"];
    check_path -> show_result [label="不存在"];
}

dot

digraph project_init {
    rankdir=TB;
    node [shape=box];

    start [label="用户请求创建算子" shape=ellipse];
    detect_ascend_kernel [label="检测ascend-kernel项目是否存在" shape=diamond];
    detect_ops [label="检测csrc/ops/目录是否存在" shape=diamond];
    copy_template [label="复制ascend-kernel项目模板到当前目录"];
    create_ops_dir [label="创建csrc/ops目录"];
    collect [label="收集算子信息"];
    check_path [label="检查目标算子路径是否存在" shape=diamond];
    show_exists [label="提示路径已存在，询问是否更换"];
    show_result [label="展示目录结构和下一步指引"];

    start -> detect_ascend_kernel;
    detect_ascend_kernel -> detect_ops [label="存在"];
    detect_ascend_kernel -> copy_template [label="不存在"];
    copy_template -> collect;
    detect_ops -> collect [label="存在ops/"];
    detect_ops -> create_ops_dir [label="不存在ops/"];
    create_ops_dir -> collect;
    collect -> check_path;
    check_path -> show_exists [label="存在"];
    show_exists -> collect [label="更换名称"];
    check_path -> show_result [label="不存在"];
}

反模式清单（NEVER DO THESE）

Anti-Pattern Checklist (NEVER DO THESE)

❌ 不要在非csrc/ops目录下生成算子
❌ 不要覆盖已存在的算子目录
❌ 不要使用除snake_case外的其他命名格式
❌ 不要跳过目录存在性检查
❌ 不要只创建算子目录而不创建
```
op_host/
```
和
```
op_kernel/
```
❌ 不要忘记更新
```
ops.h
```
、
```
register.cpp
```
、
```
csrc/CMakeLists.txt
```
（三处）
❌ 不要在
```
EXEC_KERNEL_CMD
```
中直接传右值临时变量
❌ 不要使用 ACLNN 作为新算子实现路径

❌ Do not generate operators outside the csrc/ops directory
❌ Do not overwrite existing operator directories
❌ Do not use naming formats other than snake_case
❌ Do not skip directory existence checks
❌ Do not only create operator directories without creating
```
op_host/
```
and
```
op_kernel/
```
❌ Do not forget to update
```
ops.h
```
,
```
register.cpp
```
, and
```
csrc/CMakeLists.txt
```
(three places)
❌ Do not directly pass right-value temporary variables in
```
EXEC_KERNEL_CMD
```
❌ Do not use ACLNN as the implementation path for new operators

步骤1：检测并初始化Ascend-Kernel项目

Step 1: Detect and Initialize Ascend-Kernel Project

1.1 检测Ascend-Kernel项目位置

1.1 Detect Ascend-Kernel Project Location

检测策略：

检查当前目录是否为ascend-kernel项目（包含build.sh、CMakeLists.txt、csrc/）
检查当前目录下的ascend-kernel子目录
检查一级子目录中的ascend-kernel项目

执行命令：

bash

bash <skill_dir>/scripts/detect_ascend_kernel_project.sh

Detection Strategy:

Check if the current directory is an ascend-kernel project (contains build.sh, CMakeLists.txt, csrc/)
Check the ascend-kernel subdirectory under the current directory
Check ascend-kernel projects in first-level subdirectories

Execution Command:

bash

bash <skill_dir>/scripts/detect_ascend_kernel_project.sh

1.2 处理检测结果

1.2 Process Detection Results

检测结果	处理方式
`PROJECT_FOUND:<path>`	使用现有项目，继续步骤2
`PROJECT_FOUND_NO_OPS:<path>`	在项目中创建csrc/ops/目录，继续步骤2
`PROJECT_NOT_FOUND`	复制ascend-kernel模板到当前目录，继续步骤2
`MULTIPLE_PROJECTS:<path1> <path2> ...`	列出所有项目，让用户选择

Detection Result	Processing Method
`PROJECT_FOUND:<path>`	Use the existing project and proceed to Step 2
`PROJECT_FOUND_NO_OPS:<path>`	Create the csrc/ops/ directory in the project and proceed to Step 2
`PROJECT_NOT_FOUND`	Copy the ascend-kernel template to the current directory and proceed to Step 2
`MULTIPLE_PROJECTS:<path1> <path2> ...`	List all projects and let the user select

1.3 复制项目模板（如果需要）

1.3 Copy Project Template (if needed)

执行命令：

bash

cp -r "<skill_dir>/templates/ascend-kernel" ./ascend-kernel
chmod +x ./ascend-kernel/build.sh

重要：复制后必须

chmod +x build.sh

，否则编译时会报

Permission denied

。

验证：确认ascend-kernel目录包含：

build.sh（且有执行权限）
CMakeLists.txt
csrc/ 目录

Execution Command:

bash

cp -r "<skill_dir>/templates/ascend-kernel" ./ascend-kernel
chmod +x ./ascend-kernel/build.sh

Important: Must run

chmod +x build.sh

after copying, otherwise a

Permission denied

error will occur during compilation.

Verification: Confirm that the ascend-kernel directory contains:

build.sh (with execution permission)
CMakeLists.txt
csrc/ directory

步骤2：收集算子信息（最小必填）

Step 2: Collect Operator Information (Minimum Required)

必须确认的信息：

信息	格式要求	说明
算子名称	snake_case	如 `rms_norm` , `flash_attn`

确认信息：

=== Ascend-Kernel算子信息 ===
算子名称: <op_name>
生成路径: <ascend_kernel_path>/csrc/ops/<op_name>

确认创建？[Y/n]

Mandatory Information to Confirm:

Information	Format Requirement	Description
Operator Name	snake_case	e.g., `rms_norm` , `flash_attn`

Confirmation Message:

=== Ascend-Kernel Operator Information ===
Operator Name: <op_name>
Generation Path: <ascend_kernel_path>/csrc/ops/<op_name>

Confirm creation? [Y/n]

步骤3：检查前置条件

Step 3: Check Preconditions

确认在ascend-kernel项目根目录下（build.sh存在且有执行权限）
确认csrc/ops/目录存在（不存在则创建
```
mkdir -p csrc/ops
```
）
确认目标目录
```
csrc/ops/<op_name>
```
不存在

Confirm being in the root directory of the ascend-kernel project (build.sh exists and has execution permission)
Confirm that the csrc/ops/ directory exists (create it with
```
mkdir -p csrc/ops
```
if it does not exist)
Confirm that the target directory
```
csrc/ops/<op_name>
```
does not exist

步骤4：创建算子骨架

Step 4: Create Operator Skeleton

创建目录：

bash

mkdir -p csrc/ops/<op_name>/op_host csrc/ops/<op_name>/op_kernel

在

csrc/ops/<op_name>/

下创建以下文件：

csrc/ops/<op_name>/
├── CMakeLists.txt
├── design.md                  # 设计文档占位（由 design skill 填充）
├── op_host/
│   └── <op_name>.cpp          # Host 占位（由 code-gen skill 替换）
└── op_kernel/
    └── <op_name>.cpp          # Kernel 占位（由 code-gen skill 替换）

Create Directories:

bash

mkdir -p csrc/ops/<op_name>/op_host csrc/ops/<op_name>/op_kernel

Create the following files under

csrc/ops/<op_name>/

csrc/ops/<op_name>/
├── CMakeLists.txt
├── design.md                  # Design document placeholder (to be filled by design skill)
├── op_host/
│   └── <op_name>.cpp          # Host placeholder (to be replaced by code-gen skill)
└── op_kernel/
    └── <op_name>.cpp          # Kernel placeholder (to be replaced by code-gen skill)

4.1 文件内容最小模板

4.1 Minimum File Templates

```
CMakeLists.txt
```

cmake

ascendc_add_operator(OP_NAME <op_name>)

```
op_host/<op_name>.cpp
```

包含 BSD 3-Clause 头
include
```
torch_kernel_helper.h
```
include
```
aclrtlaunch_<op_name>.h
```

提供

namespace ascend_kernel { at::Tensor <op_name>(...) { ... } }

占位

```
op_kernel/<op_name>.cpp
```

包含 BSD 3-Clause 头
include
```
kernel_operator.h
```

提供

extern "C" __global__ __aicore__ void <op_name>(...)

占位

```
CMakeLists.txt
```

cmake

ascendc_add_operator(OP_NAME <op_name>)

```
op_host/<op_name>.cpp
```

Includes BSD 3-Clause header
Includes
```
torch_kernel_helper.h
```
Includes
```
aclrtlaunch_<op_name>.h
```

Provides placeholder for

namespace ascend_kernel { at::Tensor <op_name>(...) { ... } }

```
op_kernel/<op_name>.cpp
```

Includes BSD 3-Clause header
Includes
```
kernel_operator.h
```

Provides placeholder for

extern "C" __global__ __aicore__ void <op_name>(...)

步骤5：注册提醒（必须执行但不在本 skill 自动改代码）

Step 5: Registration Reminders (Must be Executed but Not Automatically Modified in This Skill)

初始化完成后，明确提示用户/后续 skill 更新以下三处：

```
csrc/ops.h
```
：添加函数声明
```
csrc/register.cpp
```
：添加
```
m.def
```
与
```
m.impl
```
```
csrc/CMakeLists.txt
```
：
- ```
OP_SRCS
```
  添加 host 文件
- ```
ascendc_library(...)
```
  添加 kernel 文件
- 若模板中存在同名 ACLNN 封装，必须移除对应
```
aclnn/<op>.cpp
```

说明：这是实战最高频遗漏点，必须在初始化阶段提前提示。

After initialization, explicitly prompt the user/subsequent skills to update the following three places:

```
csrc/ops.h
```
: Add function declarations
```
csrc/register.cpp
```
: Add
```
m.def
```
and
```
m.impl
```
```
csrc/CMakeLists.txt
```
:
- Add host files to
```
OP_SRCS
```
- Add kernel files to
```
ascendc_library(...)
```
- If there is a duplicate ACLNN wrapper in the template, the corresponding
```
aclnn/<op>.cpp
```
  must be removed

Note: This is the most frequently missed point in practice, so it must be prompted in advance during the initialization phase.

步骤6：展示项目结构与下一步

Step 6: Display Project Structure and Next Steps

提示用户：

Ascend-Kernel项目初始化成功！

项目结构:
<ascend_kernel_path>/
├── build.sh                    # 构建脚本
├── CMakeLists.txt              # CMake配置
├── csrc/
│   ├── ops/                    # 算子目录
│   ├── aclnn/                  # ACLNN算子封装
│   ├── utils/                  # 工具类
│   ├── ops.h                   # 算子声明
│   └── register.cpp            # 算子注册
├── python/                     # Python包
└── tests/                      # 测试用例

下一步操作：
 调用 ascendc-operator-design skill 完成设计文档

Prompt User:

Ascend-Kernel project initialization succeeded!

Project Structure:
<ascend_kernel_path>/
├── build.sh                    # Build script
├── CMakeLists.txt              # CMake configuration
├── csrc/
│   ├── ops/                    # Operator directory
│   ├── aclnn/                  # ACLNN operator wrapper
│   ├── utils/                  # Utility classes
│   ├── ops.h                   # Operator declarations
│   └── register.cpp            # Operator registration
├── python/                     # Python package
└── tests/                      # Test cases

Next Steps:
  Call ascendc-operator-design skill to complete the design document

注意事项

Notes

算子名称只能包含字母、数字和下划线
系统会自动检查目录是否存在，避免覆盖
如果当前目录没有ascend-kernel项目，系统会自动复制模板
新算子必须使用 AscendC 路径，禁止 ACLNN 实现路径
```
EXEC_KERNEL_CMD
```
参数必须是左值；如
```
double
```
先转
```
float
```
局部变量再传
测试基线建议以 PyTorch 参考实现为准，CPU 不支持的 dtype（如部分 fp16 pooling）需转 float32 对比

Operator names can only contain letters, numbers, and underscores
The system will automatically check if the directory exists to avoid overwriting
If there is no ascend-kernel project in the current directory, the system will automatically copy the template
New operators must use the AscendC path; ACLNN implementation path is prohibited
```
EXEC_KERNEL_CMD
```
parameters must be left-values; e.g., convert
```
double
```
to a local float variable before passing
It is recommended to use PyTorch reference implementation as the test baseline; for dtypes not supported by CPU (such as some fp16 pooling), convert to float32 for comparison

交付标准（DoD）

Definition of Done (DoD)

完成本 skill 后，至少应满足：

已定位或创建
```
ascend-kernel
```
项目
已创建
```
csrc/ops/<op_name>/
```
标准骨架
已明确三处注册更新点（
```
ops.h
```
/
```
register.cpp
```
/
```
csrc/CMakeLists.txt
```
）
已给出可执行的构建、安装、测试命令
已提示关键防坑项（环境、左值参数、CMake 三处更新）

After completing this skill, at least the following requirements should be met:

Located or created the
```
ascend-kernel
```
project
Created the standard skeleton for
```
csrc/ops/<op_name>/
```
Identified three registration update points (
```
ops.h
```
/
```
register.cpp
```
/
```
csrc/CMakeLists.txt
```
)
Provided executable build, installation, and test commands
Prompted key pitfall prevention items (environment, left-value parameters, three CMake updates)