2026.05.16-工作周记

[Irissssaa]

工作内容

任务梳理

1. ucore的适配工作；
2. osgdb 功能梳理
   • 调试 rCore
   • OS调试面板设计与实现
   • 将使用文档进行更新
   • 适配 ucore 调试
   • 尝试调试 XV6
3. async-debug 异步调试
   • starry-os 适配
   • 实现异步OS调试功能（流程跑通，面板设计）
   • 文档撰写（使用方法）

工作记录

1. osgdb 功能修复

• osgdb的代码是直接从code-debug中移植过来的，会有一些bug，所以我将async-debug的 OS 调试功能（较为完善，无bug）替换了 osgdb 中的内容；
• 成功调试 rCore；

2. 适配 uCore

首先clone uCore：https://github.com/oscourse-tsinghua/ucore_os_lab；

接下来就是配置文件的核心内容确定：

• qemuPath / 运行架构：uCore支持两种架构：X86_32、Risc-V，我这里是X86_32。

  确定方式：查看uCore 的Makefile文件，看Qemu的变量用的是什么值。

  

• 内核、用户地址范围：找 KERNBASE 和 USERBASE 的定义：

  • 内核范围：[KERNBASE, KERNTOP)
    • 用户范围：[USERBASE, USERTOP)

   "kernel_memory_ranges": [["0xC0000000", "0xF8000000"]],
   "user_memory_ranges": [["0x00200000", "0xB0000000"]],

• Border 断点位置（内核↔用户切换点）：查看 kern/trap/trapentry.S：

  • 内核→用户（border）：找 iret 指令所在行

    • 用户→内核（border）：找 __ alltraps: 标签后第一条真正进入内核的指令行（或直接用 __alltraps 这一行）

• Hook 断点位置（获取下一个进程名）：查看 kern/process/proc.c，找进程切换函数（通常是 proc_run 或 schedule）。Hook 应该打在即将切换到新进程、能拿到新进程 proc->name 的那一行。

• 用户程序 ELF 路径：查看 Makefile，找编译产物的路径格式。Hook 返回的进程名要和这个路径对应。

// chap5
{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "uCore lab5 Debug",
            "type": "ardb",
            "request": "attach",
            "cwd": "${workspaceFolder}/labcodes/lab5",
            "target": ":1234",
            "executable": "${workspaceFolder}/labcodes/lab5/bin/kernel",
            "gdbpath": "gdb",
            "qemuPath": "qemu-system-i386",
            "qemuArgs": [
                "-L",
                "/home/iristseng/data/bin/qemu-7.1.0/pc-bios",
                "-S",
                "-s",
                "-parallel",
                "stdio",
                "-hda",
                "bin/ucore.img",
                "-drive",
                "file=bin/swap.img,media=disk,cache=writeback",
                "-serial",
                "null"
            ],
            "program_counter_id": 8,
            "first_breakpoint_group": "kernel",
            "kernel_memory_ranges": [
                [
                    "0xC0000000",
                    "0xF8000000"
                ]
            ],
            "user_memory_ranges": [
                [
                    "0x00200000",
                    "0xB0000000"
                ]
            ],
            "border_breakpoints": [
                {
                    "filepath": "${workspaceFolder}/labcodes/lab5/kern/trap/trapentry.S",
                    "line": 6
                },
                {
                    "filepath": "${workspaceFolder}/labcodes/lab5/kern/trap/trapentry.S",
                    "line": 43
                }
            ],
            "hook_breakpoints": [
                {
                    "breakpoint": {
                        "file": "${workspaceFolder}/labcodes/lab5/kern/process/proc.c",
                        "line": 647
                    },
                    "behavior": {
                        "functionArguments": "",
                        "functionBody": "const r = await this.miDebugger.evalExpression('local_name', 0, 0); const raw = r.result('value') || ''; const start = raw.indexOf('\\u0022') + 1; const end = raw.lastIndexOf('\\u0022'); const name = raw.substring(start, end); return this.cwd + '/obj/__user_' + name + '_out';",
                        "isAsync": true
                    }
                }
            ],
            "filePathToBreakpointGroupNames": {
                "isAsync": false,
                "functionArguments": "filePathStr",
                "functionBody": "if (filePathStr.includes('kern/')) { return ['kernel']; } else { return [filePathStr]; }"
            },
            "breakpointGroupNameToDebugFilePaths": {
                "isAsync": false,
                "functionArguments": "groupName",
                "functionBody": "if (groupName === 'kernel') { return ['${workspaceFolder}/labcodes/lab5/bin/kernel']; } else { return [groupName]; }"
            }
        }
    ]
}

