2026.04.19

[Irissssaa]

开发日志

1. 按老师要求转移仓库：

   • 跨特权级调试插件仓库：最开始的code-debug仓库不再变化，组织中新增名为osgdb的仓库负责保存、维护这个插件的代码和文档；（我已将 code-debug 的代码迁移到 osgdb 中）
   • 异步调试插件仓库：改名为async-debug，维护目前的异步相关代码，以及整合界面的相关代码；（后续还是继续在 async-debug 中进行 OS 调试功能的移植）

2. 解决 卡在 trap_return 的bug：

   • 先通过调试调试器，发现主要的原因是hook 断点的加载逻辑有问题，但具体哪里有问题找了很久都没找出来；
   • 然后想到通过在 mi2.ts 中加入输出日志的方式来定位问题，在两个地方注入log：
     • 发送：sendCommand 中添加 console.log([GDB ->] ${command})；
     • 接收：onOutput 中添加 console.log([<- GDB] ${line})；
   • 获得了很多的日志，但是还是没确定下来到底是什么原因。

整体架构：

VS Code UI
    ↕  DAP 协议
GDBDebugSession          ← 总指挥（gdbDebugSession.ts）
  ├── MI2                ← GDB 通信底层（mi2.ts）
  ├── OSStateMachine     ← 状态机定义（OSStateMachine.ts，纯数据）
  ├── BreakpointGroups   ← 断点组管理（breakpointGroups.ts）
  └── OSState            ← 当前状态（运行时变量）
    ↕  GDB MI2 协议
  GDB
    ↕  remote
  QEMU（rCore）

各模块职责：

1. MI2 — 最底层：负责和 GDB 说话

只做一件事：把高层指令翻译成 GDB MI2 协议命令，把 GDB 的输出解析成事件。

关键内容：

• sendCommand('break-insert ...') → 向 GDB 发原始 MI2 命令
• addBreakPoint(bp) → 调用上面，同时把断点注册进 this.breakpoints: Map<Breakpoint, Number>（key=断点对象，value=GDB编号）
• clearBreakPoints(file?) → 遍历 this.breakpoints，删掉属于该文件的所有断点——只能删它自己管的
• 收到 GDB 的停止通知后，发出 breakpoint、step-end、stopped 等 Node.js 事件，供上层监听

重点：this.breakpoints 是 MI2 维护的"我管理的断点"名单，clearBreakPoints 只删名单里的断点。

---

2. OSStateMachine（OSStateMachine.ts）— 纯状态机定义，没有任何副作用

只是一张"状态转换表"，定义了：当前在什么状态 + 发生什么事件 → 下一个状态是什么 + 要执行哪些 Action。

四个状态：

kernel                    ← 正在执行内核代码
kernel_single_step_to_user ← 正在单步穿越内核→用户边界（目前基本不用）
user                      ← 正在执行用户进程代码
user_single_step_to_kernel ← 正在单步穿越用户→内核边界（目前基本不用）

五个事件：

STOPPED                      ← 断在普通断点/单步停下
AT_KERNEL_TO_USER_BORDER     ← 断在内核→用户边界断点
AT_USER_TO_KERNEL_BORDER     ← 断在用户→内核边界断点
AT_KERNEL / AT_USER          ← 单步时确认到达了目标地址空间（RISC-V 目前不走单步路径）

关键转换：

当前状态	事件	下一状态	Actions
kernel	STOPPED	kernel	try_get_next_breakpoint_group_name + check_if_kernel_to_user_border_yet（均无自动运行 → UI暂停）
kernel	AT_KERNEL_TO_USER_BORDER	user	low_level_switch_breakpoint_group_to_high_level（有自动运行 → 不暂停）
user	STOPPED	user	check_if_user_to_kernel_border_yet（no-op → UI暂停）
user	AT_USER_TO_KERNEL_BORDER	kernel	high_level_switch_breakpoint_group_to_low_level（有自动运行 → 不暂停）

---

3. BreakpointGroups（breakpointGroups.ts）— 断点组仓库

负责记忆各断点组的内容，并在组切换时协调 GDB 操作。

核心数据：

• groups[]：每个 BreakpointGroup 存着：
  • setBreakpointsArguments：用户在 VS Code 里设的断点（文件+行号列表）
  • borders：该组的边界断点位置（如 trap_return）
  • hooks：该组的 hook 断点（命中时执行 JS 函数，读取进程名）
• currentBreakpointGroupName：当前活跃的断点组（初始 = "kernel"）
• nextBreakpointGroup：下次 kernel→user 切换时要切到哪个组（由 hook 决定，如 "user-shell"）

