msDebug 昇腾算子调试工具

msdebug 是基于 LLDB 的昇腾 NPU 算子调试器。本 skill 支持以下两种调试功能：

1. 上板调试：给算子加 -g -O0 编译选项 → 重编译/部署 → 用 msdebug 拉起算子进程 → 按用户意图交互式调试。
2. coredump 解析：用户指定 core 文件路径 → msdebug 加载解析（挂掉代码行/调用栈/现场变量）。

先识别算子类型：目标算子若位于以下官方算子库/样例库之一，其 -g -O0 编译适配、部署与可调试 target 获取均须走该仓对应流程（各仓注入机制差异较大）；否则按自定义工程处理。

官方算子库/样例库	简述
ops-transformer	CANN 算子库中提供 transformer 类大模型计算的进阶算子库
ops-nn	CANN 算子库中提供神经网络计算能力的高阶算子库
ops-math	CANN 算子库中提供数值计算的基础算子库
ops-cv	CANN 算子库中提供图像处理、目标检测等能力的高阶算子库
asc-devkit	昇腾 AI 处理器专用的 AscendC 算子程序开发语言与标准库
catlass	高性能矩阵乘类算子基础模板库
cann-samples	官方 AscendC 样例库（SIMT/量化/FlashAttention 等 story 教学样例）

各仓的 -g -O0 编译适配、部署与 target 获取统一按 references/official_workflow.md 对应仓章节执行（架构参数也查该文档）。msDebug 调试范围不含 triton-ascend-kernels（Triton JIT）与 shmem（通信多卡）。

1. 目录结构

msdebug-basic-usage/
├── SKILL.md                            // 本 skill 主文件
└── references/
    ├── official_workflow.md            // 各官方算子仓的编译适配/部署/target 获取工作流与架构参数
    ├── sample_debug/                   // 上板调试实测样例：完整命令/回显/命令速查表（含全称与缩写）
    └── sample_coredump/                // coredump 解析实测样例：core 产出、加载解析与命令可用性

2. 流程一：上板调试

支持 Kernel 直调（<<<>>>）、aclnn 单算子、PyTorch 接入。机制是 launch（拉起）：由 msdebug 启动算子进程并接管。

2.1 步骤 1：识别算子类型并加 -g -O0 编译

调试前必须让算子带上调试信息（-g）且关闭优化（-O0），否则断点无法定位代码行。先按上方“官方算子库/样例库”列表识别目标算子所在工程类型：

① 官方算子库/样例库算子：各仓 -g -O0 注入方式不同（--op_debug_config / --bisheng_flags= / CMAKE_BUILD_TYPE=Debug / build.sh --debug / 手动改 CMakeLists），必须按 references/official_workflow.md 对应仓章节执行编译适配、部署，并获取该仓产出的可调试 msdebug target；勿把某一仓命令套用到另一仓。

② 自定义工程（非上述官方仓）：

• Makefile 工程（Kernel 侧）：

  COMPILER_FLAG := -xcce -O0 -g --cce-ignore-always-inline=true -std=c++17
  

• CMake 工程：CMakePresets.json 的 CMAKE_BUILD_TYPE 由 Release 改为 Debug，或在 kernel 侧 CMakeLists 加 -g -O0。

2.2 步骤 2：部署

• ops 系列仓（transformer/nn/math/cv）：编译产出 build_out/cann-ops-<仓>*linux*.run，安装至 ${ASCEND_HOME_PATH}/opp/vendors，并按回显设置 LD_LIBRARY_PATH（见 references 对应仓）。
• 样例型仓（asc-devkit / catlass / cann-samples）：编译即出可执行文件，无需部署。

2.3 步骤 3：msdebug 拉起算子

# 必要时先做环境/通道检查
which msdebug                       # 不在 PATH 时用 ${ASCEND_HOME_PATH}/tools/msdebug/bin/msdebug
cat /proc/debug_switch              # 应为 1；为 0 需 root 执行 echo 1 > /proc/debug_switch（或以 --full 重装驱动）

