项目全景 on OS Debug 文档

开发环境搭建

Mon, 01 Jan 0001 00:00:00 +0000

开发环境搭建#

本文档说明如何获取插件源码并跑起来，面向想参与插件开发的开发者。

1. 前置依赖#

插件开发需要以下环境：

# 使用命令检查是否安装成功：
npm -v # 版本在 9 以上
node -v # 版本在 18 以上

如果不存在，按以下提示安装：

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

2. 获取代码#

各仓库及其关系：

仓库	说明
OSDebugger/osgdb	跨特权级调试插件（当前主线，插件代码在 `code-debug/` 目录下）
OSDebugger/async-debug	异步调试插件
WebFreak001/code-debug	上游项目（开源的 GDB/LLDB 调试前端），OS Debug 在其基础上 fork 而来

以 osgdb 为例：

git clone https://github.com/OSDebugger/osgdb.git
cd osgdb/code-debug
npm install
npm run compile

3. 构建与调试插件#

用 VS Code 打开 osgdb 仓库目录（仓库已内置 .vscode/launch.json，配置了 Extension Development Host 启动方式，并带有 npm: compile 前置任务）
按 F5，VS Code 会编译插件并弹出一个新的「扩展开发宿主」窗口
之后的调试操作都在「扩展开发宿主」窗口中进行：打开调试目标工程（如 rCore-Tutorial-v3），按 F5 即可开始调试

4. 打包 vsix#

npm install -g @vscode/vsce
cd osgdb/code-debug
vsce package

打包时会按 .vscodeignore 排除 docs/ 等大型文件。

OSGDB 架构设计

Mon, 01 Jan 0001 00:00:00 +0000

内核用户态协同调试设计与实现#

基本介绍#

调试操作系统与调试普通程序的关键区别在于：普通程序只有一份 ELF 符号表，调试器加载后即可完成断点、单步、调用栈查看等操作；而操作系统运行时涉及内核态和用户态，两者使用不同的符号来源：

状态	符号来源	典型代码
内核态	内核 ELF	`kernel/src/...`
用户态	用户程序 ELF	`user_apps/...`

当 CPU 在内核态运行时，用户程序源码断点不能直接命中；当 CPU 在用户态运行时，内核源码断点也不能简单按普通程序方式处理。OSGDB 的作用就是在内核态和用户态切换时，自动切换符号表和断点组。

调试后端#

整体链路：

VS Code 前端 ←— DAP —→ 调试插件 ←— GDB/MI —→ GDB ←→ QEMU GDB stub / OpenOCD（JTAG + 真实硬件）

DAP（Debug Adapter Protocol）：插件与 VS Code 调试界面交互的标准协议
GDB/MI：插件通过 GDB 的机器接口控制 GDB
调试目标：QEMU 的 GDB stub（-s 参数开启，默认监听 1234 端口），或通过 OpenOCD 连接的 JTAG 真实硬件
远程 attach 模式：支持不带 qemuPath/qemuArgs 的 attach 配置——调试器只负责连接已在运行的 GDB stub，QEMU 需要预先手动启动

内核/用户态协同调试#

1. 状态机#

内核/用户态切换是一个复杂的异步流程：特权级变化、符号表切换、断点组恢复等操作需要按严格顺序执行。为此引入了状态机架构（OSStateMachine），将整个切换流程建模为 4 种状态和 5 种事件的状态转移图；每次状态转移触发对应的动作序列（DebuggerActions，共 8 种动作）。状态机的具体定义见源码。

异步调试设计与实现

Mon, 01 Jan 0001 00:00:00 +0000

异步调试设计与实现#

背景介绍#

Rust 的 async 函数会被编译器转成状态机：函数调用时只创建异步实例，真正的执行发生在实例被 poll 时——执行器每 poll 一次，状态机前进一小段，遇到未就绪的 .await 就暂停并交出控制权。这使常规 GDB 给出的物理调用栈无法完整反映异步函数之间的调用关系：poll 返回后本次的物理栈帧即被销毁，实例之后可能在其他地方被继续 poll，此前的逻辑调用关系随之丢失。