核心方法 updateCurrentBreakpointGroup(updateTo, continueAfterUpdate)：

异步链：
  1. 清除旧组断点（clearBreakPoints × 每个文件）
  2. 卸载旧符号文件（removeSymbolFile × 每个ELF）
  3. 加载新符号文件（addSymbolFile × 每个ELF）
  4. 重新插入新组断点（addBreakPoint × 每个断点）
  5. 通知 session（onBreakpointsRestored → 发 BreakpointEvent）
  6. 若 continueAfterUpdate=true → continue（让 GDB 继续跑）

---

4. GDBDebugSession

把上面三个模块连接起来，处理 VS Code 发来的 DAP 请求，也处理 GDB 发来的事件。

初始化流程

attachRequest
  → launchGDB(config)        ← 创建 MI2，注册所有事件监听
  → MI2.connect()            ← GDB 连接 QEMU

MI2 发出 'debug-ready'
  → osDebugReady = true
  → 遍历 breakpointGroups 所有 borders
      → 用 sendCommand('break-insert') 直接插入边界断点（绕开 this.breakpoints）
      → 记录 GDB 编号到 borderGdbNumbers
  → sendEvent(InitializedEvent) → VS Code 重发所有 setBreakpointsRequest

断点命中时的处理流程（核心）

GDB 断点命中
  → MI2 发出 'breakpoint' 事件
  → GDBDebugSession 监听器
      ↓
      osDebugReady?
      是 → bkptno 在 borderGdbNumbers 里？
              是（边界断点）→ 判断方向（kernel→user 还是 user→kernel）
                           → 目标组有断点？
                               有 → osStateTransition(AT_KERNEL_TO_USER_BORDER 或 AT_USER_TO_KERNEL_BORDER)
                                       → 执行 low/high_level_switch action
                                       → 断点组切换 + continue（不暂停 UI）
                               没有 → 直接 continue（跳过，不切组）
              否（普通断点）→ osStateTransition(STOPPED)
                           → actions 都是 no-op
                           → willAutorun=false → 发 StoppedEvent → UI 暂停
      否 → 直接发 StoppedEvent

osStateTransition 的逻辑

function osStateTransition(event):
  1. 调用 stateTransition(状态机, 当前状态, event) → 得到[新状态, actions列表]
  2. 更新 osState = 新状态
  3. 检查 actions 里有没有"自动运行动作"（switch/step 类）
  4. 依次执行每个 action（doAction）
  5. 若没有自动运行动作 → sendEvent(StoppedEvent) → UI 暂停
     若有               → 锁保持（等 doAction 异步回调 releaseOsTransitionLock 后再处理下一个事件）

Hook 断点机制（决定下一个用户进程是谁）

kernel 状态下命中普通断点
  → actions 里有 try_get_next_breakpoint_group_name
  → 读当前栈帧（getStack）
  → 在当前断点组的 hooks 里查找是否匹配当前文件:行
  → 命中 hook → 读局部变量（getStackVariables）
              → 执行 hook.behavior（用户写的 JS 函数，如返回进程名 "user-shell"）
              → setNextBreakpointGroup("user-shell")
              → 下次 kernel→user 切换时就切到 "user-shell" 这个组

---

完整数据流示意

以 rCore 从内核跑到 user-shell 为例：

① GDB 停在 kernel 的某个断点（如 exec 的 hook 位置）
   → STOPPED 事件 → try_get_next_breakpoint_group_name
   → 读变量，得到 "user-shell"
   → setNextBreakpointGroup("user-shell")
   → willAutorun=false → UI 暂停（用户按 continue）

② 用户按 continue，GDB 继续跑
   → 命中 trap_return（边界断点，在 borderGdbNumbers 中）
   → AT_KERNEL_TO_USER_BORDER 事件
   → low_level_switch action
   → updateCurrentBreakpointGroup("user-shell", continueAfterUpdate=true)
       → 清旧断点（kernel的）
       → 卸旧符号（kernel ELF）
       → 加新符号（user-shell ELF）
       → 插新断点（user-shell 的断点）
       → continue（GDB继续跑）
   → UI 不暂停

③ GDB 停在 user-shell.rs 的断点
   → osState 已经是 user → STOPPED 事件
   → willAutorun=false → UI 暂停 ✓

---

这就是整个 OS 调试功能的完整逻辑链。状态机决定"停不停"，断点组管理决定"GDB 里装哪些断点"，边界断点是触发切换的开关，hook 断点是提前预判下一个进程名的机制。