msDebug算子调试工具快速入门¶

1. 概述¶

msDebug 是一款面向昇腾设备的算子调试工具，用于调试在NPU侧执行的算子程序，为算子开发人员提供关键调试能力，包括读取昇腾设备内存与寄存器、断点暂停与恢复程序运行状态等。本文档基于入门教程中开发的简易加法算子，演示 msDebug 工具的核心功能，帮助初学者直观体验其在算子开发过程中带来的高效性与便捷性。

本章节以您已完成《算子开发工具链快速入门》的全流程操作为前提；若尚未体验，建议先完成该指南以获得更佳的学习效果。

2. 操作步骤¶

2.1【环境】必备环境准备（强制前置 ⚠️）¶

🛑 本节为强制前置步骤！跳过将导致后续操作大量出现失败。
本教程仅支持标准化 CANN 容器环境，不兼容裸机、虚拟机或其他非标准容器部署。

2.1.1 安装 CANN 容器环境¶

✅ 请严格按以下指南完成环境安装：
👉 《昇腾 AI 算子开发工具链学习环境安装指南》

⏱️ 外网可达环境下预计耗时：约 3 分钟
安装完成后，您将获得一个预装所有算子工具、示例代码和依赖库的标准化容器环境。

2.1.2 执行环境自检脚本（必须通过！）¶

在如下正式体验前，请全文复制下方整段脚本，粘贴到终端执行，只有输出全部显示为 [PASS] 才能继续：

# 1. 容器环境检查
[ -f /.dockerenv ] && [ -n "$ASCEND_HOME_PATH" ] && [ -n "$ATB_HOME_PATH" ] && echo -e "\033[32m[PASS] CANN 容器环境 OK \033[0m" || echo -e "\033[31m[FAIL] 非标容器或未进入容器！\033[0m"
# 2. 示例代码仓检查
[ -d ~/ot_demo/msot/example/quick_start ] && echo -e "\033[32m[PASS] 示例代码仓 OK\033[0m" || echo -e "\033[31m[FAIL] 代码仓缺失\033[0m"

2.2【前提】算子工程准备完成¶

按照《算子开发工具链快速入门》中 2.3 节操作，完成算子工程准备。

2.3 【调试】断点调试算子代码（msDebug）¶

若算子功能异常，可借助 msDebug 工具进行断点调试，高效定位问题。先按步骤操作体验效果，原理部分可稍后阅读。

2.3.1 开启内核调试开关¶

[!CAUTION]

注意：msDebug 需要 root 权限

msDebug 需要内核调试开关 /proc/debug_switch 开启才能正常工作，但出于安全考虑默认关闭，且需要 root 权限才能打开；这在很多环境（如共享开发机、容器）中可能无法满足，这时请联系系统管理员开启，或在拥有特权的容器中体验此部分。

确认内核调试开关 debug_switch 是否已打开：

cat /proc/debug_switch

若输出值不为 1，请使用 root 权限执行以下命令：

echo 1 > /proc/debug_switch

如果不能成功设置为 1，则 msDebug 功能不可用，只能跳过本节 msDebug 的体验。

2.3.2 修改编译选项并重新部署¶

1. 修改编译选项 在 Kernel 侧 CMakeLists.txt 首行插入一行配置，用于启用调试信息、禁用编译优化：

cd ~/ot_demo/workspace/src/AddCustom
\cp -f op_kernel/CMakeLists.txt op_kernel/CMakeLists.txt.bak
printf '%s\n' "if(COMMAND add_ops_compile_options)" "  add_ops_compile_options(ALL OPTIONS -g -O0)" "elseif(COMMAND npu_op_kernel_options)" "  npu_op_kernel_options(ascendc_kernels ALL OPTIONS -g -O0)" "endif()" | cat - op_kernel/CMakeLists.txt > tmp && mv -f tmp op_kernel/CMakeLists.txt;

2. 重新编译部署算子

bash ./build.sh
MY_OP_PKG=$(find ./build_out -maxdepth 1 -name "custom_opp_*.run" | head -1) && bash $MY_OP_PKG

2.3.3 断点调试与变量查看¶

2.3.3.1 启动调试器¶

cd ~/ot_demo/workspace/src/caller/build
msdebug execute_add_op

2.3.3.2 设置断点¶

待 (msdebug) 提示符出现后，设置断点于 add_custom.cpp 第 34 行：

b add_custom.cpp:34

[!CAUTION]

若在直接申请的容器环境中操作，需特别留意 /proc/debug_switch = 1 可能为虚假状态

若您在云服务商提供的容器环境中操作，即使在容器内成功将 /proc/debug_switch 设置并查询为 1，该状态也可能是虚假的。因出于安全考虑，底层宿主机通常会通过写时复制（CoW）、影子文件或覆盖挂载（overlay mount）等机制对 /proc 目录进行隔离，导致设置未实际生效。

在此情况下，执行上一节所述的断点设置将触发警告；而按照后续章节运行 run 命令时，则会报出如下错误：
error: 'A' packet returned an error: 8
若无法在宿主机上以 root 权限正确设置 /proc/debug_switch，或不具备切换至其他合适环境的条件，则只能跳过本节关于 msDebug 的实操体验。