具体来说，物理调用栈存在三方面的问题：

不完整：每次 poll 只推进状态机一小段，物理栈上只保留当前 poll 的片段。完整的逻辑调用链从未同时存在于物理栈上；
跨协程：同一个异步实例可以被先后多次 poll，同一逻辑调用链的不同片段出现在不同的物理栈上；
混杂：物理栈中混入执行器的调度帧，与业务逻辑的调用关系无关。

例如：nonleaf 协程 .await 了 async_fn_leaf，后者又 .await 了 another_branch。GDB 停住时，物理栈上只有「执行器 → 某个协程 poll 函数的当前片段」。至于 nonleaf 在等 async_fn_leaf、async_fn_leaf 又在等 another_branch 这层等待关系，在物理栈上完全看不到。

因此，调试异步程序需要回答两个问题：「这个协程正在等谁」，以及「控制流是怎样走到这里的」。前者称为等待边（await edge，协程间 .await 关系），后者称为调用边（call edge，协程内同步函数间的调用关系）。

方案	依赖特定运行时	修改源代码	输出形式	说明
tokio-console	是（仅支持 tokio）	是（引入 console-subscriber、开启 tokio_unstable）	交互式终端界面	Tokio 官方任务观测工具
async-backtrace	否	是（逐函数添加 `#[framed]` 属性）	文本逻辑栈	异步函数的逻辑栈跟踪库

eBPF 动态跟踪设计

Mon, 01 Jan 0001 00:00:00 +0000

基于 eBPF 的动态调试设计#

背景#

GDB 静态断点调试需要暂停程序的执行，会干扰被调试对象的运行。eBPF 动态跟踪可以在不暂停程序的情况下收集运行时信息，与静态断点调试形成互补。

方案设计#

结合 GDB 断点与插桩的方式，设计基于白名单的动态函数调用跟踪方法：通过白名单指定需要跟踪的函数，在函数被调用时收集运行时信息。

项目设想还包括：在物理机器上利用 eBPF 机制，跟踪用户模式、内核模式和虚拟机监控模式的代码执行状态和数据结构信息。

历史工作#

第一阶段曾实现过 eBPF 调试面板（WebView）：连接 eBPF side-stub，查看并搜索内核/用户程序的符号表，选择函数地址注册 kprobe/uprobe，在探针触发时收集寄存器值等运行时信息。

当前状态#

规划中。

贡献指南

Mon, 01 Jan 0001 00:00:00 +0000

贡献指南#

欢迎参与 OS Debug 的开发。本指南说明如何认领任务、提交代码，以及一些团队约定。

1. 如何参与#

先阅读项目全景与路线图，了解各子项目当前状态与未来规划
按照开发环境搭建把插件跑起来
在路线图的「未来规划」中挑选感兴趣的任务

2. 提 Issue#

提交 issue 时请尽量包含：

问题现象与复现步骤
环境信息：操作系统、QEMU/GDB 版本、插件版本（commit）
相关日志：调试控制台输出、code_debug_qemu_output_history.txt 等

3. 提 Pull Request#

一个 PR 只做一件事，标题描述清晰
修改后先本地验证：npm run compile 通过、在调试目标上验证功能正常
PR 描述中说明改了什么、为什么改、如何验证

4. 文档同步要求#

改了功能，必须同步改文档。 具体包括：

插件行为、launch.json 配置项变化 → 更新对应的使用教程与功能介绍
新增支持的调试目标 → 更新支持矩阵与对应教程
阶段成果 → 更新路线图与首页「最新动态」

这条约定是为了避免文档落后于代码，希望后续不再发生。

路线图

Mon, 01 Jan 0001 00:00:00 +0000

项目阶段工作#

第一阶段：2022-2023#

核心目标：从零构建操作系统源代码级调试工具，打通内核/用户态联合调试的基本链路。

