调试

调试专栏枢纽页 —— 每个大型调试特性有独立的设计与使用说明页;本页给总览、遗留开关速查与场景路线

§1专栏地图

页内容
tracepoint 框架统一 trace-event 体系(D-15):单声明表、69 事件/17 组、tracefs 字节级对齐、两级门控、成本模型、dfx= 别名映射、新增事件流程
性能调试perf_event_open(系统调用 241)面、syscost 普查 + IF=0 EFLAGS 对探针、pbench P1-P7、性能门禁三层与六守护域、fsw
锁调试四道防线:类型化锁键(编译期)/自旋看门狗/SPIN·Kani·loom 模型检查/hunt-wedge 自动捕获;lockdep-lite 状态如实
内存取证ledger 总分类账、mmforensics、memwatch/allocwatch、OOM 取证块、USEGV 家族、scribble、hung_task/softlockup/sysrq、离线取证
panic 与符号化panic 报告结构、编译期符号表 D-3、oops 形态、行原子转储、REMOTE-BT、符号化工作流

§2内核日志

  • 串口是首要日志(console=ttyS0):启动期全部打印到 UART;调度器就绪后默认级别降为 emerg,dmesg -n 7 重开全量。
  • 级别 0–7与 Linux 一致;宏 pr_emerg!/pr_err!/pr_warn!/pr_info!/pr_debug!(println! = pr_info! 别名);release 构建剔除 pr_debug。
  • kmsg 环形缓冲 1 MB:读取途径 /proc/kmsg、syslog(2)、dmesg;devkmsg 策略(/proc/sys/kernel/printk_devkmsg:on|ratelimit|off)只决定控制台呈现多少 —— 环永远全量记录(rux 对 Linux devkmsg 语义的对齐实现)。
  • 持久日志(默认关):panic 日志跨重启幸存于 /var/log/kmsg;崩溃后 debugfs 离线抽取(见 内存取证 §8)。

§3trace 体系(摘要)

新观测一律走统一 tracepoint(观测性政策,2026-11-02)。当前 69 事件 / 17 组;tracefs 文件树与字节格式逐文件对齐 Linux;禁用站点 = 单次 load+test+branch,启用 +13–19 ns/记录,镜像 +0.18%。完整设计与用法见 tracepoint 框架。

§4dfx= 运行时开关(遗留诊断面,冻结于 49 项)

启动参数 dfx=开关1,开关2;权威表 = kernel/src/dfx/switches.rs 的 dfx_switch_table!(49 项,冻结不再增长 —— 新观测走 tracepoint);debugfs 在 /sys/kernel/debug/dfx/ 镜像同一张表;多数令牌已迁移为 rux: 事件的武装别名(映射见 tracepoint 框架 §4)。高频项:

开关用途
watchdog自旋锁死锁告警 + 全任务快照(经 SBI 直写,不依赖 printk)
taskdump周期/按需任务快照钩子
memwatch按调用点的堆/页记账(查泄漏;详见 内存取证 §3)
ledger物理页总分类账,OOM 判真耗尽/记账漂移(内存取证 §1)
mmforensicsPTE 安装台账、双重拆卸检测、页表戳环(内存取证 §2;fork/exit 有代价,仅排查用)
scribble / scribblepark任务控制字逐字节涂写猎捕;命中停靠,配 gdb watchpoint(内存取证 §6)
steptrace / writetrace指令步进 / 写路径逐事件跟踪(steptrace 曾单启动写 2.7GB 串口日志 —— 高成本如实)
sysforensic / sysring逐系统调用取证(双录、失败环、comm 扫描)—— 生产必须关(未门控时 p1_null 每调用多付 12 次原子)
ohhuntOH 图形排查探针(drm ioctl/mmap/prime-import;已 trace 化)
claiminject / oncupinject 类蓄意楔死复现器 —— 永不进入生产构建

编译期 feature(Cargo.toml)

cargo build --target riscv64gc-unknown-none-elf --features riscv64,dfx-lock-owner
# dfx-lock-owner:每次加/解锁一次原子存储;死锁告警带 holder=<cpu> + REMOTE-BT 栈捕获

§5GDB 与 QEMU 级调试

  • GDB:make debug(先 make build;连 QEMU gdbstub,断点/单步/查内存)。
  • 确定性复现:THREAD=single make run(单线程 TCG);或 ACCEL=tcg 关 KVM。
  • QEMU monitor:经 unix socket 挂接,screendump 抓屏、寄存器/内存转储(hunt-wedge 自动使用)。
  • 串口落盘:-serial file:xxx.log,长浸泡后离线 grep。

§6场景路线

症状路线
内核挂起无输出THREAD=single 复现 → dfx=watchdog 死锁告警 → hunt-wedge 自动捕获 → addr2line 符号化
内核缺页/非法指令读 panic 块(panic 页 §1):scause 定类、stval 定址 → Call trace 符号化 → 加 mmforensics 取现场
用户态程序崩溃USEGV-L 行定 pid/rip/cr2 → USEGV-FOR 归因(内存取证 §5)
文件系统问题fsw 计数器查新同步写类 → 拷盘 debugfs 离线抽日志 → e2fsck -f 验完整性
怀疑泄漏 / OOM 存疑内存取证:memwatch 记账 → ledger 判真耗尽/漂移
锁竞争/顺序锁调试:lock: 事件看延迟 → 键化对上编译期 → 看门狗 holder 交叉定位
性能回归性能调试:perf-gate.sh 三层判定 → syscost 对带 → pbench 定位组 → trace 取微观序列
仓库正本:docs/guides/debugging.md、docs/architecture/lock-ordering.md、docs/development/perf-gate-baseline.md、kernel/src/dfx/ 与 kernel/src/trace/。