29、调试器扩展：GDB Python脚本自动化

调试嵌入式程序，尤其是那些跑在裸机或RTOS上的代码，GDB几乎是绕不开的工具。但说实话，纯手工敲命令的方式，在应对复杂场景时效率确实不高。比如你要遍历一个链表、检查某个内存池的状态，或者批量修改寄存器——这些重复劳动，完全可以交给脚本去做。

GDB从7.0版本开始就内置了Python支持。这意味着你可以用Python写调试脚本，直接调用GDB的内部API。我个人习惯把这类脚本叫做“调试外挂”，它们能帮你省下大量敲命令的时间。

为什么需要GDB Python脚本？

我遇到过不少工程师，调试时只会用print、break、continue三板斧。遇到复杂数据结构就傻眼了。你想想看，一个深度嵌套的结构体，每次都要手动展开，多累？

GDB Python脚本能帮你做三件事：

• 自动化重复操作：比如批量设置断点、打印特定格式的数据
• 定制化数据展示：把原始内存数据解析成人类可读的形式
• 扩展调试能力：实现GDB原生不支持的功能，比如内存泄漏检测

说白了，就是把你的调试经验写成代码，让机器替你执行。

GDB Python脚本的基本结构

一个最简单的GDB Python脚本，其实就是一个普通的Python文件，只不过它调用了gdb模块。来看个例子：

import gdb

class PrintTaskList(gdb.Command):
    """打印当前任务链表中的所有任务"""

    def __init__(self):
        super().__init__("print-task-list", gdb.COMMAND_USER)

    def invoke(self, arg, from_tty):
        # 获取全局任务链表头指针
        task_list = gdb.parse_and_eval("g_task_list")
        current = task_list['next']
        while current != 0:
            task = current.dereference()
            print(f"任务ID: {task['id']}, 优先级: {task['priority']}, 状态: {task['state']}")
            current = task['next']

PrintTaskList()

这段代码定义了一个名为print-task-list的GDB命令。加载后，你在GDB里输入print-task-list，它就会自动遍历整个任务链表并打印信息。

加载脚本的几种方式

脚本写好了，怎么用？有三种常见方式：

方式	命令	适用场景
手动加载	source my_script.py	临时调试，一次性的
自动加载	放在~/.gdbinit中	每次启动GDB都需要的脚本
项目专用	放在项目目录的.gdbinit中	特定项目的调试辅助

我个人习惯把通用脚本放在~/.gdbinit里，项目专用的则放在项目根目录。这样既不影响其他项目，又能保持调试环境的一致性。

核心API：parse_and_eval与selected_frame

写GDB Python脚本，有两个API你几乎天天要用：

• gdb.parse_and_eval(expression)：解析并求值一个GDB表达式，返回gdb.Value对象
• gdb.selected_frame()：获取当前选中的栈帧，用于访问局部变量

举个例子，假设你想在断点处打印当前函数的参数：

import gdb

class ShowArgs(gdb.Command):
    """显示当前函数的参数"""

    def __init__(self):
        super().__init__("show-args", gdb.COMMAND_USER)

    def invoke(self, arg, from_tty):
        frame = gdb.selected_frame()
        block = frame.block()
        for symbol in block:
            if symbol.is_argument:
                value = frame.read_var(symbol.name)
                print(f"{symbol.name} = {value}")

ShowArgs()

这段脚本会遍历当前栈帧的符号表，只打印参数变量。我在调试一个参数特别多的函数时，就用这个脚本快速查看所有入参，比手动一个个print快多了。

断点回调：让脚本自动执行

手动敲命令还是不够自动化。更好的方式是让脚本在断点命中时自动执行。GDB提供了gdb.Breakpoint类，支持设置断点并绑定回调函数。

import gdb

class LogOnBreak(gdb.Breakpoint):
    """在指定函数入口打印调用栈"""

    def __init__(self, location):
        super().__init__(location)
        self.count = 0

    def stop(self):
        self.count += 1
        frame = gdb.selected_frame()
        print(f"第{self.count}次调用 {self.location}，当前PC = {frame.pc()}")
        # 打印调用栈前3层
        for i in range(3):
            if frame:
                print(f"  #{i}: {frame.name()} at {frame.function().symtab.filename}:{frame.function().line}")
                frame = frame.older()
        return False  # 不中断程序执行

LogOnBreak("my_function")

这里有个关键点：stop()方法返回False表示不中断程序执行，只是打印日志。返回True则会像普通断点一样停下来。我曾经用这个脚本追踪一个偶发的内存越界问题，每次调用某个分配函数时都记录调用栈，最后发现是某个中断服务程序里偷偷调用了malloc。

实战：自定义内存池查看器

嵌入式系统里经常用固定大小的内存池来避免碎片。但调试时想查看内存池的状态却很麻烦。下面是我写的一个脚本，专门用来查看内存池的使用情况：

import gdb

class MemPoolDump(gdb.Command):
    """显示内存池使用情况"""

    def __init__(self):
        super().__init__("mem-pool-dump", gdb.COMMAND_USER)

    def invoke(self, arg, from_tty):
        pool = gdb.parse_and_eval("g_mem_pool")
        total_blocks = int(pool['total_blocks'])
        free_list = pool['free_list']
        used_count = 0

        # 遍历空闲链表，统计已分配块数
        current = free_list
        while current != 0:
            used_count += 1
            current = current.dereference()['next']

        used = total_blocks - used_count
        print(f"内存池总块数: {total_blocks}")
        print(f"已使用: {used} ({used*100//total_blocks}%)")
        print(f"空闲: {used_count} ({used_count*100//total_blocks}%)")

        # 如果指定了详细模式，打印每个块的地址
        if arg == "-v":
            print("\n空闲块地址:")
            current = free_list
            while current != 0:
                print(f"  0x{int(current):08x}")
                current = current.dereference()['next']

MemPoolDump()

这个脚本会解析内存池结构体，统计已分配和空闲的块数，还能用-v参数列出所有空闲块的地址。我在项目里用它来排查内存泄漏——如果某个模块反复申请不释放，空闲块数量会持续下降，一眼就能看出来。

SVG：GDB Python脚本调试流程

下面这张图展示了GDB Python脚本在调试过程中的作用位置：

从图中可以看出，Python脚本和原生命令是并行的。脚本通过GDB提供的API与目标程序交互，最终把结果展示给用户。这种架构的好处是：你不需要修改GDB本身，就能实现几乎任何调试功能。

调试脚本的调试

写脚本时难免出错。GDB提供了python和python-interactive命令，可以让你在GDB里直接执行Python代码，方便测试。我常用的调试方法是：

(gdb) python print(gdb.selected_frame().name())
main

如果脚本报错，GDB会打印Python的异常信息。你还可以用gdb.write()代替print()，这样输出会直接显示在GDB控制台上，而不是标准输出。

避坑指南

我曾经踩过一个坑：在stop()回调里调用了gdb.execute("continue")，结果导致GDB死循环。原因是stop()返回后GDB会继续执行，而我又在回调里手动执行了continue，相当于重复触发了执行流程。正确的做法是让stop()返回False，GDB会自动继续。

另一个常见问题是脚本中的变量作用域。GDB Python脚本中的全局变量是跨命令调用的，如果你不小心在多个命令中使用了同名变量，可能会互相干扰。我习惯用类封装每个命令，把状态变量作为实例属性，这样就不会冲突了。

嗯，关于GDB Python脚本，今天就聊到这里。记住一点：调试脚本的价值不在于它有多复杂，而在于它能不能解决你实际遇到的问题。从一个小功能开始写起，慢慢积累，你的调试工具箱会越来越强大。