Deshab-OS/docs/系统开发策划.md

# Deshab 系统开发策划

> 文档盘点、实现矩阵、阻塞风险、里程碑策划。ROADMAP的补充（补上兼容层/桌面/包管理等用户态生态主线）。

---

## 一、文档整理

### 1.1 文档地图

```text
docs/ARCHITECTURE.md        五大支柱+子系统现状
docs/BOOT_SEQUENCE.md       五阶段启动模型
docs/ROADMAP.md             Phase 0–9路线图
docs/系统开发策划.md         ← 本文档
docs/兼容层设计.md           Linux/PE兼容层
docs/桌面设计.md             桌面环境
docs/RE/                    UTSM_设计架构/算法记录/驱动模块ABI设计/Bug记录(12条)/test-cases(8份)/docs/
docs/上下文/                 开发对话记录（待提炼为正式设计文档）
```

### 1.2 文档同步状态

2026-07-29已同步：ROADMAP/ARCHITECTURE/BOOT_SEQUENCE/Bug记录。关键偏差均已修正（如§9.2旋转环描述、console_fb圆弧已移除、B4正常路径已实现login→desktop）。

**关键发现**：`docs/上下文/`下四份开发记录（双内核/Linux EXE/桌面UI/Pacman）构成ROADMAP未收录的**用户态与生态主线**。

---

## 二、实现盘点

### 2.1 子系统实现状态矩阵

| 子系统 | 状态 | 主要缺口 |
|--------|------|---------|
| 早期启动(serial/IDT/PIC) | ✅ | — |
| DKM驱动加载(14驱动) | ✅ | ABI头未统一、warning未清零 |
| DMA分配器 | ✅ | — |
| UTSM封缄内存 | 🔶 | 真实加密原语未选型 |
| AHCI块设备 | ✅ | 单扇区偶发超时 |
| NVMe | ✅ | 写路径+PRP list+读回校验已完成 |
| FAT32 | 🔶 | DKM只读；DSK读写（根目录），子目录写待补 |
| e1000网络 | ✅ | 中断驱动收发（仍polling） |
| virtio_net | ✅ | virtqueue RX/TX+netdev注册+DHCP自测已完成 |
| 字体系统 | ✅ | — |
| FirstInit | 🔶 | B6按键崩溃修复中；鼠标仍轮询 |
| 正常启动路径 | ✅ | — |
| desktop.elf | ✅ | 脏矩形未做 |
| shell.elf / cmd.elf | ✅ | — |
| Linux兼容层 | 🔶 | VMX实机验证待做（需嵌套虚拟化环境） |
| PE/EXE兼容层 | ✅ | Win32 API覆盖少 |
| virtio-mmio模拟 | 🔶 | blk已支撑guest rootfs；net后端未在guest验证 |
| SAS-R0-PCQ调度器 | ⬜ | 未实现 |
| DRR恢复系统 | ⬜ | 未实现 |
| 真实加密 | ⬜ | 原语未选型 |
| Pacman包管理 | 🔶 | 依赖VMX验证+virtio-net后端 |

### 2.2 关键能力清单

- **kernel_api**：log/rsdp/fb_*/boot_modules/irq_register/hhdm/dma.alloc_pages/block(read@+0xA8,write@+0x18)/net
- **dsk_boot_context**：magic `0x44534B31424F4F54`，reserved[4]=pe_service，reserved[5]=linux_compat_service
- **PE service**：load/run/unload（PE32+原生Ring0，PE32走x86emu32）
- **Linux compat service**：exec(path,argv)→IPC EXEC_REQUEST(16)→daemon fork+exec→STDOUT/STDERR/EXIT
- **IPC**：1MB共享内存@GPA 0x04000000，9+5 hypercall，VMCALL RAX=`0x5554534D48430000|op`
- **FAT32**：f32_read_root_file / f32_write_root_file

---

## 三、阻塞与风险

### 3.1 关键阻塞点

| # | 阻塞点 | 严重度 | 缓解 |
|---|--------|--------|------|
| B1 | ~~block write~~ ✅已解决 | — | AHCI WRITE DMA+block_api.write已落地 |
| B2 | ~~高位PCI MMIO映射缺失~~ ✅已解决 | — | NVMe BAR0可读，写路径+PRP list+读回校验通过 |
| B3 | ~~WSL构建阻塞~~ ✅已解决 | — | bzImage/initrd/rootfs已产出 |
| **B4** | QEMU TCG不支持VMX | P0 | 真机VT-x/KVM/云VM验证；WHPX检测已落地 |
| B5 | ~~fileman QEMU exit~~ ✅已解决 | — | linker.ld BSS NOBITS分离+g_elf_image扩至1MB |
| **B6** | FirstInit按键崩溃 | P1 | fb_text边界检查+编译优化降级调试中 |
| **B7** | APIC/IOAPIC stage1 已落地（LAPIC接管/MADT/IOREDTBL/apic_route开关/tick链路验证） | P2 | UTSM LAPIC EOI、IDT 256+vector allocator、MSI-X 进行中（Phase 2） |