2.3.3.3 运行算子¶

输入 run 启动程序，等待命中断点：

run

显示如下信息，则成功命中断点：

(msdebug) run
Process 163027 launched: '/root/ot_demo/workspace/src/caller/build/execute_add_op' (aarch64)
[Launch of Kernel AddCustom_ab1b6750d7f510985325b603cb06dc8b_0 on Device 0]
Process 163027 stopped
[Switching to focus on Kernel AddCustom_ab1b6750d7f510985325b603cb06dc8b_0, CoreId 1, Type aiv]
* thread #1, name = 'execute_add_op', stop reason = breakpoint 1.1
    frame #0: 0x00000000000007e0 AddCustom_ab1b6750d7f510985325b603cb06dc8b.o`KernelAdd::Init(this=0x00000000001d78a8, x=0x12c0c0013000, y=0x12c0c001c000, z=0x12c0c0025000, totalLength=16384, tileNum=8) (.vector) at add_custom.cpp:34:9
   31           this->tileLength = this->blockLength / tileNum / BUFFER_NUM;
   32
   33           // 设置全局内存缓冲区，为当前AI Core分配其负责的全局内存区域
-> 34           xGm.SetGlobalBuffer((__gm__ DTYPE_X *)x + this->blockLength * AscendC::GetBlockIdx(), this->blockLength);
   35           yGm.SetGlobalBuffer((__gm__ DTYPE_Y *)y + this->blockLength * AscendC::GetBlockIdx(), this->blockLength);
   36           zGm.SetGlobalBuffer((__gm__ DTYPE_Z *)z + this->blockLength * AscendC::GetBlockIdx(), this->blockLength);

2.3.3.4 查看变量的值¶

在断点处执行以下命令，显示当前作用域内的所有局部变量：

var

输出示例如下：

(msdebug) var
(KernelAdd *__stack__) this = 0x00000000001d78a8
(uint8_t *__gm__) x = 0x000012c0c0013000 ""
(uint8_t *__gm__) y = 0x000012c0c001c000 ""
(uint8_t *__gm__) z = 0x000012c0c0025000 ""
(uint32_t) totalLength = 16384
(uint32_t) tileNum = 8

2.3.3.5 查看寄存器的值¶

register read -a

输出示例如下：

(msdebug) register read -a
                  PC = 0x12C04120088C
                COND = 0x0
                CTRL = 0x100000000003C
                GPR0 = 0x1D78A8
                GPR1 = 0x1D7E28
                GPR2 = 0x800
                GPR3 = 0x0
                GPR4 = 0x0
                GPR5 = 0x8

2.3.3.6 查询Device信息¶

ascend info devices

输出示例如下：

(msdebug) ascend info devices
  Device Aic_Num Aiv_Num Aic_Mask Aiv_Mask
*    3      0       8      0x0     0xf0000000000f

2.3.3.7 查询算子所运行的aicore相关信息¶

ascend info cores

输出示例如下：

(msdebug) ascend info cores
  CoreId Type Device Stream Task Block               PC    stop reason Filename Line
*      0  aiv      3    47    0     4  0x12c041200920  breakpoint 1.1       NA   NA
       1  aiv      3    47    0     5  0x12c041200920  breakpoint 1.1       NA   NA
       2  aiv      3    47    0     6  0x12c041200920  breakpoint 1.1       NA   NA
       3  aiv      3    47    0     7  0x12c041200920  breakpoint 1.1       NA   NA
      44  aiv      3    47    0     0  0x12c041200920  breakpoint 1.1       NA   NA
      45  aiv      3    47    0     1  0x12c041200920  breakpoint 1.1       NA   NA
      46  aiv      3    47    0     2  0x12c041200920  breakpoint 1.1       NA   NA
      47  aiv      3    47    0     3  0x12c041200920  breakpoint 1.1       NA   NA

2.3.3.8 查询算子所运行的task相关信息¶

ascend info tasks

输出示例如下：

(msdebug) ascend info tasks
  Device Stream Task Invocation
*   3      47     0  AddCustom_ab1b6750d7f510985325b603cb06dc8b_0

2.3.3.9 查询算子所运行的stream相关信息¶

ascend info stream

输出示例如下：

(msdebug) ascend info stream
  Device Stream Type
*   3      47    aiv

2.3.3.10 查询算子所运行的block相关信息¶

ascend info blocks

输出示例如下：

(msdebug) ascend info blocks
  Device Stream Task Block
*   3      47     0     4
    3      47     0     5
    3      47     0     6
    3      47     0     7
    3      47     0     0
    3      47     0     1
    3      47     0     2
    3      47     0     3

2.3.3.11 退出调试器¶

q
y

2.3.4 恢复被修改的文件¶

执行如下命令：

cd ~/ot_demo/workspace/src/AddCustom
\cp -f op_kernel/CMakeLists.txt.bak op_kernel/CMakeLists.txt