Ascend C CPU Debug 调试实战:基于 GDB 的核函数本地调试指南

原创2026-10-15 23:20:551,866 阅读
文章标签:人工智能深度学习高性能计算CANN

Ascend C CPU Debug 调试实战:基于 GDB 的核函数本地调试指南

导读

本文基于 asc-devkit 仓库中的 CPU Debug 直调样例(examples/01_simd_cpp_api/01_utilities/06_cpu_debug),系统讲解 Ascend C 核函数(Kernel)的 CPU 域调试方法。CPU Debug 允许开发者在不依赖 NPU 硬件的普通 x86/aarch64 服务器上,将核函数程序以 Host 程序形式编译链接,通过 GDB 设置断点、单步执行、查看变量与调用栈,完成算子逻辑验证。读完本文,你将掌握 CMAKE_ASC_RUN_MODE=cpu 编译模式的完整用法、GDB 多进程跟踪配置,以及如何在实际项目中用断点定位核函数逻辑问题。

CPU Debug 功能概述

CPU Debug 是 Ascend C 提供的"CPU 域孪生调试"能力:将算子核函数程序以 Host 程序的形式进行编译,链接 CPU 调测库(tikicpulib),执行编译生成的可执行文件即可在 CPU 上完成算子运行验证。相比 NPU 域运行,CPU 域调试具有以下特点:

  • 无需 NPU 硬件:在普通服务器上即可完成算子逻辑的开发和功能验证,适合算法原型开发、CI 快速回归和问题定位;
  • 与 GDB 深度结合:支持设置断点、查看寄存器和内存状态、单步执行、查看调用栈等标准调试操作;
  • CPU/NPU 代码归一:同一份 .asc 源码通过 CMake 切换编译模式即可在 CPU 域、NPU 仿真域、NPU 上板域之间复用。

从仓库实现看,CPU 模式的核心装配逻辑位于 cmake/asc/legacy_modules/function.cmake:当 RUN_MODE 为 cpu 时,find_package(tikicpulib REQUIRED) 引入 CPU 调测库,并链接 tikicpulib::${SOC_VERSION};同时通过 target_compile_definitions 注入 ASCENDC_CPU_DEBUG=1 ASCENDC_DEBUG=1 ASCENDC_DUMP=0 宏,并将设备端代码以 auto_gen_${KERNELS}.cpp 形式编译进 Host 工程。换句话说,CPU Debug 模式实质上是"用 Host 编译器 + CPU 模拟库重新编译设备端代码",因此不依赖任何 NPU 驱动。

注意:CPU 域调试当前仅支持 SIMD 编程场景,SIMT 编程场景暂不支持(详见 docs/zh/guide/programming_guide/debug_and_tuning/functional_debug/cpu_twin_debug.md)。

本样例支持的产品与版本

产品 CANN 软件版本
Ascend 950PR & 950DT 系列产品 >= CANN 9.1.0
Atlas A3 系列产品 >= CANN 9.0.0
Atlas A2 系列产品 >= CANN 9.0.0

样例目录结构

├── 06_cpu_debug
│   ├── CMakeLists.txt          // 编译工程文件
│   ├── cpu_debug.asc           // Ascend C 样例实现 & 调用样例
│   └── README.md               // 样例说明文档

其中 cpu_debug.asc 是完整的算子实现与调用代码,CMakeLists.txt 是构建配置。

样例设计:以 Add 计算为调试载体

本样例的 Add 实现与 Add 基础样例 保持一致,默认使用 float 类型。数据总量为 8 个 block × 2048 个元素 = 16384 个 float 元素,每个 block 处理 2048 个数据,计算流程为典型的三段式流水:DataCopy 输入到 UB → 执行 Add → 将结果 DataCopy 回 GM。

核函数实现解析

核函数定义在 cpu_debug.asc:

template <typename T, uint32_t blockLength>
__global__ __vector__ void add_custom(__gm__ T* x, __gm__ T* y, __gm__ T* z)
{
    AscendC::InitSocState();

    AscendC::GlobalTensor<T> xGm;
    AscendC::GlobalTensor<T> yGm;
    AscendC::GlobalTensor<T> zGm;
    xGm.SetGlobalBuffer(x + block_idx * blockLength, blockLength);
    yGm.SetGlobalBuffer(y + block_idx * blockLength, blockLength);
    zGm.SetGlobalBuffer(z + block_idx * blockLength, blockLength);

    AscendC::LocalMemAllocator<AscendC::Hardware::UB> ubAllocator;
    AscendC::LocalTensor<T> xLocal = ubAllocator.Alloc<T, blockLength>();
    AscendC::LocalTensor<T> yLocal = ubAllocator.Alloc<T, blockLength>();
    AscendC::LocalTensor<T> zLocal = ubAllocator.Alloc<T, blockLength>();

    AscendC::DataCopy(xLocal, xGm, blockLength);
    AscendC::DataCopy(yLocal, yGm, blockLength);
    AscendC::PipeBarrier<PIPE_ALL>();

    AscendC::Add(zLocal, xLocal, yLocal, blockLength);
    AscendC::PipeBarrier<PIPE_ALL>();

    AscendC::DataCopy(zGm, zLocal, blockLength);
    AscendC::PipeBarrier<PIPE_ALL>();
}

关键点说明:

  • 数据分片:block_idx 通过 GetBlockIdx() 获取当前核编号,每个核按 block_idx * blockLength 偏移处理各自的数据段,实现多核并行;
  • GM 访问:GlobalTensor 用于访问 GM(Global Memory,AI Core 外部全局存储,容量大但访问慢);
  • UB 缓存:LocalTensor 指向 UB(Unified Buffer,AI Core 内部向量计算专用缓存,容量有限但访问快),向量计算单元只能访问 UB 上的数据;
  • 数据搬运:DataCopy 在 GM 与 UB 之间搬运数据,方向由参数顺序决定;
  • 流水同步:PipeBarrier 确保"搬入→计算→搬出"各阶段按序执行,避免读写冲突。

Host 侧调用与结果校验

主程序(cpu_debug.asc)完成数据准备、核函数启动和精度校验:

  • 使用 aclrtMalloc 在设备侧分配 x、y、z 三块显存,aclrtMemcpy 完成 H2D 拷贝;
  • 通过内核调用符 <<<numBlocks, 0, stream>>> 启动核函数,numBlocks=8 指定 8 个核并行执行;
  • 计算完成后 aclrtMemcpy 回拷结果,并与 Host 侧 golden 数据(x[i] + y[i])逐元素比对;
  • 校验通过时输出 [Success] Case accuracy is verification passed.,失败时输出 [Failed] Case accuracy is verification failed!。

说明:CPU 域调测对 acl 接口的支持是有边界的。框架在 CPU 域仅对部分 acl 接口做了适配(如 aclrtMalloc/aclrtFree/aclrtMemcpy 等有实际功能,aclInit/aclrtSetDevice/aclrtCreateStream 等为打桩实现),且不支持用户自行链接 ascendcl 库。具体支持清单见 cpu_twin_debug.md。

编译与运行

配置环境变量

请根据当前环境上 CANN 开发套件包的安装方式配置环境变量:

source ${install_path}/cann/set_env.sh

${install_path} 为 CANN 包安装目录,未指定安装目录时默认安装至 /usr/local/Ascend 下。

样例执行

在样例目录下执行如下命令:

mkdir -p build && cd build;
cmake -DCMAKE_ASC_RUN_MODE=cpu -DCMAKE_ASC_ARCHITECTURES=dav-2201 ..;make -j;
./cpu_debug

请根据实际测试的 NPU 硬件架构选择对应的 CMAKE_ASC_ARCHITECTURES 参数。

编译选项说明

选项 可选值 说明
CMAKE_ASC_RUN_MODE cpu 指定为 cpu,开启 CPU 域编译
CMAKE_ASC_ARCHITECTURES dav-2201、dav-3510 指定 NPU 架构版本号,CMake 会根据该值配置对应的 CPU 调试依赖库。dav-2201 对应 Atlas A2 系列产品和 Atlas A3 系列产品,dav-3510 对应 Ascend 950PR&950DT 系列产品