### 3.2 风险登记

| 风险 | 概率 | 影响 | 应对 |
|------|------|------|------|
| VMX实机验证长期受阻 | 中 | 高 | 构建产物已就位；窗口期内争取验证，失败则冻结运行时 |
| ROADMAP与实现态偏离 | 高 | 中 | 本次整理后同步 |
| docs/上下文/对话膨胀 | 高 | 中 | 提炼为正式设计文档 |
| UTSM真实加密原语选型拖延 | 中 | 高 | Phase 9前完成PoC |
| PE32+原生执行安全风险 | 中 | 中 | PE shim白名单+IAT拦截审计 |

---

## 四、开发策划

### 4.1 策划原则

先闭环再扩展；解阻塞优先于新功能；内核主线与生态主线并行；不破坏SAS-R0/O(1)热路径；文档与代码同步。

### 4.2 里程碑总览

```text
M1 持久化闭环+桌面稳定     (2–4周)  B1→FAT32 write→FirstInit写盘→桌面bug
M2 存储升级+中断后端       (4–8周)  B2高位MMIO→NVMe→B7 APIC/IOAPIC/MSI-X→e1000中断驱动
M3 兼容层验证             (与M2并行) B3/B4→Linux guest→IPC→Arch rootfs
M4 调度器+恢复+加密       (8–16周) SAS-R0-PCQ→DRR→真实加密
M5 软件生态               (依赖M3)  Pacman→AUR→desktop集成
```

### 4.3 M1 — 持久化闭环+桌面稳定

| 任务 | 验收标准 |
|------|---------|
| AHCI WRITE DMA | dkm_block_api.write注册 |
| FAT32文件覆写/创建 | f32_write_root_file可写user.conf/firstInit.txt |
| FAT32 FAT链分配 | 新文件可创建、可追加 |
| FirstInit user.conf写盘 | 重启后login可读取 |
| FirstInit鼠标光标 | PS/2 IRQ12+包解码+24×24光标 |
| 桌面fileman崩溃修复(B5) | fileman可正常使用 |
| FirstInit按键崩溃修复(B6) | -O2下fb_text稳定 |

### 4.4 M2 — 存储升级+中断后端

| 任务 | 验收标准 | 进度 |
|------|---------|------|
| 页表映射接口 | mmio_map/unmap通用接口 | ✅ |
| 高位PCI MMIO映射(B2) | NVMe BAR0可读register | ✅（NVMe 数据路径已验证） |
| 替换arena为真实页分配 | 移除16MB arena上限 | |
| NVMe admin queue/identify+block provider | 注册nvme0 | ✅ 写路径+PRP list+读回校验完成 |
| IDT扩展256 vectors+vector allocator | 动态分配中断向量 | |
| APIC EOI→IOAPIC redirection→LAPIC timer | 替代PIC | 🔶 stage1 完成（LAPIC接管/MADT/IOREDTBL/apic_route开关/tick链路验证），UTSM LAPIC EOI 进行中 |
| MSI/MSI-X | NVMe/e1000使用MSI-X | |
| e1000中断驱动收发 | 替代polling | |
| virtio-net virtqueue RX/TX | 收发包成功 | ✅ virtqueue RX/TX+netdev注册+DHCP自测完成 |
| DKM工程化收尾 | 统一ABI头、零warning | |
| QEMU测试套件脚本化 | Run-All 全用例自动化 | ✅ 9 用例（8+deaicup-e2e）全自动化 PASS |

### 4.5 M3 — 兼容层验证

| 任务 | 验收标准 |
|------|---------|
| Linux 6.6 LTS构建+VMX运行环境 | bzImage+initramfs生成，真机VT-x或KVM可用 |
| VMX自测→Linux guest跑到shell | initramfs busybox shell可交互 |
| utsm_exec_daemon运行 | EXEC_READY(20)发送，park生效 |
| virtio-blk/net后端验证 | guest内可读写块/DHCP/ping |
| IPC exec全链路 | `linux ls`→stdout回显 |
| Arch rootfs bootstrap | pacman可用 |

### 4.6 M4 — 调度器+恢复+加密

