项目全景#

初次接触本项目的开发者建议从本文开始，了解整个项目的来龙去脉与各子项目的分工。

我们做什么#

OS Debug 是面向操作系统开发的源代码级调试工具，目前在 VS Code 中提供三条调试能力线：

  1. OSGDB —— 跨特权级源代码单步调试。在常规 GDB 中，当特权级切换时，原特权级代码中设置的断点会失效，也无法在一个特权级运行时给另一个特权级代码设置断点。OSGDB 通过断点组机制自动处理地址空间切换，可以在内核代码和用户程序中同时设置断点。
  2. Async-Debuger —— Rust 异步（协程）程序调试。在异步执行逻辑中，常规 GDB 给出的物理调用栈无法完整反映异步函数之间的调用关系：异步函数调用时只创建异步实例，真正的执行发生在实例被 poll 时；poll 返回后本次的物理栈帧即被销毁，实例可能在其他协程上被继续执行，此前的逻辑调用关系随之丢失。Async-Debuger 从 GDB 动态获取协程信息，重建异步函数、同步函数的逻辑调用栈，不依赖特定异步运行时。
  3. 跨特权级异步跟踪。异步调试与跨特权级调试的融合能力：在调试 Rust 异步内核时，既可以跨内核态/用户态设置断点与单步调试，也可以查看异步任务的逻辑调用栈。功能已基本实现，但由于调试方案的设计，跟踪的时间消耗很大，后续会进行优化。

此外还有一条规划中的能力线：eBPF 动态调试——结合 GDB 断点与插桩的方式，设计基于白名单的动态函数调用跟踪方法。

项目缘起#

操作系统课上，同学们的内核代码调试手段主要还是在代码中加 printk() 输出信息，很难像应用程序开发那样有一个集成的开发环境，可以方便地进行源代码级的动态跟踪和调试。于是一群对工具感兴趣的人一起开始了这个开源社区项目，希望通过开源社区的持续努力改善这一现状。

项目目标#

我们希望在各种代码执行环境中，及时、准确地获取代码执行信息，并以可视化的方式展现。具体分三个层面：

代码执行环境#

  • 不同特权级：用户模式、内核模式、虚拟机监控模式、机器模式
  • 不同虚拟化环境：QEMU 模拟器、虚拟机、物理 CPU
  • 不同源代码开发语言：C 语言、Rust 语言

信息获取#

  • 当前执行代码与源代码的对应关系信息（符号信息）
  • 函数调用栈
  • 进程、线程和协程的控制块
  • 系统调用、中断、异常等事件
  • 调度器中各种队列数据结构
  • 内存分配和释放情况

信息展现#

  • 在 VS Code 和浏览器中，获取信息的当前状态和历史变化的及时、准确可视化展现
  • 代码信息展现：源代码行号、函数名等
  • 数据结构和相互关系展现：函数调用关系图、火焰图等

各子项目状态与仓库#

子项目仓库状态
OSGDB（跨特权级调试）OSDebugger/osgdb已适配 rCore、StarryOS
Async-Debuger（异步调试）OSDebugger/async-debug已实现插件与界面，在 embassy 上验证；跟踪优化与融合工作在此仓库进行
异步跟踪方案（2024-2025）OSDebugger/code-debug_Asynchronous-trace已停止更新；Rust 异步跟踪方案的起点
旧代码仓库chenzhiy2001/code-debug已停止更新；项目的起点，2022-2024 的工作在此完成
eBPF 动态调试—规划中

如何跑起来#

文档地图#

文档内容
开发环境搭建插件源码的获取、构建与调试
OSGDB 架构设计状态机、断点组、边界断点、钩子断点的设计与实现
异步调试设计与实现逻辑调用栈重建、从 GDB 动态获取协程信息
eBPF 动态跟踪设计eBPF 跟踪方案（规划中）
贡献指南如何参与开发
路线图项目的开发历程与未来规划
Backward 功能介绍 开发环境搭建 Forward