前言

要做昇腾NPU算子开发，但不知道从哪入手？Ascend C代码写完了，不知道怎么编译、怎么调试、怎么验证？asc-tools就是为这个场景准备的。

asc-tools是昇腾官方提供的算子开发工具集，包含了编译工具（ascendc++）、调试工具（adb/gdb）、验证工具（acl soot）等，一站式解决算子开发的全流程问题。第一次用它的时候，被它的"一条命令搞定编译"震撼到了——不用配环境变量，不用写Makefile，只要ascendc++ my_op.cpp -o my_op.so，就搞定了。

本文是手把手实战——会从asc-tools的安装讲起，一步步带你在昇腾NPU上写、编译、调试、验证一个简单的VectorAdd算子。

asc-tools在CANN五层架构里的位置

先说清楚asc-tools住在哪。昇腾CANN的架构分五层，asc-tools住在第2层——昇腾计算服务层，具体是工具与开发套件里的算子开发工具集。

第1层：昇腾计算语言层 AscendCL
  └─ 算子开发接口 Ascend C

第2层：昇腾计算服务层 ← asc-tools 住在这
  ├─ AOL 算子库
  ├─ AOE 调优引擎
  └─ asc-tools（算子开发工具集）← 本文主角

第3层：昇腾计算编译层
  ├─ Graph Compiler 图编译器
  └─ BiSheng / ATC 编译器

第4层：昇腾计算执行层
  ├─ Runtime 运行时
  ├─ Graph Executor 图执行器
  ├─ HCCL 集合通信库
  └─ AIPP / DVPP

第5层：昇腾计算基础层
  ├─ RMS/CMS/DMS/DRV
  └─ SVM/VM/HDC

硬件层：昇腾 AI 硬件（达芬奇架构）

为啥住第2层？因为asc-tools是"开发工具"，是给算子开发者用的，不是给最终用户用的。可以把它理解成"昇腾CANN的SDK"——包含编译、调试、验证工具，让算子开发更简单。

依赖关系

asc-tools → driver → hardware（NPU）。asc-tools依赖driver提供的接口，driver依赖NPU硬件。

环境准备：安装asc-tools

要用asc-tools，先要安装它。

方式1：pip安装（推荐）

# pip安装asc-tools
pip install ascend-ascend-tools -i https://pypi.ascend.com/simple/

# 验证安装成功
ascendc --version

# 预期输出（示例）
# ascend-ascend-tools 1.2.0
# Copyright (C) 2024 Ascend

方式2：源码编译安装

# 克隆asc-tools仓库
git clone https://atomgit.com/cann/asc-tools.git

# 编译安装
cd asc-tools
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install

# 验证安装成功
ascendc --version

方式3：Docker镜像

# 拉取昇腾CANN开发镜像（已包含asc-tools）
docker pull ascendcr.jfrog.io/ascend/ascend-cann-toolkit:8.0

# 运行容器
docker run -it ascendcr.jfrog.io/ascend/ascend-cann-toolkit:8.0

# 验证安装成功
ascendc --version

逐步推进：asc-tools的4个使用步骤

asc-tools的使用分4步，一步步拆。

步骤1：写Ascend C代码

用asc-tools的第一步，是写Ascend C代码。Ascend C是昇腾CANN的算子编程语言，基于C++，针对达芬奇架构做了扩展。

代码讲解（VectorAdd算子）：

// vector_add.cpp
#include "ascend_c/ascend_c.h"

using namespace ascend::c;

// VectorAdd算子类
class VectorAdd : public KernelOperator {
public:
    // 初始化算子参数
    void Init(int32_t element_count) {
        element_count_ = element_count;
        
        // 绑定输入输出buffer
        x_buffer_.Bind(this, "x");  // 输入x
        y_buffer_.Bind(this, "y");  // 输入y
        z_buffer_.Bind(this, "z");  // 输出z
        
        // 设置输出shape
        z_buffer_.SetShape({element_count_});
    }
    
    // 算子主体
    void Compute() {
        // 分配LocalTensor
        auto x_local = x_buffer_.GetLocal();
        auto y_local = y_buffer_.GetLocal();
        auto z_local = z_buffer_.GetLocal();
        
        // VectorAdd计算
        for (int i = 0; i < element_count_; i++) {
            z_local.SetValue(i, x_local.GetValue(i) + y_local.GetValue(i));
        }
        
        // 同步数据到GlobalTensor
        z_buffer_.SyncToGlobal();
    }
    
private:
    int32_t element_count_;
    InputBuffer<x_buffer_, Tensor> x_buffer_;
    InputBuffer<y_buffer_, Tensor> y_buffer_;
    OutputBuffer<z_buffer_, Tensor> z_buffer_;
};

// 算子注册（框架自动调用）
REGISTER_OP("VectorAdd")
    .Input(x)
    .Input(y)
    .Output(z)
    .Attr(element_count, Int)
    .SetKernelFunc([](const OpKernelInput& input, OpKernelOutput& output) {
        VectorAdd op;
        op.Init(input.GetAttr<int32_t>("element_count"));
        op.Compute();
        return 0;
    });

代码讲解：