相关问题：

• whm遇到的“json with comment”的问题是因为当前vscode焦点放在了配置文件中，所以vscode识别成要调试这个json文件了，只需要将调试焦点转移到其他文件就可以了。
• uCore最新的代码维护在https://github.com/LearningOS/uCore-Tutorial-Code，最开始用的是八年前的uCore，启动不了。所以配置文件需要重新写。

3. 配置Starry OS

• QEMU 路径与固件修复：由于我使用的是自定义路径编译的 QEMU，导致其无法自动识别系统固件。

  解决方案：通过修改 make/qemu.mk，在 qemu_args 中添加 -L /usr/share/qemu 参数，显式指定 OpenSBI** 和 网卡 ROM（efi-virtio.rom）的搜索路径。

• 根据StarryOs的信息写调试配置文件。以下是适配 StarryOS 到 osgdb 调试遇到的核心问题：

  ---

    1. GDB 工具链不匹配
  
  系统默认 gdb 不支持 riscv64 架构，报 Truncated register 37。需在 launch.json
  中指定 "gdbpath": "riscv64-unknown-elf-gdb"。
  

  ---

    2. Border 断点位置难找——内核/用户切换在外部 crate
  
  StaryOS 的内核→用户态切换发生在 axcpu 这个外部 crate 的汇编函数 enter_user
  中，没有 StaryOS 自己的源码可以打断点。最终通过为 osgdb 新增函数名 border 
  断点（{ "function": "enter_user" }）解决，直接让 GDB 在函数入口处停下。
  

  ---

    3. Border 断点不能打在循环体内
  
  最初将 border 打在 kernel/src/task/user.rs:26（uctx.run() 调用处），但该行在
  while
  循环里，状态机会被反复触发，导致状态混乱。改用函数名方式后规避了这个问题。
  

  ---

    4. trap_vectorbase 不能用作 border
  
  trap_vector_base 是所有 trap
  的统一入口，包括内核态中断（时钟中断等），不只是用户态 ecall 返回。若将其设为
  border，内核启动期间会被频繁触发，导致启动极慢甚至卡死。
  

  ---

    5. 用户程序调试需要 execve hook
  
  StaryOS 的 shell（busybox）本身没有调试符号，无法直接调试。需要在
  kernel/src/syscall/task/execve.rs:63（curr.set_name(loc.name()）打 hook
  断点，在运行时动态捕获用户执行的任意程序名，并自动切换到对应的符号表和断点组。
  

  ---

    6. 遗留问题（未解决）
  
  enter_user 函数名 border
  命中后，调试器直接暂停给用户，而不是进入单步模式穿越地址边界。怀疑
  borderMatches() 在匹配函数名 border 时存在逻辑问题，需进一步排查 GDB 停在
  enter_user 时 getStack 返回的顶帧 function 字段的实际值。
  

4. 新功能实现方案：注释标记断点

目标：在 launch.json 里，border/hook 断点支持用 marker 字段替代 filepath+line，osgdb 在
attach 阶段自动扫描源文件找到标记行。

---

• launch.json 配置格式变更

  Border 断点（现在）：
  { "filepath": "/path/to/trap/mod.rs", "line": 42 }

  Border 断点（新增支持）：
  { "marker": "@osgdb:border" }

  Hook 断点（现在）：
  {
  "breakpoint": { "file": "/path/to/task/mod.rs", "line": 100 },
  "behavior": { ... }
  }

  Hook 断点（新增支持）：
  {
  "marker": "@osgdb:hook",
  "behavior": { ... }
  }

  uCore 源码里对应加注释：
  // @osgdb:border
  trap_return();

  // @osgdb:hook
  next_proc = schedule();

---

2. 新增模块：markerScanner.ts

职责：给定 cwd 和 marker 字符串，递归扫描源文件，返回 { filepath, line }[]。

scanMarker(cwd: string, marker: string): { filepath: string; line: number }[]

• 扫描范围：cwd 下所有 .c、.rs、.S 文件（可配置）
• 匹配规则：行内含有 marker 字符串即命中，取下一行的行号（注释在断点行的上方）
• 返回多个结果时全部注册（同一个 marker 可以打多个断点）

---

3. gdbDebugSession.ts 修改

在 attachRequest 处理 border_breakpoints / hook_breakpoints 时，检测是否有 marker
字段：

• 有 marker：调用 scanMarker(config.cwd, marker) 得到 { filepath, line }[]，展开后走现有注册逻辑
• 有 filepath+line：走现有逻辑不变

两种格式可以混用。