📚 课程目录第3章动态调试框架(Dynamic Debug)

3、动态调试框架 (Dynamic Debug)：CONFIG_DYNAMIC_DEBUG 配置与 debugfs 接口

动态调试 (Dynamic Debug, dyndbg) 是 Linux 内核提供的一种强大机制，允许开发者在系统运行时动态地启用或禁用内核代码中的 pr_debug()、dev_dbg() 等调试打印语句，而无需重新编译内核或重启系统。对于网络协议栈这类复杂且状态多变的子系统，动态调试是定位运行时问题的利器。

3.1 核心配置：CONFIG_DYNAMIC_DEBUG

要使用动态调试功能，首先需要在内核配置中启用该选项。这是所有后续操作的基础。

配置项	说明	推荐状态
`CONFIG_DYNAMIC_DEBUG`	启用动态调试核心框架，支持对 `pr_debug`/`dev_dbg` 的运行时控制	必须开启 (y)
`CONFIG_DYNAMIC_DEBUG_CORE`	将动态调试核心代码编译为独立模块，减少内核体积	可选 (m)

配置检查命令：

# 检查当前内核是否启用了动态调试
zcat /proc/config.gz | grep CONFIG_DYNAMIC_DEBUG

# 输出示例（已启用）
CONFIG_DYNAMIC_DEBUG=y
CONFIG_DYNAMIC_DEBUG_CORE=y

如果输出为空或显示 # CONFIG_DYNAMIC_DEBUG is not set，则需要重新编译内核并开启此选项。

3.2 debugfs 接口：`/sys/kernel/debug/dynamic_debug/control`

当内核启用了 CONFIG_DYNAMIC_DEBUG 且挂载了 debugfs 文件系统后，用户空间可以通过 /sys/kernel/debug/dynamic_debug/control 文件与动态调试框架交互。该文件既是查询接口，也是控制接口。

挂载 debugfs： 如果 /sys/kernel/debug 目录为空，需要手动挂载：

mount -t debugfs none /sys/kernel/debug

3.2.1 查询当前所有调试语句

读取 control 文件可以列出内核中所有被 pr_debug() / dev_dbg() 标记的调试点及其当前状态。

# 查看所有调试点（输出可能非常庞大）
cat /sys/kernel/debug/dynamic_debug/control

# 使用 grep 过滤网络协议栈相关调试点
cat /sys/kernel/debug/dynamic_debug/control | grep "net/ipv4/tcp"

输出格式示例：

net/ipv4/tcp_input.c:1234 [tcp]tcp_rcv_established =_ "TCP: data seq %u ack %u\012"
net/ipv4/tcp_output.c:567 [tcp]tcp_transmit_skb =_ "TCP: output skb %p len %u\012"

每一行代表一个调试点，格式为：文件名:行号 [模块名]函数名 =标志位 "格式化字符串"。标志位 =_ 表示当前禁用，=p 表示当前启用。

3.2.2 动态启用/禁用调试语句

向 control 文件写入特定的命令字符串，可以精确控制调试点的开关。命令格式遵循 match_type match_value flags 的语法。

匹配类型	匹配值示例	说明
`file`	`tcp_input.c`	匹配文件名（支持通配符 `*`）
`func`	`tcp_rcv_established`	匹配函数名
`module`	`tcp`	匹配所属内核模块名
`line`	`1234` 或 `1000-2000`	匹配行号或行号范围
`format`	`TCP: data seq`	匹配格式化字符串内容

标志位	含义
`+p`	启用 (print) 该调试点的打印
`-p`	禁用该调试点的打印
`=p`	将标志位设置为仅启用打印（清除其他标志）
`+f`	在输出中添加函数名
`+l`	在输出中添加行号
`+m`	在输出中添加模块名
`+t`	在输出中添加线程 ID

常用控制命令示例：

# 启用 tcp_input.c 文件中所有调试点
echo "file tcp_input.c +p" > /sys/kernel/debug/dynamic_debug/control

# 启用 tcp_rcv_established 函数中的所有调试点
echo "func tcp_rcv_established +p" > /sys/kernel/debug/dynamic_debug/control

# 启用 tcp 模块中所有调试点，并附加函数名和行号
echo "module tcp +pfl" > /sys/kernel/debug/dynamic_debug/control

# 禁用 net/ipv4 目录下所有调试点
echo "file net/ipv4/* -p" > /sys/kernel/debug/dynamic_debug/control

3.3 动态调试工作流程

下图展示了从用户空间写入命令到内核调试点状态变更的完整流程。

3.4 实战技巧：精准定位网络协议栈问题

在网络协议栈调试中，动态调试可以极大减少信息噪音。以下是一些经过验证的实战策略。

按模块启用： 当怀疑 TCP 层问题时，只启用 tcp 模块的调试，避免被其他子系统日志淹没。
```
echo "module tcp +p" > /sys/kernel/debug/dynamic_debug/control
```
按函数聚焦： 如果问题集中在连接建立阶段，可以只启用 tcp_v4_connect 或 tcp_rcv_synsent_state_process 等关键函数。
```
echo "func tcp_v4_connect +p" > /sys/kernel/debug/dynamic_debug/control
```
结合行号范围： 当已知问题代码的大致范围时，可以启用特定行号区间的调试点。
```
echo "file tcp_input.c line 1200-1300 +p" > /sys/kernel/debug/dynamic_debug/control
```
附加上下文信息： 使用 +flm 标志让每条调试输出都包含文件名、行号和模块名，便于后期分析。
```
echo "module tcp +pflm" > /sys/kernel/debug/dynamic_debug/control
```

性能警告： 启用大量调试点（尤其是网络数据路径上的高频函数，如 tcp_rcv_established）会显著增加系统开销，可能导致性能下降或日志缓冲区溢出。建议在低负载环境或特定测试场景下使用，并尽快关闭。

3.5 与 printk 级别的关系

动态调试与传统的 printk 级别机制是互补的。动态调试控制的 pr_debug() 和 dev_dbg() 在默认编译条件下，其日志级别等同于 KERN_DEBUG (7)。这意味着，即使通过动态调试启用了某个调试点，如果当前控制台的日志级别 (/proc/sys/kernel/printk) 低于 7，这些消息仍然不会显示在控制台上，但会记录在 dmesg 环形缓冲区中。

机制	控制方式	运行时开关	日志级别
`printk(KERN_INFO ...)`	编译时硬编码	否	KERN_INFO (6)
`pr_debug()` (无 DYNAMIC_DEBUG)	编译时 `DEBUG` 宏	否	KERN_DEBUG (7)
`pr_debug()` (有 DYNAMIC_DEBUG)	debugfs 接口	是	KERN_DEBUG (7)

确保能看到调试输出：

# 将控制台日志级别调低，使 KERN_DEBUG 消息也能显示
echo 8 > /proc/sys/kernel/printk

# 或者直接查看 dmesg
dmesg -w | grep "tcp:"