| 任务 | 验收标准 |
|------|---------|
| SAS-R0-PCQ: TCB+task_create, Per-CPU runqueue, O(1)位图调度, context_switch(只加载crypto指针), task_kill crypto erase | 多任务调度运行 |
| DRR: Emergency Pool, Watchdog, Recovery log, Dirty Shard+Bitmap, A/B Checkpoint双槽, 三级Rollback, 驱动recovery ops | checkpoint/rollback演示 |
| 真实加密: 原语选型PoC(HKDF+AES-CTR+Poly1305), KDF, Stream cipher(64B line), MAC(4KB page), PCKC真实key schedule | UTSM真实加密selftest通过 |

### 4.7 M5 — 软件生态

| 任务 | 验收标准 |
|------|---------|
| FILE_TRANSFER+EXEC_FORWARD hypercall | 跨内核文件传输+命令委托 |
| shell path_search_and_run扩展 | PATH命中stub→IPC委托 |
| pacman装包+AUR helper | `pacman -S <pkg>`成功 |
| desktop动态Linux命令图标 | 点击图标运行Linux应用 |

### 4.8 依赖关系

```text
B1(block write)→FAT32 write→user.conf写盘→M1闭环
B2(高位MMIO)→NVMe; B7(IRQ后端)→APIC/IOAPIC/MSI-X→e1000中断驱动+virtio-net
B3(Linux构建)+B4(VMX环境)→VMX验证→guest shell→daemon→IPC→Arch rootfs
M1→M4调度器→DRR→真实加密; Arch rootfs→M5 Pacman→AUR→desktop集成
```

---

## 五、文档治理建议

**立即**：同步ROADMAP状态标记；结构化Bug记录(BUG-YYYYMMDD-NNN模板)。

**中期**：`docs/上下文/双内核+Linux_EXE`→`docs/兼容层设计.md`；`docs/上下文/桌面UI`→`docs/桌面设计.md`；Pacman→合并进兼容层设计§生态。

**长期**：PR必须同步ROADMAP+设计文档；test-cases关联可执行脚本；CLAUDE.md季度回顾。

---

## 六、附录：关键技术参考速查

### 6.1 关键地址与魔数

| 项 | 值 |
|----|-----|
| dsk_boot_context.magic | `0x44534B31424F4F54` "DSK1BOOT" |
| dkm_driver_desc.magic | `0x444B4D31` "DKM1" |
| VMCALL RAX | `0x5554534D48430000|op` "UTSMHC\0\0" |
| IPC共享内存GPA | `0x04000000`(1MB) |
| Linux guest RAM GPA | `0x05000000+`(64MB) |
| block_read偏移 | `kernel_api + 0xA8`(read@+0x10, write@+0x18) |
| pe_service槽 | `reserved[4]` |
| linux_compat_service槽 | `reserved[5]` |
| IPC exec消息号 | 16–20 |
| ipc_exec_request约束 | ≤240字节 |
| virtio-blk/net IRQ | 5/6（向量0x35/0x36） |

### 6.2 关键约束清单

- 进入C前cli/cld；早期serial不无限等待ready位
- 未启用SSE前-mno-sse -mno-sse2 -mno-mmx -msoft-float
- DATA/BSS用PF_R|PF_W|PF_X
- DSK ibuf 1MB；g_dsk_fat32_filedata 2MB；g_fdata 1MB
- FAT32批量读≥8扇区(推荐256)；DSK linker.ld BSS分离NOBITS
- mkfat32.ps1 Name83正好11字符；Linux guest cmdline含nohlt idle=poll
- VMCS不保存guest GPR，vmexit_asm.S保存16个GPR到g_guest_regs
- 调度热路径禁止扫描capability/计算MAC/写checkpoint/重加密
- DRR recovery路径禁止依赖普通堆；PE32+用__attribute__((ms_abi)) shim

### 6.3 关键文件索引

| 模块 | 文件 |
|------|------|
| UTSM入口 | `CODE/UTSM/kernel/main.c` |
| DSK加载 | `CODE/UTSM/kernel/dsk_loader.c` |
| boot context | `CODE/UTSM/include/utsm/dsk.h` |
| VMM | `CODE/UTSM/vmm/vmm.c/vmexit.c/linux_boot.c/linux_resume.c/vmexit_asm.S` |
| PE兼容层 | `CODE/UTSM/pe/pe_service.c/pe_loader.c/pe_shim.c/x86emu32.c` |
| Linux compat | `CODE/UTSM/vmm/linux_compat.c` |
| IPC | `CODE/utsm-ipc/ipc_proto.h` |
| exec daemon | `CODE/linux/initramfs/bin/utsm_exec_daemon.c` |
| DSK | `CODE/dsk/main.c` |
| 桌面 | `CODE/desktop/main.c` |
| shell/cmd | `CODE/shell/main.c`, `CODE/cmd/main.c` |
| FAT32镜像 | `.build_tmp/mkfat32.ps1` |