# 拉起（进入 (msdebug) 会话；任选其一）
msdebug ./test_aclnn_add_example          # Kernel / aclnn 直调
msdebug -- ./app --flag1 arg1             # 带参程序
msdebug python3 test_ops_custom.py        # PyTorch（见 2.4）

终端报 Cannot read termcap database 时：先 export TERMINFO=$(infocmp -D | head -n1) 再拉起。

2.4 步骤 4：按用户意图交互调试

进程拉起后，进入(msdebug) 会话内，此时等待用户的下一步指令，并在 (msdebug) 会话内将用户意图映射为命令并执行。注意：严禁进入(msdebug) 会话后自行加调试命令运行算子，msdebug是交互式调试流程，调试每一步都要按照用户的意图来。

用户意图	msdebug 命令（全称 / 缩写）
打断点 / 查看 / 删除	breakpoint set -f <file> -l <line> / b；查看 breakpoint list；删除 breakpoint delete <id>
运行 / 继续 / 中断	run / r；continue / c；CTRL+C（run 后自动聚焦命中的 kernel）
单步跳过 / 步入 / 步出	thread step-over / n / next；thread step-in / s / step；thread step-out / finish
打印变量	print <变量名> / p（LocalTensor 看 address_.bufferAddr，GlobalTensor 看 address_）
打印全部局部变量	frame variable / var
读 UB / GM / L1 / L0A / L0B / L0C / FB 内存	memory read / x：x -m <空间> -f <格式>[] <地址> -c <行数> -s <每行字节数>（UB 用 bufferAddr，GM 用 address_）
读寄存器	register read / re r（全部加 -a；指定如 re r $PC）
查看调用栈 / 切换栈帧	thread backtrace / bt；frame select <id>（上板调试与 coredump 解析均可用）
查 device / 核 / task / stream / block	ascend info devices / cores / tasks / stream / blocks（blocks -d 看各 block 中断处代码；cores 给出 CoreId 便于切核）
切 Cube / Vector 核	ascend aic <id> / ascend aiv <id>（id 取 ascend info cores 的 CoreId；aic 仅 Cube 算子场景可用）
查 SIMT 线程	ascend info threads / ascend thread <id>（仅 SIMT / Cube 核场景可用）
帮助 / 退出	help <命令> / quit / q（确认时输入 y）

memory read（x）的 -m 可选 GM/UB/L1/L0A/L0B/L0C/FB，-f 支持 float32[]/float16[]/int32[]/uint8[] 等，-c 为打印行数、-s 为每行字节数。完整实测回显与命令速查见 references/sample_debug，建议先按其 README 把样例跑通，再把同样命令泛化到目标算子。

PyTorch 补充：kernel 以独立 .o 部署、run 时动态下发，msdebug 不自动关联其调试信息；kernel 需先带 -g -O0 编译部署。

• 推荐：启动前 export LAUNCH_KERNEL_PATH=<部署路径>/<OpName>_<hash>.o（多在 ${ASCEND_HOME_PATH}/opp/vendors/customize/.../kernel/<SOC>/<op_type>/ 下，多 dtype 选实际调用的那个），再 msdebug python3 test_ops_custom.py，run 前即可按行号打断点。
• 备选：run 后手动 image add <kernel.o> 导入调试信息、image load -f <kernel.o> -s 0 使生效，再设断点（官方顺序：先 run，再 add → load）。

将(msdebug) 会话的打屏输出中与用户当前意图直接相关的 msdebug 回显（提示符/源码行号/变量值/stop reason）展示给用户，末尾给 1~3 条下一步提示予推荐；不输出内部准备与排障过程，不写长报告；每次末尾附 ⚠️基于AI技术生成，注意核查重要信息，仅供参考。用户给出下一步意图后，继续转换为命令并执行。重复此流程直到用户结束调试。