从样例的 CMakeLists.txt 可以看出,工程通过 find_package(ASC REQUIRED) 引入 Ascend C 构建框架,project(cpudebug LANGUAGES ASC CXX) 声明 ASC 语言,target_compile_options 中通过 --npu-arch=${CMAKE_ASC_ARCHITECTURES} 将架构版本传给编译器。底层构建框架会根据 RUN_MODE 决定链接 CPU 调测库还是 NPU 运行时库(见 function.cmake)。在 CPU 模式下,还会额外生成 Host 侧的 host_stub.cpp 与 auto_gen_${KERNELS}.cpp(生成逻辑见 extract_host_stub.py),其中通过 ICPU_RUN_KF 宏将核函数编译为可在 CPU 上调用的入口,这正是"CPU 域可执行程序"的由来。

执行结果

执行成功输出如下:

[Success] Case accuracy is verification passed.

进入 GDB 模式调试

前置要求:需使用 GDB 12.1 及以上版本。

编译生成的 CPU 域可执行程序支持通过 gdb 进行调试。gdb 支持设置断点、查看寄存器和内存状态、单步执行、查看调用栈等常用调试操作。在上述指令中 ./cpu_debug 前加入 gdb --args,再次执行指令即可进入 gdb 模式:

gdb --args ./cpu_debug

关键前提:子进程跟踪模式

CPU Debug 通过为每个核函数启动单独的子进程来模拟 NPU 的执行逻辑(每个 AI Core 拉起一个子进程;针对分离架构,默认每个 AI Core 会拉起 3 个子进程,1 个 Cube、2 个 Vector)。因此使用 gdb 调试时,需要设置 follow-fork-mode 让 gdb 跟踪子进程,才能在核函数内部断点调试。进入 gdb 后,先设置跟踪子进程模式:

(gdb) set follow-fork-mode child

常用调试操作

# 在核函数入口处设置断点
(gdb) break add_custom

# 运行程序
(gdb) run

# 单步执行
(gdb) next

# 继续执行到下一个断点
(gdb) continue

进阶:同时调试多个子进程

上述 follow-fork-mode child 方式只会停留在遇到断点的第一个子进程,其余子进程和主进程会继续执行直到退出,因此涉及核间同步的算子无法用该方法调试。如需同时调试多个子进程,可采用以下多进程调试流程(详见 cpu_twin_debug.md):

# 设置只调试一个进程、挂起其他进程
(gdb) set detach-on-fork off

# 查看当前调试模式
(gdb) show detach-on-fork

# 捕捉 fork 事件,每次起子进程时中断 gdb
(gdb) catch fork

执行 run 后查看当前进程信息:

(gdb) info inferiors
  Num  Description
* 1    process 19613

此时程序断在主进程 fork 的位置,子进程还未生成。执行 continue 后再查看,可以看到第一个子进程已启动:

(gdb) info inferiors
  Num  Description
* 1    process 19613
  2    process 19626

切换到第二个进程(即第一个子进程)打上断点进行调试:

(gdb) inferior 2
[Switching to inferior 2 [process 19626] ($HOME/demo)]
(gdb) info inferiors
  Num  Description
  1    process 19613
* 2    process 19626

注意:inferior 后跟的数字是进程的序号,不是进程号。如果遇到同步阻塞,可切回主进程继续生成子进程,再切换到新的子进程调试;同步条件完成后,再切回第一个子进程继续执行。

完整调试会话示例

gdb --args add_custom_cpu        # 启动 gdb(add_custom_cpu 为 CPU 域算子可执行文件)
set follow-fork-mode child       # 跟踪子进程
break add_custom.cpp:45          # 在源码指定行设置断点
run
list                             # 查看断点附近源码
backtrace                        # 查看调用栈
print i                          # 打印变量值
break add_custom.cpp:56          # 在另一个位置设置断点
continue
display xLocal                   # 每步自动显示 xLocal 的值
quit