• class VectorAdd：VectorAdd算子类，继承自KernelOperator
• Init()：初始化算子参数，绑定输入输出buffer
• Compute()：算子主体，做VectorAdd计算
• REGISTER_OP()：注册算子，告诉框架这个算子叫什么、输入输出是什么

⚠️ 踩坑预警：Ascend C的语法和标准C++有差异（比如__aicore__关键字、LocalTensor/GlobalTensor等），要仔细看文档。

步骤2：编译Ascend C代码

代码写完了，第二步是编译。asc-tools提供了ascendc++编译器，是gcc的昇腾版本，针对达芬奇架构做了优化。

编译命令：

# 编译VectorAdd算子
ascendc++ -o vector_add.so vector_add.cpp \
    -I${ASCEND_HOME}/ascend-c/include \
    -L${ASCEND_HOME}/ascend-c/lib64 \
    -lace

# 验证编译成功
ls -lh vector_add.so

# 预期输出（示例）
# -rw-r--r-- 1 root root 45K May 24 10:00 vector_add.so

代码讲解：

• ascendc++：昇腾C++编译器，是gcc的昇腾版本
• -I${ASCEND_HOME}/ascend-c/include：头文件目录
• -L${ASCEND_HOME}/ascend-c/lib64：库文件目录
• -lace：链接昇腾C库

⚠️ 踩坑预警：编译前要设置ASCEND_HOME环境变量，不然找不到头文件和库文件。

步骤3：调试Ascend C代码

代码编译成功了，第三步是调试。asc-tools提供了ascend-gdb调试器，是gdb的昇腾版本，支持NPU上的断点调试。

调试命令：

# 启动ascend-gdb
ascend-gdb ./vector_add_test

# ascend-gdb命令（和gdb一样）
(gdb) break VectorAdd::Compute  # 在Compute函数打断点
(gdb) run                       # 运行程序
(gdb) next                      # 单步执行
(gdb) print element_count_      # 打印变量值
(gdb) info locals               # 打印所有局部变量
(gdb) print x_local.GetValue(0)  # 打印Tensor值
(gdb) continue                  # 继续执行
(gdb) quit                      # 退出调试器

代码讲解：

• ascend-gdb：昇腾GDB调试器，是gdb的昇腾版本
• break：在指定位置打断点
• run：运行程序
• next：单步执行（不进入函数）
• step：单步执行（进入函数）
• print：打印变量值

⚠️ 踩坑预警：ascend-gdb不支持查看LocalTensor的完整内容，只能查看单个元素。

步骤4：验证Ascend C代码

代码调试通过了，第四步是验证。asc-tools提供了acl soot验证工具，可以在CPU上模拟运行Ascend C代码，不用真机就能验证逻辑正确性。

验证命令：

# 用acl soot验证VectorAdd算子
acl soot --op vector_add.so \
    --input "x=[1,2,3,4,5]; y=[10,20,30,40,50]" \
    --expected "z=[11,22,33,44,55]" \
    --attr "element_count=5"

# 预期输出（示例）
# [PASS] VectorAdd op verification passed
# Input x: [1, 2, 3, 4, 5]
# Input y: [10, 20, 30, 40, 50]
# Output z: [11, 22, 33, 44, 55]
# Expected z: [11, 22, 33, 44, 55]
# Match: True

代码讲解：

• acl soot：昇腾算子验证工具，可以在CPU上模拟运行Ascend C代码
• --op：算子动态库路径
• --input：输入数据
• --expected：期望输出
• --attr：算子属性

⚠️ 踩坑预警：acl soot是模拟运行，有些硬件相关的操作（比如DMA）无法模拟，需要真机验证。

完整实战：写一个VectorAdd算子并验证

理论讲完了，来一个完整实战。一步步写、编译、调试、验证一个VectorAdd算子。

步骤1：创建项目目录

# 创建项目目录
mkdir -p ~/vector_add_project/src
mkdir -p ~/vector_add_project/build
mkdir -p ~/vector_add_project/test

cd ~/vector_add_project

步骤2：写Ascend C代码

// src/vector_add.cpp
#include "ascend_c/ascend_c.h"

using namespace ascend::c;

class VectorAdd : public KernelOperator {
public:
    void Init(int32_t element_count) {
        element_count_ = element_count;
        x_buffer_.Bind(this, "x");
        y_buffer_.Bind(this, "y");
        z_buffer_.Bind(this, "z");
        z_buffer_.SetShape({element_count_});
    }
    
    void Compute() {
        auto x_local = x_buffer_.GetLocal();
        auto y_local = y_buffer_.GetLocal();
        auto z_local = z_buffer_.GetLocal();
        
        for (int i = 0; i < element_count_; i++) {
            z_local.SetValue(i, x_local.GetValue(i) + y_local.GetValue(i));
        }
        
        z_buffer_.SyncToGlobal();
    }
    
private:
    int32_t element_count_;
    InputBuffer<x_buffer_, Tensor> x_buffer_;
    InputBuffer<y_buffer_, Tensor> y_buffer_;
    OutputBuffer<z_buffer_, Tensor> z_buffer_;
};

