3. 动态调试 (Dynamic Debug)：原理、过滤与实战

动态调试（Dynamic Debug，简称 dyndbg）是 Linux 内核提供的一种运行时动态控制打印信息的机制。它允许开发者在不重新编译内核、不重启设备的情况下，按模块、文件、函数甚至代码行号来开关调试输出。相比传统的 printk 与 pr_debug() 静态编译方式，dyndbg 将调试信息的使能决策从编译期推迟到了运行期，极大提升了驱动调试的灵活性与效率。

核心优势： 生产环境内核默认关闭大量调试打印，避免日志洪流与性能损耗；当现场出现异常时，通过 dyndbg 动态开启目标模块的调试信息，精准定位问题，无需更换内核镜像。

3.1 动态调试原理

动态调试的实现依赖于两个关键基础设施：内核动态调试表与 debugfs 文件系统。

  • 编译时埋点： 使用 pr_debug()、dev_dbg() 等宏的代码，在编译时会被记录到一个全局的 __dyndbg 节区（section）中。每条记录包含：所属模块名、源文件名、函数名、行号、格式化字符串地址。
  • 运行时控制： 内核启动后，通过挂载 debugfs 并在 /sys/kernel/debug/dynamic_debug/control 接口暴露该表。向该文件写入格式化命令，即可动态修改表中任意条目的使能状态。
  • 使能机制： 每条调试语句对应一个 _ddebug 结构体，内含 flags 位域。当 flags 中的 enabled 位被置 1 时，该 pr_debug() 才会实际输出到内核日志缓冲区。
动态调试原理架构图 动态调试 (dyndbg) 原理架构 编译时埋点 pr_debug() / dev_dbg() → __dyndbg 节区 内核动态调试表 _ddebug 结构体数组 (模块/文件/函数/行号/flags) 运行时控制接口 debugfs 文件系统 /sys/kernel/debug/ dynamic_debug/control 写入控制命令 echo 'module xxx +p' > control 关键数据结构 struct _ddebug { const char *modname, *function, *filename; unsigned int lineno; unsigned int flags; };

3.2 启用与禁用动态调试

使用动态调试前，需要确保内核配置了以下选项：

内核配置项说明推荐值
CONFIG_DYNAMIC_DEBUG启用动态调试核心功能y
CONFIG_DEBUG_FS启用 debugfs 文件系统y
CONFIG_DYNAMIC_DEBUG_CORE动态调试核心支持（通常自动选中）y

挂载 debugfs 并查看控制接口：

# 挂载 debugfs（若未自动挂载）
mount -t debugfs none /sys/kernel/debug

# 查看当前所有可动态调试的语句（数量可能很大）
cat /sys/kernel/debug/dynamic_debug/control | head -20

# 统计总数
cat /sys/kernel/debug/dynamic_debug/control | wc -l

启用/禁用命令格式：

echo 'command' > /sys/kernel/debug/dynamic_debug/control

命令由 查询条件 与 操作标志 两部分组成，用空格分隔。常用操作标志：

标志含义说明
+p启用打印使匹配的 pr_debug() 输出
-p禁用打印关闭匹配的调试输出
+f显示函数名输出时附加调用函数名
+l显示行号输出时附加代码行号
+m显示模块名输出时附加模块名
+t显示线程 PID输出时附加线程 ID
常用组合： +pflmt 表示启用打印并同时显示函数名、行号、模块名、线程 PID，适合详细追踪。

3.3 按模块/文件/函数过滤

动态调试支持多种查询条件，可以精确控制调试范围。以下为最常用的过滤方式：

3.3.1 按模块名过滤

# 启用 usb_storage 模块的所有动态调试打印
echo 'module usb_storage +p' > /sys/kernel/debug/dynamic_debug/control

# 禁用 usb_storage 模块的所有动态调试打印
echo 'module usb_storage -p' > /sys/kernel/debug/dynamic_debug/control

3.3.2 按源文件名过滤

# 启用 drivers/usb/storage/ 目录下所有文件的调试打印
echo 'file drivers/usb/storage/* +p' > /sys/kernel/debug/dynamic_debug/control

# 启用特定文件（支持通配符）
echo 'file usb.c +p' > /sys/kernel/debug/dynamic_debug/control

3.3.3 按函数名过滤

# 启用 usb_stor_control_thread 函数内的所有调试打印
echo 'func usb_stor_control_thread +p' > /sys/kernel/debug/dynamic_debug/control

# 启用所有名为 probe 的函数
echo 'func probe +p' > /sys/kernel/debug/dynamic_debug/control

3.3.4 按行号过滤

# 启用文件 usb.c 中第 1024 行的调试打印
echo 'file usb.c line 1024 +p' > /sys/kernel/debug/dynamic_debug/control

# 启用行号范围 1000-2000
echo 'file usb.c line 1000-2000 +p' > /sys/kernel/debug/dynamic_debug/control