结合 print、display、backtrace、list 等命令,可以在断点处精确检查 LocalTensor 内容、中间变量和函数调用关系,精准验证程序执行流程是否符合预期。

CPU 域调试的注意事项

1. BuiltIn 关键字被置空导致的函数重定义

在 CPU 孪生调试模式下,编译器不识别 Ascend C 提供的 SIMD-BuiltIn 关键字及 SIMT-BuiltIn 关键字,包括函数执行空间限定符(__aicore__、__global__、__host__)、函数标记宏(__simd_vf__、__simd_callee__)以及地址空间限定符(__gm__、__ubuf__)等。这些关键字与 Device 侧执行强相关,在 CPU 域无需实际生效,因此框架将其定义为空。

由于这种置空处理,仅通过 BuiltIn 关键字区分的函数签名将被视为相同,会导致重定义编译错误。典型问题场景:

  • Device 侧函数与 Host 侧函数同名:如下例中 add 仅通过 __aicore__ 区分运行域,CPU 模式下两个声明冲突:
__aicore__ inline void add(int x, int y);  // Device侧
void add(int x, int y);                    // Host侧(等同于 __host__)
  • 参数类型仅有地址空间限定符不同:两个 Device 侧函数仅在指针的地址空间限定符上不同:
__aicore__ inline void process(__gm__ void* data, int size);
__aicore__ inline void process(__ubuf__ void* data, int size);

孪生调试场景下请勿定义仅依赖 BuiltIn 关键字来区分的函数。

2. 日志环境变量辅助调测

CPU 调测过程中,配置日志相关环境变量可以记录程序的运行过程及异常信息,有助于功能调测。关于环境变量的使用约束与详细说明,可参见 CANN 文档《环境变量参考》中"辅助功能 > 日志"章节。

3. 与 printf / DumpTensor 的取舍

除了 GDB 断点调试,Ascend C 还提供了 printf 与 DumpTensor 两种轻量打印手段,二者均可用于 CPU 域调试。它们的对比关系是:

手段 适用场景 特点
GDB 断点调试 需要交互式检查变量、调用栈、寄存器 不污染代码,可随时暂停检查现场
printf 在 kernel 侧打印格式化日志 简单直接,但对运行性能有影响,通常调测阶段使用,可通过 ASCENDC_DUMP=0 关闭
DumpTensor 打印指定 LocalTensor 的内容及附加信息 适合快速查看张量数据,同样可通过 ASCENDC_DUMP=0 关闭

与 NPU 仿真、上板运行模式的对比

CMAKE_ASC_RUN_MODE 还支持 sim(NPU 仿真)与 npu(上板运行)模式(默认 npu)。三者对比如下:

运行模式 编译目标 依赖 典型用途
cpu Host 可执行程序,链接 tikicpulib 无需 NPU 硬件 本地逻辑调试、GDB 单步、CI 快速回归
sim 链接仿真运行时(runtime_camodel 等) 无需 NPU 硬件,需仿真库 指令级行为验证、性能预估
npu 链接 runtime,设备端编译成二进制 需要 NPU 设备与驱动 上板运行、真实性能测试

切换编译模式前需清理 cmake 缓存,可在 build 目录下删除 CMakeCache.txt 后重新 cmake。

总结

CPU Debug 是 Ascend C 算子开发链路中"先验证逻辑、再上板调优"的重要一环。通过 -DCMAKE_ASC_RUN_MODE=cpu 即可将同一份 .asc 源码编译为 CPU 域可执行程序,配合 GDB 12.1+ 的 follow-fork-mode child / detach-on-fork off / catch fork 多进程调试手段,开发者可以在无 NPU 环境下完成断点、单步、变量检查等全流程逻辑验证。建议的实践路径是:先在本样例(Add 计算)上跑通 CPU Debug 全流程,掌握核函数断点与子进程跟踪技巧,再将其迁移到实际算子工程中,用于问题定位与回归验证。如需更深入的原理与多进程调试细节,可继续阅读 docs/zh/guide/programming_guide/debug_and_tuning/functional_debug/cpu_twin_debug.md。

登录后查看全文
asc-devkit