REGISTER_OP("VectorAdd")
    .Input(x)
    .Input(y)
    .Output(z)
    .Attr(element_count, Int)
    .SetKernelFunc([](const OpKernelInput& input, OpKernelOutput& output) {
        VectorAdd op;
        op.Init(input.GetAttr<int32_t>("element_count"));
        op.Compute();
        return 0;
    });

步骤3：写测试代码

# test/vector_add_test.py
import numpy as np
import acl

# 初始化ACL
acl.init()

# 分配设备
acl.rt.set_device(0)

# 准备输入数据
x = np.array([1, 2, 3, 4, 5], dtype=np.float32)
y = np.array([10, 20, 30, 40, 50], dtype=np.float32)

# 分配设备内存
ptr_x = acl.rt.malloc(x.nbytes, acl.RT_MEM_MALLOC_NORMAL_ONLY)
ptr_y = acl.rt.malloc(y.nbytes, acl.RT_MEM_MALLOC_NORMAL_ONLY)
ptr_z = acl.rt.malloc(x.nbytes, acl.RT_MEM_MALLOC_NORMAL_ONLY)

# 拷贝输入数据到设备
acl.rt.memcpy(ptr_x, x.nbytes, x.ctypes.data, x.nbytes, acl.RT_MEMCPY_HOST_TO_DEVICE)
acl.rt.memcpy(ptr_y, y.nbytes, y.ctypes.data, y.nbytes, acl.RT_MEMCPY_HOST_TO_DEVICE)

# 加载算子
acl.op.load_operator("VectorAdd", "./vector_add.so")

# 创建算子描述符
op_desc, ret = acl.op.create_op_desc("VectorAdd")
acl.op.set_op_desc_input_ptr(op_desc, 0, ptr_x, x.nbytes)
acl.op.set_op_desc_input_ptr(op_desc, 1, ptr_y, y.nbytes)
acl.op.set_op_desc_output_ptr(op_desc, 0, ptr_z, x.nbytes)
acl.op.set_op_desc_attr_int(op_desc, "element_count", 5)

# 执行算子
op_handle, ret = acl.op.create_op(op_desc)
acl.op.execute(op_handle)
acl.op.sync_op(op_handle)

# 拷贝结果回主机
result = np.empty(5, dtype=np.float32)
acl.rt.memcpy(result.ctypes.data, result.nbytes, ptr_z, result.nbytes, acl.RT_MEMCPY_DEVICE_TO_HOST)

print(f"x = {x}")
print(f"y = {y}")
print(f"z = {result}")
print(f"期望: z = [11, 22, 33, 44, 55]")
print(f"通过: {np.allclose(result, [11, 22, 33, 44, 55])}")

# 释放资源
acl.op.destroy_op(op_handle)
acl.op.destroy_op_desc(op_desc)
acl.rt.free(ptr_x)
acl.rt.free(ptr_y)
acl.rt.free(ptr_z)
acl.rt.reset_device(0)
acl.finalize()

步骤4：编译算子

cd ~/vector_add_project/build

# 编译VectorAdd算子
ascendc++ -o ../vector_add.so ../src/vector_add.cpp \
    -I${ASCEND_HOME}/ascend-c/include \
    -L${ASCEND_HOME}/ascend-c/lib64 \
    -lace

echo "编译完成"
ls -lh ../vector_add.so

步骤5：运行测试

cd ~/vector_add_project

# 运行测试
python3 test/vector_add_test.py

# 预期输出（示例）
# x = [ 1.  2.  3.  4.  5.]
# y = [10. 20. 30. 40. 50.]
# z = [11. 22. 33. 44. 55.]
# 期望: z = [11, 22, 33, 44, 55]
# 通过: True

踩坑实录

用asc-tools的时候，踩过几个坑，分享出来。

坑1：ascendc++编译失败，找不到头文件

现象：运行ascendc++，报错说fatal error: ascend_c/ascend_c.h: No such file or directory。

原因：ASCEND_HOME环境变量没设置，或者设置错了。

解决：设置ASCEND_HOME环境变量。

# 设置ASCEND_HOME
export ASCEND_HOME=/usr/local/Ascend

# 验证设置正确
echo $ASCEND_HOME
ls $ASCEND_HOME/ascend-c/include/ascend_c/ascend_c.h

坑2：ascend-gdb无法打断点

现象：运行ascend-gdb，打断点时报错说No symbol table loaded。

原因：编译时没加-g参数，生成调试信息。

解决：编译时加-g参数。

# 错误写法（没有调试信息）
ascendc++ -o vector_add.so vector_add.cpp ...

# 正确写法（有调试信息）
ascendc++ -g -o vector_add.so vector_add.cpp ...

坑3：acl soot验证失败

现象：运行acl soot，报错说op verification failed。

原因：算子的输入输出格式和期望不一致。

解决：检查算子的输入输出格式，确保和测试代码一致。

# 查看算子的输入输出格式
acl soot --op vector_add.so --dump-shape

# 预期输出（示例）
# Operator: VectorAdd
# Input x: [N] (float32)
# Input y: [N] (float32)
# Output z: [N] (float32)
# Attr element_count: int32

参考仓库

asc-tools 仓库