若算子发生 AI Core（AIC ERR）类崩溃：msdebug 调试会话与 coredump 抓取互斥，需退出调试、按流程二 3.1 复现抓取 core 后再解析。

3. 流程二：coredump 解析

算子发生 AI Core（AIC ERR）异常崩溃后，核心工作是加载并解析 core 文件，定位挂掉代码行 / 异常调用栈 / 现场变量。解析是重点；如何产出 core 只是很短的前置（见 3.1）。

3.1 前置：如何产生 core 文件（简短，非重点）

coredump 抓取与 msdebug 调试互斥，不能同时进行：msdebug 调试会话内不会抓取到该类 aic core；需退出调试，直接运行算子并开启 dump。

export ASCEND_DUMP_SCENE="aic_err_detail_dump"   # 必须设置才会生成 aic core
export ASCEND_DUMP_PATH=<输出目录>
./add                                       # 直接运行算子（非 msdebug 拉起）；崩溃后退出码非 0
# core 文件位于 ${ASCEND_DUMP_PATH}/extra-info/data-dump/<deviceId>/ 下

复现与“越界注入 → 崩溃出 core → 定位修复”的完整示例见 references/sample_coredump。

3.2 配套产物与编译取向

• core 文件：必须。
• 解析用二进制：推荐提供 kernel.o（多 tilingKey 用目标 tilingKey 对应 .o）或可执行文件/动态库。建议用 -O2 -g 编译（保留 inline 展开以获取更完整调用栈；上板调试用的 -O0 会展开过多 inline，栈帧反而少）。缺省只有汇编/地址级信息。

3.3 加载与解析

msdebug --core <core文件> [<kernel.o 或 -O2 -g 编译的可执行文件/动态库>]

进入 (msdebug) 后按序执行：

1. ascend info summary：崩溃概要（挂掉 kernel、stop_reason、崩溃核列表与 PC、dump 中可读内存区域及地址）。判读：多核 PC 一致多为逻辑性错误；x 读内存的地址需取自 summary 列出的内存区域。
2. bt：调用栈。帧 #0~#2 常为 AscendC 库调用链，往下找用户源码帧（如 DoubleBufAdd::Process(...) at add.asc:84）即异常位置。仅 stop_reason 为 MTE_ERROR / VEC_ERROR / CUBE_ERROR / CCU_ERROR / FIXP_ERROR 时保证准确。
3. frame select <id>：逐帧看源码；frame variable / p <变量名>：查看现场变量。
4. re r $PC：核对崩溃指令地址；需要时用 x 读取 dump 内存取证。

3.4 coredump 模式命令可用性

命令	可用性
ascend info summary / bt / frame select / frame variable / p	✅
re r $PC / register read -a	✅
x -m <空间> ...（限 summary 列出的 dump 范围，越界报 addr is not in range）	✅
ascend aiv <id>（切换查看其他崩溃核）	✅
ascend info cores / tasks	❌ coredump 模式不支持
n / s / c / continue（单步与继续）	❌ 静态快照不支持

3.5 输出结论

贴 summary / bt / frame / 变量关键回显，用 2~3 句话给出结论（挂掉代码行 file:line、调用栈要点、关键变量值 / 初步根因），附 ⚠️ 免责声明。解析不改动算子；修复请回到流程一（注意：coredump 建议 -O2 -g，上板调试建议 -O0 -g），修复后按 3.1 复现确认。

完整实测（summary / bt 回显、越界定位与修复）见 references/sample_coredump。

4. 约束与注意事项

• 单 Device 仅支持单个 msdebug 实例，调试期间勿运行其他算子程序，单次只调试一个算子；调试通道权限大，生产环境禁用。
• Hccl 接口不支持单步调试；Ascend 950 的 simd_vf 强制 inline 导致断点无法解析时，目标行附近加 __asm__("NOP"); 再打断点。
• Host/Kernel 同名实现文件时，断点用绝对路径。
• 调试完成后恢复临时改过的编译选项/构建文件，并清理残留进程。