3.3.5 组合过滤

# 同时按模块和函数过滤（逻辑与）
echo 'module usb_storage func usb_stor_control_thread +p' > /sys/kernel/debug/dynamic_debug/control

# 排除特定函数
echo 'module usb_storage func !usb_stor_invoke_transport +p' > /sys/kernel/debug/dynamic_debug/control
动态调试过滤匹配流程 动态调试过滤匹配流程 用户写入控制命令 解析查询条件 遍历 __dyndbg 表 匹配成功 → 修改 flags 不匹配 → 跳过，继续遍历 匹配 → 置位/清除 enabled 位

3.4 实战案例：调试 USB 存储驱动

假设我们需要追踪 USB 存储设备插入时的探测流程，定位设备无法识别的根因。以下为完整实战步骤。

3.4.1 场景描述

一块嵌入式开发板插入 U 盘后，dmesg 无任何输出，lsusb 能看到设备，但 /dev/sd* 未出现。怀疑 usb_storage 驱动在 probe 阶段异常退出。

3.4.2 开启目标模块动态调试

# 1. 确认 debugfs 已挂载
mount | grep debugfs

# 2. 查看 usb_storage 模块当前可调试语句数量
cat /sys/kernel/debug/dynamic_debug/control | grep usb_storage | wc -l

# 3. 启用 usb_storage 模块所有调试打印，并附加函数名和行号
echo 'module usb_storage +pfl' > /sys/kernel/debug/dynamic_debug/control

# 4. 确认已启用
cat /sys/kernel/debug/dynamic_debug/control | grep usb_storage | head -5

3.4.3 复现问题并捕获日志

# 清空内核日志环缓冲区
echo > /dev/kmsg

# 重新插入 U 盘（或触发热插拔事件）
# 观察实时日志
dmesg -w | grep usb_storage

3.4.4 按函数精确过滤（减少日志噪音）

# 先关闭所有 usb_storage 调试
echo 'module usb_storage -p' > /sys/kernel/debug/dynamic_debug/control

# 仅启用 probe 函数
echo 'module usb_storage func storage_probe +pfl' > /sys/kernel/debug/dynamic_debug/control

# 再次触发探测，观察输出
dmesg -w | grep storage_probe

3.4.5 按文件过滤（追踪特定源文件）

# 仅启用 scsiglue.c 和 protocol.c 的调试
echo 'file drivers/usb/storage/scsiglue.c +p' > /sys/kernel/debug/dynamic_debug/control
echo 'file drivers/usb/storage/protocol.c +p' > /sys/kernel/debug/dynamic_debug/control

3.4.6 恢复现场（关闭调试）

# 关闭所有动态调试（谨慎使用，会关闭全局）
echo '' > /sys/kernel/debug/dynamic_debug/control

# 或仅关闭 usb_storage 模块
echo 'module usb_storage -p' > /sys/kernel/debug/dynamic_debug/control
注意事项：
  • 生产环境开启大量动态调试可能导致日志洪流，引发系统卡顿或存储溢出。务必使用精确过滤。
  • 动态调试仅对使用 pr_debug()、dev_dbg() 等宏的代码有效。直接使用 printk(KERN_DEBUG ...) 的代码不受控制。
  • 某些发行版内核可能未开启 CONFIG_DYNAMIC_DEBUG，需自行编译内核或确认配置。
  • 嵌入式平台若未挂载 debugfs，需在根文件系统启动脚本中添加挂载命令。

3.5 动态调试 vs 传统 printk 对比

对比维度动态调试 (dyndbg)传统 printk / pr_debug
使能时机运行时动态控制编译时静态决定
重新编译不需要需要修改代码并重新编译
重启设备不需要需要加载新内核或模块
过滤粒度模块/文件/函数/行号全局或手动添加条件判断
性能影响关闭时几乎为零（仅一次空判断）关闭时仍需执行条件判断
适用场景生产环境问题定位、现场调试开发阶段快速验证
最佳实践： 驱动开发阶段使用 pr_debug() 埋点，发布时保留这些调试语句。现场问题定位时，通过 dyndbg 按需开启，实现“零成本埋点，按需激活”的调试策略。

3.6 本章小结

  • 动态调试将调试信息的使能决策从编译期推迟到运行期，通过 debugfs 接口动态控制。
  • 支持按 module、file、func、line 四种维度进行精确过滤，并可组合使用。
  • 操作标志 +p 控制打印使能，+f/+l/+m/+t 控制输出附加信息。
  • 实战中应遵循“先粗后细、精准定位、及时关闭”的原则，避免日志洪流。
  • 动态调试是内核驱动调试的首选武器，与 ftrace、kprobe 等工具配合使用可覆盖绝大多数调试场景。
← 上一章 📖 返回目录 下一章 →