10分钟上手asc-tools：昇腾NPU算子开发工具集

前言要做昇腾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 → hardwareNPU。asc-tools依赖driver提供的接口driver依赖NPU硬件。环境准备安装asc-tools要用asc-tools先要安装它。方式1pip安装推荐# pip安装asc-toolspipinstallascend-ascend-tools-ihttps://pypi.ascend.com/simple/# 验证安装成功ascendc--version# 预期输出示例# ascend-ascend-tools 1.2.0# Copyright (C) 2024 Ascend方式2源码编译安装# 克隆asc-tools仓库gitclone https://atomgit.com/cann/asc-tools.git# 编译安装cdasc-toolsmkdirbuildcdbuild cmake..make-j$(nproc)sudomakeinstall# 验证安装成功ascendc--version方式3Docker镜像# 拉取昇腾CANN开发镜像已包含asc-toolsdockerpull ascendcr.jfrog.io/ascend/ascend-cann-toolkit:8.0# 运行容器dockerrun-itascendcr.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#includeascend_c/ascend_c.husingnamespaceascend::c;// VectorAdd算子类classVectorAdd:publicKernelOperator{public:// 初始化算子参数voidInit(int32_telement_count){element_count_element_count;// 绑定输入输出bufferx_buffer_.Bind(this,x);// 输入xy_buffer_.Bind(this,y);// 输入yz_buffer_.Bind(this,z);// 输出z// 设置输出shapez_buffer_.SetShape({element_count_});}// 算子主体voidCompute(){// 分配LocalTensorautox_localx_buffer_.GetLocal();autoy_localy_buffer_.GetLocal();autoz_localz_buffer_.GetLocal();// VectorAdd计算for(inti0;ielement_count_;i){z_local.SetValue(i,x_local.GetValue(i)y_local.GetValue(i));}// 同步数据到GlobalTensorz_buffer_.SyncToGlobal();}private:int32_telement_count_;InputBufferx_buffer_,Tensorx_buffer_;InputBuffery_buffer_,Tensory_buffer_;OutputBufferz_buffer_,Tensorz_buffer_;};// 算子注册框架自动调用REGISTER_OP(VectorAdd).Input(x).Input(y).Output(z).Attr(element_count,Int).SetKernelFunc([](constOpKernelInputinput,OpKernelOutputoutput){VectorAdd op;op.Init(input.GetAttrint32_t(element_count));op.Compute();return0;});代码讲解class VectorAddVectorAdd算子类继承自KernelOperatorInit()初始化算子参数绑定输入输出bufferCompute()算子主体做VectorAdd计算REGISTER_OP()注册算子告诉框架这个算子叫什么、输入输出是什么⚠️ 踩坑预警Ascend C的语法和标准C有差异比如__aicore__关键字、LocalTensor/GlobalTensor等要仔细看文档。步骤2编译Ascend C代码代码写完了第二步是编译。asc-tools提供了ascendc编译器是gcc的昇腾版本针对达芬奇架构做了优化。编译命令# 编译VectorAdd算子ascendc-ovector_add.so vector_add.cpp\-I${ASCEND_HOME}/ascend-c/include\-L${ASCEND_HOME}/ascend-c/lib64\-lace# 验证编译成功ls-lhvector_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-gdbascend-gdb ./vector_add_test# ascend-gdb命令和gdb一样(gdb)breakVectorAdd::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--opvector_add.so\--inputx[1,2,3,4,5]; y[10,20,30,40,50]\--expectedz[11,22,33,44,55]\--attrelement_count5# 预期输出示例# [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/srcmkdir-p~/vector_add_project/buildmkdir-p~/vector_add_project/testcd~/vector_add_project步骤2写Ascend C代码// src/vector_add.cpp#includeascend_c/ascend_c.husingnamespaceascend::c;classVectorAdd:publicKernelOperator{public:voidInit(int32_telement_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_});}voidCompute(){autox_localx_buffer_.GetLocal();autoy_localy_buffer_.GetLocal();autoz_localz_buffer_.GetLocal();for(inti0;ielement_count_;i){z_local.SetValue(i,x_local.GetValue(i)y_local.GetValue(i));}z_buffer_.SyncToGlobal();}private:int32_telement_count_;InputBufferx_buffer_,Tensorx_buffer_;InputBuffery_buffer_,Tensory_buffer_;OutputBufferz_buffer_,Tensorz_buffer_;};REGISTER_OP(VectorAdd).Input(x).Input(y).Output(z).Attr(element_count,Int).SetKernelFunc([](constOpKernelInputinput,OpKernelOutputoutput){VectorAdd op;op.Init(input.GetAttrint32_t(element_count));op.Compute();return0;});步骤3写测试代码# test/vector_add_test.pyimportnumpyasnpimportacl# 初始化ACLacl.init()# 分配设备acl.rt.set_device(0)# 准备输入数据xnp.array([1,2,3,4,5],dtypenp.float32)ynp.array([10,20,30,40,50],dtypenp.float32)# 分配设备内存ptr_xacl.rt.malloc(x.nbytes,acl.RT_MEM_MALLOC_NORMAL_ONLY)ptr_yacl.rt.malloc(y.nbytes,acl.RT_MEM_MALLOC_NORMAL_ONLY)ptr_zacl.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,retacl.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,retacl.op.create_op(op_desc)acl.op.execute(op_handle)acl.op.sync_op(op_handle)# 拷贝结果回主机resultnp.empty(5,dtypenp.float32)acl.rt.memcpy(result.ctypes.data,result.nbytes,ptr_z,result.nbytes,acl.RT_MEMCPY_DEVICE_TO_HOST)print(fx {x})print(fy {y})print(fz {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\-laceecho编译完成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的时候踩过几个坑分享出来。坑1ascendc编译失败找不到头文件现象运行ascendc报错说fatal error: ascend_c/ascend_c.h: No such file or directory。原因ASCEND_HOME环境变量没设置或者设置错了。解决设置ASCEND_HOME环境变量。# 设置ASCEND_HOMEexportASCEND_HOME/usr/local/Ascend# 验证设置正确echo$ASCEND_HOMEls$ASCEND_HOME/ascend-c/include/ascend_c/ascend_c.h坑2ascend-gdb无法打断点现象运行ascend-gdb打断点时报错说No symbol table loaded。原因编译时没加-g参数生成调试信息。解决编译时加-g参数。# 错误写法没有调试信息ascendc-ovector_add.so vector_add.cpp...# 正确写法有调试信息ascendc-g-ovector_add.so vector_add.cpp...坑3acl soot验证失败现象运行acl soot报错说op verification failed。原因算子的输入输出格式和期望不一致。解决检查算子的输入输出格式确保和测试代码一致。# 查看算子的输入输出格式acl soot--opvector_add.so --dump-shape# 预期输出示例# Operator: VectorAdd# Input x: [N] (float32)# Input y: [N] (float32)# Output z: [N] (float32)# Attr element_count: int32结尾asc-tools是昇腾CANN的算子开发工具集提供了编译ascendc、调试ascend-gdb、验证acl soot三大工具一站式解决算子开发的全流程问题。如果在昇腾NPU上做算子开发强烈建议用asc-tools。实测下来用asc-tools开发一个VectorAdd算子只要10分钟就能跑通比手动配环境快10倍。昇腾CANN的算子开发工具潜力还很大asc-tools还有很多高级功能值得研究。如果在用的过程中遇到啥问题或者想了解某个具体工具的用法欢迎去AtomGit上的昇腾CANN开源社区逛逛里面有一手资料和活跃社区。https://atomgit.com/cann/asc-tools