基于开源的 GDB/LLDB 调试前端 WebFreak001/code-debug 进行 fork，实现 VS Code 扩展的基本架构（DAP 协议交互、GDB/MI 接口控制 GDB），支持 QEMU 虚拟机远程调试
提出并实现断点组核心概念：断点按所在地址空间分组，任意时刻只有当前地址空间对应的断点组生效；切换时符号表动态加载/卸载，实现内核态 ↔ 用户态的边界检测与自动切换；以 rCore-Tutorial 作为首个适配目标验证联合调试的可行性
实现 eBPF 调试面板（WebView）与基于 eBPF 的内核态、用户态代码动态跟踪，与 GDB 静态断点调试形成互补
实现内存读写、寄存器查看（RISC-V）、断点表展示等调试界面功能
本阶段遗留问题：断点不在 VS Code 中显示、边界断点与内核符号表耦合、缺少单步步进、控制台输出杂乱、插件包过大、配置硬编码等，成为下一阶段的主要工作内容

第二阶段：2023-2024#

核心目标：全面完善调试器的可用性和通用性，扩展对不同语言（C 语言）和不同运行环境（真实硬件）的支持。

功能完善#

修复第一阶段遗留问题：利用 debug.addBreakpoints API 解决断点显示；边界断点重构为断点组的属性（支持 customRequest 动态设置与右键菜单）；引入 OSStateMachine 状态机架构（4 状态、5 事件、8 种动作）重构切换流程；实现单步步进与 Continue 按钮适配；优化控制台输出；插件包瘦身；配置文件去硬编码（引入 filePathToBreakpointGroupNames、breakpointGroupNameToDebugFilePaths 两个映射函数）

新增功能#

钩子断点（Hook Breakpoints）：断点触发时执行自定义 JavaScript 函数，在进程调度处自动获取即将被调度的用户进程名称，返回值设置 nextBreakpointGroup
SSH 远程调试：密钥/密码认证、X11 转发、远程/本地源文件路径自动映射
多进程调试：断点组动态创建，支持同时调试多个用户态进程
更名为 “OS Debugger” 发布到 VS Code Extension Marketplace，发布 v2.0.0 里程碑版本

新平台适配#

xv6（C 语言）：调试工具栏对所有语言可见；支持多边界断点（usys.S 中多个 ecall 出口）；编写 xv6 专用 launch.json 模板（virt 机器、128M 内存、2 SMP 核心）；适配用户程序命名规则（_filename）与钩子断点
真实硬件（昉·星光 2 开发板）：通过 JTAG 接口集成 OpenOCD；实现 U-Boot 加载操作系统的调试流程；适配 DCSR 寄存器限制（边界断点设在 ecall 前一条指令）

工程化改进#

支持 RISC-V 汇编文件断点；寄存器查看（从上游合并）；一键安装脚本（Shell）；合并上游多项改进（静态变量支持、STL 容器解析修复、GDB Frame Filters 支持等）

第三阶段：2024-2025#

核心目标：提升调试器的稳定性和实用性，修复实际使用中的关键 bug，整理项目仓库，开展 Rust 异步调试功能的研究与开发。

项目全景 on OS Debug 文档

开发环境搭建

开发环境搭建#

1. 前置依赖#

2. 获取代码#

3. 构建与调试插件#

4. 打包 vsix#

OSGDB 架构设计

内核用户态协同调试设计与实现#

基本介绍#

调试后端#

内核/用户态协同调试#

1. 状态机#

异步调试设计与实现

异步调试设计与实现#

背景介绍#

相关工作#

eBPF 动态跟踪设计

基于 eBPF 的动态调试设计#

背景#

方案设计#

历史工作#

当前状态#

贡献指南

贡献指南#

1. 如何参与#

2. 提 Issue#

3. 提 Pull Request#

4. 文档同步要求#

路线图

项目阶段工作#

第一阶段：2022-2023#

第二阶段：2023-2024#

功能完善#

新增功能#

新平台适配#

工程化改进#

第三阶段：2024-2025#