ascendc-operator-project-init

AscendC operator project initialization

Skill type: process-oriented (multi-stage workflow, stage checkpoints)

Quickly create an Ascend-Kernel operator project; all operators are uniformly generated under the csrc/ops directory, and it is ensured that the subsequent design/coding/compilation testing stages can be entered directly.

Core principles

1. Single directory: all operators are uniformly generated under the csrc/ops directory
2. Safety first: automatically check whether the directory exists to avoid overwriting existing files
3. Naming convention: strictly require the snake_case naming format
4. Project detection: prioritize using an existing ascend-kernel project; if it does not exist, copy the template
5. Verifiable results: output the directory structure, registration change points, and build test commands
6. Built-in pitfall prevention: explicitly prompt for the three CMake updates,EXEC_KERNEL_CMD lvalue requirements, environment dependencies

Workflow

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="不存在"];
}

Anti-pattern checklist (NEVER DO THESE)

• ❌ Do not generate operators outside the csrc/ops directory
• ❌ Do not overwrite an existing operator directory
• ❌ Do not use any naming format other than snake_case
• ❌ Do not skip the directory existence check
• ❌ Do not create only the operator directory without creating op_host/ and op_kernel/
• ❌ Do not forget to update ops.h、register.cpp、csrc/CMakeLists.txt(three places)
• ❌ Do not, in EXEC_KERNEL_CMD , directly pass an rvalue temporary variable
• ❌ Do not use ACLNN as the implementation path for a new operator

Step 1: Detect and initialize the Ascend-Kernel project

1.1 Detect the Ascend-Kernel project location

Detection strategy：

1. Check whether the current directory is an ascend-kernel project (contains build.sh, CMakeLists.txt, csrc/)
2. Check the ascend-kernel subdirectory under the current directory
3. Check for an ascend-kernel project in first-level subdirectories

Execute command：

bash <skill_dir>/scripts/detect_ascend_kernel_project.sh

1.2 Process the detection result

Detection result	Handling method
PROJECT_FOUND:<path>	Use the existing project and continue to step 2
PROJECT_FOUND_NO_OPS:<path>	Create the csrc/ops/ directory in the project and continue to step 2
PROJECT_NOT_FOUND	Copy the ascend-kernel template to the current directory and continue to step 2
MULTIPLE_PROJECTS:<path1> <path2> ...	List all projects and let the user choose

1.3 Copy the project template (if needed)

Execute command：

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

Important: after copying, you must chmod +x build.sh, otherwise compilation will report Permission denied。

Verification: confirm that the ascend-kernel directory contains:

• build.sh (and it has execute permission)
• CMakeLists.txt
• csrc/ directory

Step 2: Collect operator information (minimum required)

Information that must be confirmed：

Information	Format requirement	Description
Operator name	snake_case	such as rms_norm, flash_attn

Confirmation Information：

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

确认创建？[Y/n]

Step 3: Check Prerequisites

1. Confirm you are in the ascend-kernel project root directory (build.sh exists and has execute permission)
2. Confirm the csrc/ops/ directory exists (if it does not exist, create it mkdir -p csrc/ops）
3. Confirm the target directory csrc/ops/<op_name> does not exist

Step 4: Create Operator Skeleton

Create Directory：

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

Under csrc/ops/<op_name>/ create the following files:

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 替换）

4.1 Minimal File Content Template

1. CMakeLists.txt

ascendc_add_operator(OP_NAME <op_name>)

1. op_host/<op_name>.cpp

• Include BSD 3-Clause header
• include torch_kernel_helper.h
• include aclrtlaunch_<op_name>.h
• Provide namespace ascend_kernel { at::Tensor <op_name>(...) { ... } } placeholder

1. op_kernel/<op_name>.cpp

• Include BSD 3-Clause header
• include kernel_operator.h
• Provide extern "C" __global__ __aicore__ void <op_name>(...) placeholder

Step 5: Registration Reminders (must be performed but this skill does not automatically modify code)

After initialization is complete, clearly remind the user/subsequent skills to update the following three places:

1. csrc/ops.h: Add function declaration
2. csrc/register.cpp: Add m.def and m.impl
3. csrc/CMakeLists.txt：
   • OP_SRCS Add host file
   • ascendc_library(...) Add kernel file
   • If a same-named ACLNN wrapper exists in the template, the corresponding aclnn/<op>.cpp

Note: This is the most frequently missed point in practice and must be reminded in advance during the initialization phase.

Step 6: Show Project Structure and Next Steps

Remind the user：

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 完成设计文档

Notes

• Operator names may contain only letters, digits, and underscores
• The system automatically checks whether the directory exists to avoid overwriting
• If the current directory does not contain an ascend-kernel project, the system automatically copies the template
• New operators must use the AscendC path; the ACLNN implementation path is prohibited
• EXEC_KERNEL_CMD The parameter must be an lvalue; if double First convert float local variable and then pass it
• For test baselines, it is recommended to use the PyTorch reference implementation as the standard; dtypes not supported on CPU (such as some fp16 pooling) need to be converted to float32 for comparison

Definition of Done (DoD)

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

• Located or created ascend-kernel project
• Created csrc/ops/<op_name>/ standard skeleton
• Clarified the three registration update points (ops.h / register.cpp / csrc/CMakeLists.txt）
• Provided executable build, install, and test commands
• Highlighted key pitfalls (environment, lvalue parameters, three CMake updates)