xyou
8717ea8f20
新增 docs/上下文/260805/交接文档-多智能体推进收尾.md：W2-W6 全程成果、W6 丢失项、Bug 状态核对、下一步优先级、环境坑点 Bug记录.txt: BUG-005/006/007 状态 OPEN->FIXED（代码已修于 a26866e，文档过时未同步） 系统开发策划.md: M2 进度更新（vector allocator/LAPIC EOI 标完成，MSI-X 标 NVMe完成/virtio_net待做，B7 阻塞点更新）
184 lines
14 KiB
Markdown
184 lines
14 KiB
Markdown
# 交接文档 — 多智能体推进收尾（2026-08-05）
|
||
|
||
> **接手者须知**：本文档记录截至 2026-08-05 的工作全貌。此前通过多轮多智能体并发推进 W2→W6，主体成果已合并提交（commit `a26866e` + `019585f`），但**第六波（W6）三线成果全部丢失未入库**，需重做。请先读"未完成工作"与"Bug 状态核对"两节。
|
||
|
||
---
|
||
|
||
## 一、项目方向与当前里程碑
|
||
|
||
**Deshab OS**：SAS-R0 单地址空间 Ring0 内核，UTSM 内置 PE 兼容层 + Linux 兼容层（VMX guest）。
|
||
|
||
**当前里程碑**：M2 — 存储升级 + 中断后端（`docs/系统开发策划.md` §4.4）。
|
||
|
||
**本轮大方向**：通过多智能体并发推进，把 M2 的阻塞点逐个清掉——NVMe 写路径、virtio_net 数据路径、B7 IRQ 后端（APIC/IOAPIC/MSI-X）、PE 兼容层缺陷、用户态输入缺陷、QEMU 测试套件脚本化。
|
||
|
||
---
|
||
|
||
## 二、已落地成果（commit `a26866e` + `019585f`，已核实代码在库）
|
||
|
||
### 1. B7 IRQ 后端（APIC/IOAPIC）— stage1+2 完成
|
||
|
||
- **DKM `apic.drv`**（`CODE/DKM/apic/apic.c`，+1025 行）：LAPIC 接管、MADT/ISO 解析、IOAPIC IOREDTBL 编程（82093AA 位布局已修正 bit13/15/16）、FUCK 开关 `apic_route=0/1`（0=PIC 零回归，1=IOAPIC→LAPIC 接管，失败完整降级）、`apic_route_legacy` 放开 IRQ1/12/11、`apic_diag` HPET 对拍。
|
||
- **UTSM LAPIC EOI 钩子**（`CODE/UTSM/arch/x86_64/idt.c` + `dkm.h` 尾部追加 `register_apic_eoi`，ABI 兼容）：idt_handler 分发后调钩子写 LAPIC EOI，0xFF spurious 特判，PIC EOI 保留无害。DSK diag IDT（`idt_install_dsk_diag`）让 0-31 号异常打印完整现场后安全停机。
|
||
- **tick 链路验证**：route=1 下 500ms 窗口 100 ticks（PIT mode3 双沿触发，定论为 200Hz，BUG-20260803-009 CLOSED，非缺陷）。
|
||
- **生产配置**：FUCK `apic_route=1` 已启用，boot-regression B1-B5 全 PASS（含 FirstInit 向导真实按键走 IOAPIC→LAPIC→IDT 链路）。
|
||
|
||
### 2. NVMe — 写路径 + MSI/MSI-X 中断驱动完成
|
||
|
||
- 写路径 + PRP list 多页 + 读回校验自检（`CODE/DKM/nvme/nvme.c`）。
|
||
- **MSI/MSI-X 中断驱动化**（commit `019585f`）：vector allocator（bitmap+ctzll，0x40-0xDF 池，O(1)）、MSI-X 表项编程、完成槽+irqsave 自适应轮询混合模型、**幽灵 CQE 三层 CID 校验防御**（BUG-20260803-010 FIXED，QEMU 在 unmask 边界补投 CID=0 幽灵 CQE）、handler 自写 LAPIC EOI。FUCK `nvme_msi=1` 默认开，0 强制轮询。
|
||
- 三配置回归全绿（MSI-X / route=0 PIC / nvme_msi=0 纯轮询），driver-matrix.ps1 PASS。
|
||
|
||
### 3. virtio_net — virtqueue RX/TX 完成（纯轮询，无 MSI-X）
|
||
|
||
- legacy transitional 探测、feature negotiation、RXQ/TXQ 各 256 描述符、netdev 注册 index=1、boot 时 DHCP 自测（slirp 真实 OFFER）。
|
||
- **数据路径纯轮询**：rx_poll 轮询 used ring，TX 后同步等待。IRQ handler 已注册但未用于数据路径。
|
||
- **MSI-X 中断驱动化未完成**（W6-B 丢失，见第三节）。
|
||
|
||
### 4. PE 兼容层 — 004/005/006/007 全部修复
|
||
|
||
- **BUG-004**（gen_pe.py PE32+ RVA 偏置）：call disp32 偏移 + import RVA 全部加 code_rva 偏置，重新生成 hello64/hello32/cmd.exe。
|
||
- **BUG-005**（DSK 阶段异常无法投递）：`idt_install_dsk_diag` 装配最小 IDT，#PF/#GP/#DF 打印向量+CR2+RIP+CS 后 cli;hlt。
|
||
- **BUG-006**（pe_shim longjmp 跨已返回函数 UB）：setjmp 下沉到 `pe_service_run` 本体，`g_exit_jmp[24]` 缓冲区，`pe_shim_setup_exit` 只提供缓冲区（setjmp 帧在 PE 执行全程存活）。
|
||
- **BUG-007**（shim fn32 guest 指针当 host 指针）：`g_emu_mem_base` + `pe_shim_set_emu_base()` + `gp()` 转换（va<0x10000000 加基址），原生路径恒等映射零影响。
|
||
- **Deaicup GUI** 端到端验证通过（首帧渲染 + PS/2 键盘 + AUX 鼠标 + 软件光标 + Esc 退出链），raster.rs 重心坐标符号 bug 顺带修复。
|
||
|
||
### 5. 用户态输入/加载 — 001/002/003/008 全部修复
|
||
|
||
- **BUG-001**（shell 吞 y/i/0）：Ctrl 修饰键跟踪（0x1D/0x9D），快捷键仅 Ctrl 按下时生效。
|
||
- **BUG-002**（g_run_image 256KB）：扩至 1MB，editor.elf（496KB 内存镜像）可加载。
|
||
- **BUG-003**（da_mouse_poll 吞键盘扫描码）：先判 AUX 位（st&0x20）再读 0x60。
|
||
- **BUG-008**（da_mouse_init 配置字污染）：序列首尾 da_ps2_drain 冲刷残留，配置字补 0x40，复位读完 FA AA 00。
|
||
|
||
### 6. QEMU 测试套件 — 9 用例全自动化
|
||
|
||
`tests/qemu/`（commit `a26866e` 已入库，已核实存在）：
|
||
- `lib/QemuTest.ps1`：公共框架（启动 QEMU/计时杀/串口断言/monitor TCP sendkey/screendump/HTTP 服务器/并发隔离端口分配）。
|
||
- 9 用例：`boot-regression` / `driver-matrix` / `linux-compat` / `pe-compat` / `deaicup-e2e` / `userapps-matrix` / `network-e2e` / `performance-baseline` / `x86emu32-coverage`。
|
||
- `Run-All.ps1`：汇总表 + 退出码。
|
||
- W5-A 基线实跑 8/9 PASS（唯一 FAIL 是 cmd AUTOEXEC 缓冲别名，见 BUG-011）。
|
||
- `docs/RE/test-cases/` 8 份用例文档均补"自动化脚本"小节。
|
||
|
||
---
|
||
|
||
## 三、未完成工作（W6 三波成果全部丢失，需重做）
|
||
|
||
> 第六波并发三线（W6-A/B/C）的 subagent 报告完成，但**改动未入库**（工作区干净，代码核实无对应实现）。下个 agent 需重做。
|
||
|
||
### W6-A：cmd AUTOEXEC 缓冲别名修复（BUG-011，P1）
|
||
|
||
- **根因**（已定位定案）：`f32_read_root_file`（`CODE/tools/fat32_io.h`）把文件读入**共享静态缓冲** `f32_data` 并返回指针；`run_autoexec`（`CODE/cmd/main.c` L1232）跨 `execute_command` 持有该指针逐行执行；首行 `pe HELLO32.EXE` 加载 PE 文件覆盖缓冲中剩余 AUTOEXEC 脚本 → `exit` 行丢失 → cmd 落入交互主循环永远轮询键盘。
|
||
- **影响**：任何"读文件的 AUTOEXEC 命令 + 后续行"组合。历史上从无"真实 PE 执行后 `[DSK] cmd.elf returned`"。
|
||
- **修法**（W6-A 已设计未入库）：`run_autoexec` 先把脚本整体拷入私有缓冲 `g_autoexec_snapshot[4096]` 再逐行执行。`CODE/cmd/main.c` 当前 L1232 仍是原样，**需重做**。
|
||
- **验证**：修复后 x86emu32-coverage.ps1 末锚点 `[DSK] cmd.elf returned` 转绿（该用例硬断言已就位，W6-A 报告复跑 PASS 但成果丢失）。
|
||
- **登记**：Bug记录.txt **无 011 条目**（W6-A 报告登记了但未入库），需补登。
|
||
|
||
### W6-B：virtio_net MSI-X 中断驱动 RX/TX
|
||
|
||
- **现状**：virtio_net.c 有 virtqueue RX/TX（纯轮询），**无 MSI-X 代码**（Select-String 'msix|MSI-X' 无匹配）。
|
||
- **W6-B 设计**（未入库）：legacy transitional + MSI-X 组合，三向量（cfg/RXQ/TXQ）编程，SPSC pending 环 IRQ 上下文收包，三级降级（MSI-X→INTx→轮询），FUCK `vnet_msi=1` 开关。参考 NVMe 的 `nvme_msix_program` 模式。
|
||
- **需重做**。QEMU 拓扑：e1000@net0 + virtio-net-pci@net1。
|
||
|
||
### W6-C：用户态工具串口锚点增补 + 策划文档收尾
|
||
|
||
- **现状**：`CODE/tools/editor.c` / `curl.c` / `ping.c` / `browser.c` **无** `[editor] saved` / `[curl] http status` / `[ping] reply` / `[browser] loaded` 锚点（Select-String 无匹配）。
|
||
- **W6-C 设计**（未入库）：为各工具补 1-3 个关键事件串口锚点，升级 userapps-matrix.ps1 / network-e2e.ps1 的 MANUAL 项为自动断言。
|
||
- **需重做**。
|
||
|
||
---
|
||
|
||
## 四、Bug 状态核对表（重要 — 文档与代码不符）
|
||
|
||
> `docs/RE/Bug记录.txt` 中以下条目**代码已修复并提交（a26866e）但状态仍标 [OPEN]**，本次交接已修正为 [FIXED]。
|
||
|
||
| Bug | 登记状态 | 代码实际 | 本次处理 |
|
||
|-----|---------|---------|---------|
|
||
| BUG-20260801-005 DSK 异常无法投递 | [OPEN] | ✅ idt_install_dsk_diag 已落地 | 改 [FIXED] |
|
||
| BUG-20260801-006 pe_shim longjmp UB | [OPEN] | ✅ g_exit_jmp 重构已落地 | 改 [FIXED] |
|
||
| BUG-20260801-007 shim fn32 guest 指针 | [OPEN] | ✅ g_emu_mem_base+gp() 已落地 | 改 [FIXED] |
|
||
| BUG-20260803-011 cmd AUTOEXEC 别名 | **未登记** | ❌ 代码未入库 | 需补登 + 重做修复 |
|
||
|
||
其余已 FIXED 条目（001/002/003/004/008/010）状态正确。009 CLOSED（定论非缺陷）。
|
||
|
||
---
|
||
|
||
## 五、新出现的并行工作（8/5 下午，commit `6287513` + `4a62932`）
|
||
|
||
> 这两批提交不是本轮多智能体推进的产物，是另一条线的工作，接手时注意区分：
|
||
|
||
- **Linux 预览后端**（`6287513`）：`CODE/tools/desktop_app_linux.h`（跨平台后端抽象）、`CODE/desktop/host_main.c`/`host_main.h`（桌面宿主 Linux 预览）、`ISO/run_desktop_host.sh`、Notes 应用预览（`CODE/tools/notes/`，5x7 位图字体）。
|
||
- **PE DLL 管理器**（`4a62932`）：`CODE/UTSM/pe/pe_dll_manager.c/h`（新模块，PE DLL 加载管理）。
|
||
- **FAT32 长文件名**：`CODE/tools/fat32_lfn.h`。
|
||
- **上下文目录重命名**：`docs/上下文/250729`→`260729`、`25072901`→`26072901`（年份修正 25→26）。
|
||
|
||
接手者若推进这些方向，先读对应源码理解现状。
|
||
|
||
---
|
||
|
||
## 六、下一步优先级建议
|
||
|
||
| 优先级 | 任务 | 理由 |
|
||
|--------|------|------|
|
||
| **P1** | 重做 W6-A：cmd AUTOEXEC 缓冲别名（BUG-011） | 阻断 x86emu32-coverage 用例，影响所有 AUTOEXEC 多行场景；修法简单（私有快照缓冲） |
|
||
| **P1** | 补登 BUG-011 条目 + 核对 Bug记录其余状态 | 文档与代码一致性 |
|
||
| **P2** | 重做 W6-B：virtio_net MSI-X | NVMe MSI-X 已完成可参照；virtio_net 当前纯轮询，中断化收益明确 |
|
||
| **P2** | M2 剩余：e1000 中断驱动收发（替代 polling） | 策划 L134 仍空；e1000 走 legacy IRQ11 已通，MSI 切换成本低 |
|
||
| **P3** | 重做 W6-C：tools 串口锚点 + 测试断言升级 | 把 MANUAL 项回收为自动化 |
|
||
| **P3** | M2 收尾：替换 arena 为真实页分配（L129）、DKM 工程化（ABI 头统一/零 warning，L136） | 策划仍空 |
|
||
| **P3** | 真机冒烟：APIC/MSI-X 在真机验证（QEMU 无多 IOAPIC/非常规 GSI） | W4-B/W5-B 均提遗留 |
|
||
| **P4** | M3 兼容层验证推进（VMX 真机/KVM） | B4 阻塞，需嵌套虚拟化环境 |
|
||
|
||
---
|
||
|
||
## 七、环境与协作约定（坑点合集，务必读完）
|
||
|
||
### 构建环境
|
||
- Windows + **PowerShell 5.1**（不能用 `&&`/`||`/三元）。
|
||
- `make.exe` 在 `C:\mingw64\bin`，clang/ld.lld 在 LLVM bin。
|
||
- 全量构建：根目录 `build.ps1`。UTSM 编译：`CODE/UTSM/MAKEFILE`（-MMD -MP，零警告）。
|
||
- **工具 MAKEFILE 普遍缺头文件依赖**：改 `desktop_app.h` 等公共头不会触发工具重编，需手动删对应 `.o`。
|
||
- **仓库内 .ps1 一律纯 ASCII**：PS5.1 把无 BOM UTF-8 按 GBK 解码，CJK 注释第三字节（0x80-0xBF）被当 GBK lead byte 会吞掉紧跟换行符，把后续代码并进注释。编辑已有含 BOM 文件保留 BOM。
|
||
|
||
### QEMU
|
||
- `ISO/run_qemu.bat`（WHPX）。WHPX 在 PE 执行处会 VP exit 4，pe-compat/deaicup-e2e 已有 TCG 自动兜底。
|
||
- **`-snapshot` 必加**（镜像只读，防 deshab.img 锁冲突，多代理并发必备）。
|
||
- monitor TCP 端口分配：deaicup-e2e 固定 45454，测试套件 45501-45509，其他按需避让。
|
||
- **Start-Process 下 `-serial file:` 不生效**（已知坑）：用临时 cmd 批处理 + `-serial stdio` 重定向到日志文件，计时按 PID 杀。
|
||
- **monitor screendump 路径必须正斜杠**：反斜杠 `\C` 转义静默失败。
|
||
- `-d reset` 非法（本版叫 `cpu_reset`）。
|
||
- 并发时**只杀自己启动的 QEMU（记 PID），绝不全局 `Stop-Process qemu`**。
|
||
|
||
### 多智能体并发协议（若继续用多 agent）
|
||
- **构建互斥**：`build.ps1` 前检查 `.build_tmp\BUILD.lock`：存在且 30 分钟内则 `Start-Sleep 15-30s` 重试，不存在才创建（写名字+PID+时间），构建+打包完成**立即删除**。
|
||
- 地盘划分：UTSM/DKM/desktop/cmd/tools/tests 分属不同 agent，不交叉改动。
|
||
- **subagent 改动落地风险**：本轮 W6 三线 subagent 报告完成但改动未入库——**接手者用 subagent 后务必核实改动是否落盘主仓库工作区**（`git status` + Grep 代码），不能只信报告。建议关键修复由主会话直接 Edit/Write 落盘。
|
||
|
||
### kernel_api ABI
|
||
- 结构体 **ABI 冻结**：成员顺序/签名不可改，**只允许尾部追加**。本轮已追加 `register_apic_eoi`、`irq_vector_alloc/free`（dkm.h 尾部）。
|
||
|
||
---
|
||
|
||
## 八、关键文件索引
|
||
|
||
| 模块 | 关键文件 |
|
||
|------|---------|
|
||
| APIC/IOAPIC | `CODE/DKM/apic/apic.c`、`CODE/UTSM/arch/x86_64/idt.c`（EOI 钩子+DSK diag+vector allocator）、`CODE/UTSM/include/utsm/dkm.h`（kernel_api 尾部追加） |
|
||
| NVMe | `CODE/DKM/nvme/nvme.c`（写+MSI-X+CID 防御）、`SYSTEM/system/deshab64/FUCK`（nvme_msi 开关） |
|
||
| virtio_net | `CODE/DKM/virtio_net/virtio_net.c`（virtqueue 轮询，**无 MSI-X**） |
|
||
| PE 兼容层 | `CODE/UTSM/pe/pe_shim.c`（g_exit_jmp/g_emu_mem_base）、`pe_service.c`、`pe_loader.c`、`CODE/UTSM/pe/pe_dll_manager.c`（新）、`CODE/tools/pe-samples/gen_pe.py` |
|
||
| 用户态 | `CODE/shell/main.c`（Ctrl 跟踪+g_run_image 1MB）、`CODE/cmd/main.c`（**run_autoexec 待修**）、`CODE/tools/desktop_app.h`（da_mouse_init/poll）、`CODE/tools/editor.c`/`curl.c`/`ping.c`/`browser.c`（**锚点待补**） |
|
||
| 测试套件 | `tests/qemu/Run-All.ps1`、`tests/qemu/lib/QemuTest.ps1`、9 用例脚本 |
|
||
| 配置 | `SYSTEM/system/deshab64/FUCK`（apic_route/nvme_msi/vnet_msi/dev_mode 等） |
|
||
| 文档 | `docs/系统开发策划.md`（M2 进度）、`docs/RE/Bug记录.txt`、`docs/RE/test-cases/`、`docs/RE/桌面设计.md`、`LESSONS_LEARNED.md`、`CLAUDE.md` |
|
||
|
||
---
|
||
|
||
## 九、本轮提交时间线
|
||
|
||
| commit | 时间 | 内容 |
|
||
|--------|------|------|
|
||
| `a26866e` | 8/4 18:08 | **大合并**：B7 APIC stage1+2、NVMe 写+MSI-X、virtio_net virtqueue、PE 004-007、用户态 001-003/008、9 用例测试套件、文档 |
|
||
| `019585f` | 8/4 18:36 | B7 阶段3：NVMe MSI-X 增强 + vector allocator + 幽灵 CQE 防御（BUG-010） |
|
||
| `6287513` | 8/5 13:15 | Linux 预览后端 + Notes 应用（并行工作，非本轮） |
|
||
| `4a62932` | 8/5 13:58 | PE DLL 管理器 + desktop host + fat32_lfn + 上下文目录重命名（并行工作） |
|