FUCKYOU

2026-07-28 21:11:10 +08:00
parent 537890df9e
commit 2774c10d0c
49 changed files with 4019 additions and 94 deletions
@@ -1,6 +1,39 @@
-开发者模式中启动的Shell的提示符没有在第一行也没有显示
-shell光标没有闪烁
-Login界面没有显示鼠标指针
-在桌面上时每按下按键屏幕就会闪烁
-窗口打开和关闭时的动画太卡，而且屏幕会闪，直接去掉动画
-启动一次之后，第二次开机启动会直接退出
+# Deshab Bug 记录
+
+> 所有测试与开发过程中发现的 bug 统一登记于此。每个 bug 按 BUG-YYYYMMDD-NNN 编号。
+> 测试用例文档位于 RE/test-cases/。
+
+## 严重程度定义
+
+- P0 阻断: 影响主链路启动或核心功能完全不可用（必须立即修复）
+- P1 严重: 功能可降级但关键路径受损（本轮内修复）
+- P2 一般: 非关键路径异常或体验问题（下一里程碑前修复）
+- P3 提示: 日志/小问题，不影响功能（记录备查）
+
+## Bug 条目格式
+
+```
+### BUG-YYYYMMDD-NNN [P级] [模块] 简述
+- 现象:
+- 复现步骤:
+- 串口/日志证据:
+- 根因分析:
+- 修复方案:
+- 状态: [OPEN/FIXING/FIXED/CLOSED]
+- 修复提交: <commit hash 或 "待提交">
+- 验证: <验证方法与结果>
+```
+
+---
+
+## Bug 列表
+
+<!-- 在此追加 bug 条目，最新放在顶部 -->
+P2: 软件Files的窗口点击叉无法关闭
+P3: 在第一页已经有了终端，所以在第四页的桌面上不用显示终端和CMD
+P2: 在开发者模式中的shell输入命令并回车时文字消失没有反应
+P3: 启动时的打字机效果再快3倍
+P2: 桌面中第一页的shell中输入命令回车后，上一条命令输入的文字会跑到下一行
+P2: 桌面中第一页的Files显示的不是SYSTEM/user中的文件夹内容
+P2: Files中没有显示文件夹，直接显示了文件夹下的文件
+P2: Files没有提供“..”来供用户返回上一级的文件夹
@@ -0,0 +1,38 @@
+# Deshab 测试用例矩阵
+
+本目录组织 Deshab-OS 的系统化测试用例文档。
+
+## 测试矩阵总览
+
+| 文档 | 范围 | 优先级 |
+|---|---|---|
+| [boot-regression.md](boot-regression.md) | 启动链路回归（首启/正常/dev_mode/无盘/无NIC） | P0 |
+| [linux-compat.md](linux-compat.md) | UTSM+Linux 双内核兼容层端到端 | P0 |
+| [pe-compat.md](pe-compat.md) | PE/EXE 兼容层（PE32+ native + PE32 x86emu32） | P1 |
+| [driver-matrix.md](driver-matrix.md) | 14 DKM 驱动功能矩阵 | P1 |
+| [userapps-matrix.md](userapps-matrix.md) | 用户态程序矩阵（shell/cmd/desktop/tools） | P1 |
+| [network-e2e.md](network-e2e.md) | 网络端到端（DHCP/ARP/DNS/ping/curl） | P1 |
+| [performance-baseline.md](performance-baseline.md) | 性能基线（TSC 测量） | P2 |
+| [x86emu32-coverage.md](x86emu32-coverage.md) | x86emu32 指令覆盖率 | P2 |
+
+## 测试场景状态标记
+
+- ✅ PASS: 全部测试项通过
+- 🔶 PARTIAL: 部分测试项通过，存在已知限制
+- ❌ FAIL: 关键测试项失败，需修复
+- ⬜ PENDING: 未执行
+- ⏭ SKIP: 因环境/依赖不可用而跳过
+
+## 自动化执行
+
+```powershell
+# 运行全部自动化测试场景
+.\ISO\run_tests.bat
+
+# 输出
+# ISO/logs/test-report-<timestamp>.md
+```
+
+## Bug 跟踪
+
+所有测试发现的 bug 登记到 [../Bug记录.txt](../Bug记录.txt)，并在对应测试文档中引用 bug 编号。
@@ -0,0 +1,96 @@
+# 启动链路回归测试矩阵
+
+> 对应计划 Phase C2：验证不同启动场景下系统行为正确
+
+## 状态: ⬜ PENDING
+
+## 测试场景
+
+| # | 场景 | firstInit.txt | 配置 | 期望串口锚点 | 状态 | Bug# |
+|---|---|---|---|---|---|---|
+| B1 | 首次启动 | `0\n0` | 空 user.conf | `[DSK] firstInit=0` → `mouseInit` → `FirstInit` → 完成向导 → 写盘 | ⬜ | |
+| B2 | 正常启动 | `1\n0` | 已有 user.conf | `[DSK] firstInit=1` → `login` → desktop | ⬜ | |
+| B3 | dev_mode | `1\n1` | dev_mode=1 | `[DSK] dev_mode` → shell run_dev_tests 全绿 → Esc → 正常流程 | ⬜ | |
+| B4 | 无 SATA 盘 | 任意 | 移除 sata_fat32_dsk.img | DSK fallback 到 Limine module | ⬜ | |
+| B5 | 无 NIC | 任意 | 移除 `-netdev` | e1000 not found → netman 警告 → 继续启动 | ⬜ | |
+| B6 | Linux 兼容层启用 | 任意 | +linux-bzImage +linux-initrd | UTSM VMM + Linux park → DSK 正常接管 | ⬜ | |
+
+## 串口日志锚点（标准启动）
+
+### 首次启动（B1）
+
+```
+[UTSM] boot
+[UTSM] SELFTEST PASS
+[UTSM] loading DSK
+[DSK] boot
+[DSK] context ok
+[DSK] firstInit=0
+[DSK] loading mouseInit.elf
+[DSK] loading FirstInit.elf
+[FirstInit] ...
+[DSK] writing firstInit=1
+[DSK] loading shell.elf
+```
+
+### 正常启动（B2）
+
+```
+[UTSM] boot
+[UTSM] SELFTEST PASS
+[UTSM] loading DSK
+[DSK] boot
+[DSK] firstInit=1
+[DSK] loading login.elf
+[DSK] loading desktop.elf
+```
+
+### dev_mode（B3）
+
+```
+[UTSM] boot
+[UTSM] SELFTEST PASS
+[DSK] dev_mode=1
+[DSK] loading shell.elf
+[shell] run_dev_tests:
+[shell]   ls: OK
+[shell]   echo>: OK
+[shell]   cat: OK
+[shell]   cp: OK
+[shell]   mv: OK
+[shell]   rm: OK
+[shell] dev_tests done
+... (Esc 返回后正常流程)
+```
+
+## 自动化脚本
+
+[ISO/run_qemu_scenario.bat](../../ISO/run_qemu_scenario.bat) 接收场景名参数：
+
+```powershell
+.\ISO\run_qemu_scenario.bat firstboot
+.\ISO\run_qemu_scenario.bat normal
+.\ISO\run_qemu_scenario.bat devmode
+.\ISO\run_qemu_scenario.bat nosata
+.\ISO\run_qemu_scenario.bat nonic
+.\ISO\run_qemu_scenario.bat linux
+```
+
+每个场景输出独立日志到 `ISO/logs/<scenario>-<timestamp>.log`。
+
+## 配置文件准备
+
+### B1 首次启动
+
+- `SYSTEM/system/user/use/firstInit.txt`: `0\n0`
+- 备份 `user.conf` 后清空内容（仅保留 `DESHAB_USERCONF_V1` 头）
+
+### B3 dev_mode
+
+- `firstInit.txt`: `1\n1`
+- 保持现有 user.conf
+
+### B4 无 SATA
+
+- 临时重命名 `.build_tmp/sata_fat32_dsk.img` → `.build_tmp/sata_fat32_dsk.img.bak`
+- run_qemu.bat 自动检测，缺失时跳过 `-device ide-hd`
@@ -0,0 +1,70 @@
+# 14 DKM 驱动功能矩阵
+
+> 对应计划 Phase C3：每个驱动的加载、探测、功能验证点
+
+## 状态: ⬜ PENDING
+
+## 驱动清单
+
+| # | 驱动 | stage | class | required | QEMU 参数 | 期望串口日志 | 功能验证点 | 状态 | Bug# |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 | timer | 0 | timer | ✅ | 默认 | `[DKM:timer]` | 100ms busy-wait 精度 | ⬜ | |
+| 2 | apic | 0 | interrupt | ✅ | 默认 | `[DKM:apic] MADT found` | LAPIC MMIO 只读 | ⬜ | |
+| 3 | acpi | 0 | platform | ❌ | 默认 | `[DKM:acpi]` | RSDP/XSDT 枚举 | ⬜ | |
+| 4 | pci | 0 | bus | ✅ | 默认 | `[DKM:pci]` | PCI config space 扫描 | ⬜ | |
+| 5 | console_fb | 1 | console | ❌ | 默认 | `[DKM:console_fb]` | 淡蓝色背景清屏 | ⬜ | |
+| 6 | ahci | 1 | storage | ❌ | +SATA 测试盘 | `[DKM:ahci] ahci0 registered` | LBA0 读取 | ⬜ | |
+| 7 | nvme | 1 | storage | ❌ | `-device nvme` | `[DKM:nvme] 1b36:0010 found` | BAR0 读取（高位 MMIO 未解决则 SKIP） | ⏭ | |
+| 8 | bootfs | 1 | fs | ✅ | 默认 | `[DKM:bootfs]` | Limine boot module FS | ⬜ | |
+| 9 | vfs | 2 | fs-core | ✅ | 默认 | `[DKM:vfs]` | 挂载 bootfs | ⬜ | |
+| 10 | fat32 | 2 | fs | ❌ | +SATA 测试盘 | `[DKM:fat32]` | BPB/FAT/目录项解析 | ⬜ | |
+| 11 | devfs | 2 | fs | ❌ | 默认 | `[DKM:devfs]` | /dev/version, /dev/fb0 等 | ⬜ | |
+| 12 | e1000 | 3 | net | ❌ | `-device e1000` | `tx=ready rx=ready` | DHCP + ping | ⬜ | |
+| 13 | virtio_net | 3 | net | ❌ | `-device virtio-net-pci` | `[DKM:virtio_net] 1af4:1001 found` | capability 枚举 | ⬜ | |
+| 14 | ath9k | 3 | net | ❌ | （QEMU 不支持 WiFi） | `no Atheros WiFi device found` | 跳过（QEMU 限制） | ⏭ | |
+| 15 | ps2kbd | 3 | input | ❌ | 默认 | scan code 读取 | 输入回显 | ⬜ | |
+
+## stage 加载顺序
+
+```
+stage 0 (platform): timer → apic → acpi → pci
+stage 1 (boot):     console_fb → ahci → nvme → bootfs
+stage 2 (fs):       vfs → fat32 → devfs
+stage 3 (optional): e1000 → virtio_net → ath9k → ps2kbd
+```
+
+## 测试设备 QEMU 参数
+
+### AHCI + FAT32 测试盘
+
+```
+-drive id=sata0,format=raw,file=.build_tmp/sata_fat32_dsk.img,if=none ^
+-device ide-hd,drive=sata0,bus=ide.0 ^
+```
+
+### NVMe
+
+```
+-device nvme,drive=nvme0,serial=UTSMTEST ^
+-drive id=nvme0,format=raw,file=.build_tmp/nvme_test.img,if=none ^
+```
+
+### e1000
+
+```
+-netdev user,id=net0 ^
+-device e1000,netdev=net0,mac=52:54:00:12:34:56 ^
+```
+
+### virtio-net
+
+```
+-netdev user,id=net0 ^
+-device virtio-net-pci,netdev=net0 ^
+```
+
+## 已知限制
+
+- NVMe BAR0 在 QEMU 中常位于 4G 以上，当前 HHDM 不能安全访问，需 Phase 0 高位 MMIO 映射解决
+- ath9k 在 QEMU 中无对应设备模拟，永远走 "not found" 路径
+- 多个 NIC 同时挂载会改变 PCI 拓扑，可能影响 e1000 探测位置
@@ -0,0 +1,77 @@
+# Linux 兼容层测试矩阵
+
+> 对应计划 Phase A：UTSM+Linux 双内核 park-and-resume 端到端验证
+> 前置条件：Linux 6.6 LTS bzImage 已构建（SYSTEM/boot/linux-bzImage + linux-initrd.img）
+
+## 状态: ⬜ PENDING
+
+## 测试环境
+
+- QEMU 加速: WHPX (`-accel whpx -cpu max`)，TCG 不支持 VMX
+- Linux 模块: limine.conf 中 bzImage/initrd 模块已启用
+- 串口: `-serial stdio`，过滤 `Linux version|utsm-linux|linux_compat|UTSM.*Linux|DSK|shell`
+
+## 测试矩阵
+
+| # | 测试项 | 串口/Shell 预期 | 状态 | 失败处理 | Bug# |
+|---|---|---|---|---|---|
+| A5.1 | UTSM VMM self-test 通过 | `[UTSM] VMM self-test PASS` | ⬜ | 检查 VMCS/EPT 初始化；BIOS 启用 VT-x | |
+| A5.2 | bzImage 加载与解析 | `[UTSM] Linux bzImage loaded` | ⬜ | 检查 linux_loader_init header magic 校验 | |
+| A5.3 | EPT 映射 + vmlaunch | `[UTSM] Linux guest launched` | ⬜ | 检查 EPT 表、VMCS guest 状态 | |
+| A5.4 | Linux 内核启动 | `Linux version 6.6.x` 串口日志 | ⬜ | 检查 cmdline、boot_params、E820 表 | |
+| A5.5 | init 脚本运行 | `[utsm-linux] init started` | ⬜ | 检查 initramfs 结构 | |
+| A5.6 | exec daemon 启动 + park | `[utsm-linux] starting utsm_exec_daemon...` → `linux_compat_init() ready` | ⬜ | 检查 daemon 编译、IPC 共享内存初始化 | |
+| A5.7 | DSK 正常接管 | `[DSK] boot` → `[DSK] SELFTEST PASS` | ⬜ | 验证 Linux park 不阻塞 DSK | |
+| A5.8 | shell `linux`（无参）状态查询 | `Linux 兼容层已就绪 (双内核 park-and-resume)` | ⬜ | 检查 reserved[5] 传递链 | |
+| A5.9 | shell `linux ls` | 输出 initramfs 根目录内容 | ⬜ | 检查 IPC exec 协议、vmresume 路径 | |
+| A5.10 | shell `linux uname -a` | 输出 `Linux ... 6.6.x ...` | ⬜ | 同上 | |
+| A5.11 | shell `linux cat /etc/hostname` | 输出 hostname | ⬜ | 同上 | |
+| A5.12 | 错误路径：`linux nosuchprog` | 输出 exec 失败，shell 不崩溃 | ⬜ | 检查 EXEC_EXIT 消息处理 | |
+
+## 关键约束验证
+
+| 约束 | 验证方法 | 状态 |
+|---|---|---|
+| Linux guest cmdline 含 `nohlt idle=poll` | 检查 [linux_loader.c](../../CODE/UTSM/vmm/linux_loader.c) cmdline 构造 | ⬜ |
+| IPC 共享内存 GPA=0x04000000, 1MB | e820 中标记 RESERVED，Linux 不分配 | ⬜ |
+| Linux guest RAM 起始 0x05000000 | 检查 EPT 映射范围 | ⬜ |
+| exec daemon 先发 EXEC_READY 再 HLT | daemon 源码 [utsm_exec_daemon.c](../../CODE/linux/initramfs/bin/utsm_exec_daemon.c) | ⬜ |
+| UTSM hypercall ABI: RAX=magic\|op | 检查 [hypercall.c](../../CODE/UTSM/vmm/hypercall.c) 处理 | ⬜ |
+
+## 已知限制
+
+- QEMU TCG 不支持 VMX，必须 WHPX 或真机
+- WHPX 可能不暴露 nested VMX 给 guest（需实测）
+- 若 CPU 不支持 VT-x，整个 Linux 兼容层降级为"不可用"，不影响其他系统功能
+
+## 手动测试命令
+
+进入 shell 后执行：
+
+```
+deshab:/ $ linux
+deshab:/ $ linux ls
+deshab:/ $ linux uname -a
+deshab:/ $ linux cat /etc/hostname
+deshab:/ $ linux nosuchprog
+```
+
+## 串口日志锚点
+
+启动后期望按顺序出现：
+
+```
+[UTSM] VMM self-test PASS
+[UTSM] Linux bzImage loaded
+[UTSM] Linux guest launched
+Linux version 6.6.x ...
+[utsm-linux] init started
+[utsm-linux] kernel: 6.6.x
+[utsm-linux] starting utsm_exec_daemon...
+[utsm-linux] daemon PID=...
+[utsm-linux] init: daemon running, entering idle hold
+[UTSM] linux_compat service ready
+[DSK] boot
+[DSK] SELFTEST PASS
+... (进入 shell 提示符)
+```
@@ -0,0 +1,62 @@
+# 网络端到端测试矩阵
+
+> 对应计划 Phase C4 网络部分：e1000 + net_stack + ping/curl/browser
+
+## 状态: ✅ 已验证（[deshab_system_roadmap_plan.md](../../.trae/documents/deshab_system_roadmap_plan.md) Phase 1）
+
+> 本矩阵用于回归验证，确保不退化
+
+## 测试环境
+
+- QEMU 网络: `-netdev user,id=net0 -device e1000,netdev=net0`
+- slirp 默认: guest 10.0.2.15, 网关 10.0.2.2, DNS 10.0.2.3
+- 主机 http 服务: `python -m http.server 8000`
+
+## 测试矩阵
+
+| # | 测试项 | 命令 | 预期 | 状态 | Bug# |
+|---|---|---|---|---|---|
+| N1 | e1000 驱动加载 | (自动) | `tx=ready rx=ready` | ✅ | |
+| N2 | netman 注册 | (自动) | netman 打印设备枚举 | ✅ | |
+| N3 | DHCP 获取 IP | (自动) | netman DHCP final rc=0 | ✅ | |
+| N4 | ARP 解析网关 | (自动) | netman ARP final rc=0 | ✅ | |
+| N5 | DNS 查询 | (自动) | netman DNS final rc=0 | ✅ | |
+| N6 | shell ping 网关 | `ping 10.0.2.2` | 4/4 reply, RTT<10ms | ✅ | |
+| N7 | shell ping 外网 | `ping 8.8.8.8` | (依赖主机联网) | 🔶 | |
+| N8 | shell curl 本地 | `curl http://10.0.2.2:8000/` | HTTP 200 + 目录 HTML | ✅ | |
+| N9 | shell curl 外网 | `curl http://example.com/` | HTTP 200 (依赖主机联网) | 🔶 | |
+| N10 | curl.elf 工具 | `run CURL.ELF` | 独立工具执行 curl | ✅ | |
+| N11 | ping.elf 工具 | `run PING.ELF` | 独立工具执行 ping | ✅ | |
+| N12 | browser.elf 工具 | `run BROWSER.ELF` | URL 输入 + HTTP GET | ✅ | |
+
+## 回归验证
+
+每次启动 dev_mode 时，run_dev_tests 应包含：
+
+```
+[shell] dev_tests:
+  ...
+  ping 10.0.2.2: OK (4/4 reply, RTT=Xms)
+  ...
+```
+
+若 ping 失败：
+
+1. 检查 e1000 是否加载（`-device e1000` 参数）
+2. 检查 netman 是否成功 DHCP
+3. 检查 ARP 是否解析网关
+4. 串口日志 grep `e1000|netman|DHCP|ARP|DNS|network`
+
+## 性能基线
+
+参见 [performance-baseline.md](performance-baseline.md)：
+
+- ping RTT < 10ms
+- curl 64KB 页面接收无明显停顿
+- DHCP 总耗时 < 5s
+
+## 已知限制
+
+- HTTPS/TLS 不支持（curl 仅 http）
+- TCP 仅最小 client 实现（无拥塞控制/乱序队列）
+- QEMU slirp 不支持真实 Wi-Fi 模式，ath9k 驱动在 QEMU 中无设备
@@ -0,0 +1,72 @@
+# PE/EXE 兼容层测试矩阵
+
+> 对应计划 Phase B：PE32+ (64位 native) 与 PE32 (32位 x86emu32) 兼容层验证
+> 入口：cmd.elf 通过 `ctx->reserved[4]` 取 pe_service
+
+## 状态: ⬜ PENDING
+
+## 测试程序
+
+| 文件 | 类型 | 来源 | FAT32 8.3 名 | 路径 |
+|---|---|---|---|---|
+| hello64.exe | PE32+ (64位) | MinGW/MSVC 编译或 Python 生成 | `HELLO64 EXE` | SYSTEM/system/deshab64/tools/ |
+| hello32.exe | PE32 (32位) | MinGW 交叉编译或 Python 生成 | `HELLO32 EXE` | SYSTEM/system/deshab64/tools/ |
+
+## 测试矩阵
+
+| # | 测试项 | 命令 | 预期输出 | 状态 | Bug# |
+|---|---|---|---|---|---|
+| B2.1 | PE32+ 加载执行 | `pe HELLO64.EXE` | `Hello from PE32+!` | ⬜ | |
+| B2.2 | PE32 加载执行（解释器） | `pe HELLO32.EXE` | `Hello from PE32!` | ⬜ | |
+| B2.3 | PE 头解析 | `peinfo HELLO64.EXE` | `machine=0x8664 entry=0x... image_base=0x...` | ⬜ | |
+| B2.4 | 文件不存在错误路径 | `pe NONEXIST.EXE` | `Error: file not found` | ⬜ | |
+| B2.5 | 无参用法提示 | `pe` | 显示用法 | ⬜ | |
+| B2.6 | ExitProcess 返回 | (执行后) | cmd 接管，longjmp 跳回 pe_service_run | ⬜ | |
+| B2.7 | PE32 头解析 | `peinfo HELLO32.EXE` | `machine=0x14c entry=0x... image_base=0x00400000` | ⬜ | |
+
+## 关键 ABI 验证
+
+| ABI | 验证方法 | 状态 |
+|---|---|---|
+| `ctx->reserved[4]` 持 pe_service* | [cmd/main.c:825](../../CODE/cmd/main.c#L825) | ⬜ |
+| `PE_SERVICE_MAGIC` 校验 | [cmd/main.c:830](../../CODE/cmd/main.c#L830) | ⬜ |
+| `g_pe_svc` 缓存 | [cmd/main.c:108](../../CODE/cmd/main.c#L108) | ⬜ |
+| PE32+ IAT 填 ms_abi shim | [pe_loader.c](../../CODE/UTSM/pe/pe_loader.c) | ⬜ |
+| PE32 IAT 填合成地址 0x00010000\|idx | [pe_loader.c](../../CODE/UTSM/pe/pe_loader.c) | ⬜ |
+| x86emu32 拦截 CALL 合成地址 | [x86emu32.c](../../CODE/UTSM/pe/x86emu32.c) | ⬜ |
+
+## 测试程序源码
+
+### hello64.c (PE32+)
+
+```c
+#include <windows.h>
+int main(void) {
+    WriteFile(GetStdHandle(STD_OUTPUT_HANDLE), "Hello from PE32+!\r\n", 19, NULL, NULL);
+    return 0;
+}
+```
+
+编译：`x86_64-w64-mingw32-gcc -o hello64.exe hello64.c` 或 `cl /Fe:hello64.exe hello64.c`
+
+### hello32.c (PE32)
+
+```c
+#include <windows.h>
+int main(void) {
+    WriteFile(GetStdHandle(STD_OUTPUT_HANDLE), "Hello from PE32!\r\n", 18, NULL, NULL);
+    return 0;
+}
+```
+
+编译：`i686-w64-mingw32-gcc -o hello32.exe hello32.c -Wl,--image-base=0x00400000`
+
+### Fallback: Python 生成器
+
+若无 MinGW/MSVC，使用 [CODE/tools/pe-samples/gen_pe.py](../../CODE/tools/pe-samples/gen_pe.py) 生成最小 PE 程序。
+
+## 已知限制
+
+- pe_shim 实现的 Win32 API 子集有限，测试程序仅使用 WriteFile + ExitProcess
+- x86emu32 指令覆盖率参见 [x86emu32-coverage.md](x86emu32-coverage.md)
+- TLS / IFUNC / lazy binding 不支持（DKM ABI 约束）
@@ -0,0 +1,88 @@
+# 性能基线测量
+
+> 对应计划 Phase C5：基于 TSC 的关键性能指标测量
+
+## 状态: ⬜ PENDING
+
+## 测量方法
+
+所有指标基于 TSC（Time Stamp Counter）：
+
+```c
+static inline u64 rdtsc(void) {
+    u32 lo, hi;
+    __asm__ volatile("rdtsc" : "=a"(lo), "=d"(hi));
+    return ((u64)hi << 32) | lo;
+}
+```
+
+TSC 频率需先校准（PIT 100ms busy-wait 测量）：
+
+```c
+u64 tsc_freq;  // Hz
+u64 calibrate_tsc(void) {
+    u64 start = rdtsc();
+    pit_busy_wait(100);  // 100ms
+    u64 end = rdtsc();
+    return (end - start) * 10;  // ×10 得到 Hz
+}
+```
+
+时间换算：`ms = (tsc_diff * 1000) / tsc_freq`
+
+## 基线指标
+
+| # | 指标 | 测量位置 | 基线目标 | 实测 | 状态 |
+|---|---|---|---|---|---|
+| P1 | UTSM 启动到 DSK SELFTEST | UTSM entry → DSK selftest pass | < 500ms (QEMU) | | ⬜ |
+| P2 | DSK 加载 shell.elf 时间 | FAT32 read + PIE load 包围 | < 200ms | | ⬜ |
+| P3 | DSK 加载 desktop.elf 时间 | 同上 | < 200ms | | ⬜ |
+| P4 | shell `ping 10.0.2.2` RTT | echo request → reply | < 10ms (user-net) | | ⬜ |
+| P5 | shell `linux ls` 完整 RTT | IPC exec round-trip | < 100ms (park-and-resume) | | ⬜ |
+| P6 | shell `run PING.ELF` 加载时间 | FAT32 read + PIE load | < 150ms | | ⬜ |
+| P7 | desktop 窗口拖动帧率 | 帧计数/TSC | 30+ FPS | | ⬜ |
+| P8 | `pe HELLO64.EXE` 加载+执行 | pe_service_run 包围 | < 50ms | | ⬜ |
+| P9 | `pe HELLO32.EXE` 加载+执行 | x86emu32 解释 | < 200ms | | ⬜ |
+| P10 | UTSM VMM self-test | vmm_init → vmm_self_test | < 50ms | | ⬜ |
+| P11 | Linux guest 启动到 park | vmlaunch → daemon HLT | < 3s (QEMU WHPX) | | ⬜ |
+| P12 | e1000 DHCP 完整耗时 | netman DHCP start → final rc | < 5s | | ⬜ |
+
+## 自动化测量
+
+在 dev_mode run_dev_tests 中追加性能测量代码：
+
+```c
+/* 在 run_dev_tests 开头校准 TSC */
+u64 tsc_freq = calibrate_tsc();
+logl("[shell] TSC freq: <Hz>");
+
+/* 各项测试包围 TSC */
+u64 t0 = rdtsc();
+/* ... 操作 ... */
+u64 t1 = rdtsc();
+u64 ms = (t1 - t0) * 1000 / tsc_freq;
+logl("[shell] perf: <name> = <ms>ms");
+```
+
+输出到串口日志，由 [ISO/run_tests.bat](../../ISO/run_tests.bat) 收集汇总。
+
+## 性能回归检测
+
+```powershell
+# 比较两次测试结果
+$prev = Get-Content ISO/logs/perf-baseline-prev.json | ConvertFrom-Json
+$curr = Get-Content ISO/logs/perf-baseline-curr.json | ConvertFrom-Json
+
+foreach ($m in $curr.metrics) {
+    $p = $prev.metrics | Where-Object name -eq $m.name
+    if ($p -and $m.ms -gt $p.ms * 1.5) {
+        Write-Host "[REGRESSION] $($m.name): $($p.ms)ms -> $($m.ms)ms (>50%)"
+    }
+}
+```
+
+## 已知限制
+
+- QEMU 性能数据不等于真机，仅作回归参考
+- WHPX vs TCG 性能差异巨大，必须固定加速方案
+- 多次测量取中位数，避免单次抖动
@@ -0,0 +1,76 @@
+# 用户态程序功能矩阵
+
+> 对应计划 Phase C4：FirstInit/login/desktop/shell/cmd + 5 个工具应用
+
+## 状态: ⬜ PENDING
+
+## 程序矩阵
+
+| # | 程序 | ELF 路径 | 入口 | 关键命令/功能 | 验证点 | 状态 | Bug# |
+|---|---|---|---|---|---|---|---|
+| 1 | FirstInit | `system/user/use/FirstInit.elf` | 首启触发 | 计算机名/用户名/密码输入、空字段红字、网络配置 | SHA256 密码、user.conf 写入缓冲 | ⬜ | |
+| 2 | login | `system/user/use/login.elf` | 次启触发 | 用户选择、密码输入、错误重试 | USER.CONF 解密、密码匹配 | ⬜ | |
+| 3 | desktop | `system/deshab64/desktop.elf` | login 后 | 双击图标、窗口拖动、任务栏、内建 bash | 6 个工具启动、鼠标光标 | ⬜ | |
+| 4 | shell | `system/deshab64/shell.elf` | desktop Terminal | ls/cat/cp/mv/rm/echo>/ping/curl/run/linux | dev_mode 自动测试全绿 | ⬜ | |
+| 5 | cmd | `system/deshab64/cmd.elf` | desktop CMD | dir/type/copy/del + `pe <NAME.EXE>` | PE 兼容层调用 | ⬜ | |
+| 6 | netman | `system/deshab64/network/netman.elf` | DSK 调度 | 读 conf.conf、应用网络配置 | DHCP/静态 IP | ⬜ | |
+| 7 | mouseInit | `system/deshab64/mouse/mouseInit.elf` | DSK 调度 | 安全 stub | 不阻塞启动 | ⬜ | |
+| 8 | editor | `system/deshab64/tools/editor.elf` | desktop 双击 | 文件打开/编辑/保存 | FAT32 写盘 | ⬜ | |
+| 9 | fileman | `system/deshab64/tools/fileman.elf` | desktop 双击 | 浏览/打开/复制 | 目录遍历 | ⬜ | |
+| 10 | browser | `system/deshab64/tools/browser.elf` | desktop 双击 | URL 输入/HTTP GET | net_stack 协议栈 | ⬜ | |
+| 11 | curl | `system/deshab64/tools/curl.elf` | desktop 双击 | `curl http://...` | HTTP GET | ⬜ | |
+| 12 | ping | `system/deshab64/tools/ping.elf` | desktop 双击 | `ping <ip>` | ICMP echo | ⬜ | |
+
+## 启动链路
+
+```
+首启: utsm → DSK → mouseInit → netman → FirstInit → desktop
+次启: utsm → DSK → login → desktop
+dev_mode: utsm → DSK → shell(dev_tests) → Esc → login → desktop
+desktop → 双击 Terminal → shell.elf
+desktop → 双击 CMD → cmd.elf
+shell → run FILEMAN.ELF → fileman.elf → Esc 返回 shell
+shell → run BROWSER.ELF → browser.elf
+shell → run EDITOR.ELF → editor.elf
+shell → run PING.ELF → ping.elf
+shell → run CURL.ELF → curl.elf
+```
+
+## 详细测试用例
+
+### shell 命令测试
+
+| 命令 | 参数 | 预期 | 状态 |
+|---|---|---|---|
+| `ls` | (无) | 列出根目录文件（DESHAB.ELF, SHELL.ELF 等） | ⬜ |
+| `pwd` | (无) | `/` | ⬜ |
+| `cat` | `README.TXT` | 显示文件内容 | ⬜ |
+| `cp` | `a b` | 复制成功 | ⬜ |
+| `mv` | `a b` | 移动成功 | ⬜ |
+| `rm` | `a` | 删除成功 | ⬜ |
+| `echo>` | `text > file` | 写入文件 | ⬜ |
+| `ping` | `10.0.2.2` | 4/4 reply | ⬜ |
+| `curl` | `http://10.0.2.2:8000/` | HTTP 200 + body | ⬜ |
+| `run` | `PING.ELF` | 加载并执行 ping | ⬜ |
+| `linux` | (无) | 显示兼容层状态 | ⬜ |
+| `linux` | `ls` | 输出 initramfs 内容 | ⬜ |
+| `help` | (无) | 显示命令列表 | ⬜ |
+| `ver`/`version` | (无) | 显示版本 | ⬜ |
+
+### desktop UI 测试
+
+| 操作 | 预期 | 状态 |
+|---|---|---|
+| 双击 Terminal 图标 | 打开 shell 窗口 | ⬜ |
+| 双击 CMD 图标 | 打开 cmd 窗口 | ⬜ |
+| 双击 Editor 图标 | 打开 editor | ⬜ |
+| 双击 File Manager 图标 | 打开 fileman | ⬜ |
+| 双击 Browser 图标 | 打开 browser | ⬜ |
+| 鼠标移动 | 光标跟随，无闪烁 | ⬜ |
+| 窗口拖动 | 流畅，无撕裂 | ⬜ |
+| 任务栏点击 | 窗口切换 | ⬜ |
+
+## 已知问题
+
+- fileman.elf 之前触发过 QEMU 退出（访问未支持 boot context 字段），需观察是否复现
+- 真实 TTF 字体未运行时光栅化，使用预渲染位图（已知设计选择，非 bug）
@@ -0,0 +1,86 @@
+# x86emu32 指令覆盖率测试
+
+> 对应计划 Phase B3：枚举 x86emu32.c 已实现指令，验证覆盖率
+
+## 状态: ⬜ PENDING
+
+## 已实现指令清单
+
+> 待根据 [x86emu32.c](../../CODE/UTSM/pe/x86emu32.c) 实际代码枚举填充
+
+### 数据传送
+
+| 指令 | 操作码 | 测试程序 | 预期 | 状态 |
+|---|---|---|---|---|
+| MOV r32, imm32 | B8+rd | `mov eax, 0x12345678` | eax=0x12345678 | ⬜ |
+| MOV r32, r/m32 | 8B /r | `mov eax, ebx` | eax=ebx | ⬜ |
+| MOV r/m32, r32 | 89 /r | `mov [esi], eax` | [esi]=eax | ⬜ |
+| PUSH r32 | 50+rd | `push eax` | [esp]=eax, esp-=4 | ⬜ |
+| POP r32 | 58+rd | `pop eax` | eax=[esp], esp+=4 | ⬜ |
+
+### 算术运算
+
+| 指令 | 操作码 | 测试程序 | 预期 | 状态 |
+|---|---|---|---|---|
+| ADD r32, r/m32 | 03 /r | `add eax, ebx` | eax=eax+ebx | ⬜ |
+| SUB r32, r/m32 | 2B /r | `sub eax, ebx` | eax=eax-ebx | ⬜ |
+| INC r32 | FF /0 | `inc eax` | eax=eax+1 | ⬜ |
+| DEC r32 | FF /1 | `dec eax` | eax=eax-1 | ⬜ |
+| MUL r/m32 | F7 /4 | `mul ebx` | edx:eax=eax*ebx | ⬜ |
+| DIV r/m32 | F7 /6 | `div ebx` | eax=edx:eax/ebx | ⬜ |
+
+### 逻辑运算
+
+| 指令 | 操作码 | 测试程序 | 预期 | 状态 |
+|---|---|---|---|---|
+| AND r32, r/m32 | 23 /r | `and eax, ebx` | eax=eax&ebx | ⬜ |
+| OR r32, r/m32 | 0B /r | `or eax, ebx` | eax=eax\|ebx | ⬜ |
+| XOR r32, r/m32 | 33 /r | `xor eax, ebx` | eax=eax^ebx | ⬜ |
+| NOT r/m32 | F7 /2 | `not eax` | eax=~eax | ⬜ |
+
+### 控制流
+
+| 指令 | 操作码 | 测试程序 | 预期 | 状态 |
+|---|---|---|---|---|
+| JMP rel32 | E9 cw/cd | `jmp label` | rip=label | ⬜ |
+| JMP r/m32 | FF /4 | `jmp eax` | rip=eax | ⬜ |
+| CALL rel32 | E8 cd | `call func` | push rip, rip=func | ⬜ |
+| RET | C3 | `ret` | pop rip | ⬜ |
+| Jcc rel32 | 0F 8x cd | `jz label` | 条件跳转 | ⬜ |
+
+### 字符串操作
+
+| 指令 | 操作码 | 测试程序 | 预期 | 状态 |
+|---|---|---|---|---|
+| MOVSB | A4 | `movsb` | [edi]=[esi], inc/dec | ⬜ |
+| STOSB | AA | `stosb` | [edi]=al, inc/dec | ⬜ |
+| REP MOVSB | F3 A4 | `rep movsb` | 重复 ecx 次 | ⬜ |
+| REP STOSB | F3 AA | `rep stosb` | 重复 ecx 次 | ⬜ |
+
+### 堆栈与控制
+
+| 指令 | 操作码 | 测试程序 | 预期 | 状态 |
+|---|---|---|---|---|
+| ENTER imm16, imm8 | C8 iw ib | `enter 8, 0` | 建立栈帧 | ⬜ |
+| LEAVE | C9 | `leave` | 释放栈帧 | ⬜ |
+| NOP | 90 | `nop` | 无操作 | ⬜ |
+| INT3 | CC | `int3` | 触发断点 | ⬜ |
+
+## 测试 PE 程序
+
+每个指令类别构造一个最小 PE32 测试程序，在 [CODE/tools/pe-samples/](../../CODE/tools/pe-samples/) 下：
+
+- `test_arith.exe`：算术运算
+- `test_logic.exe`：逻辑运算
+- `test_control.exe`：控制流
+- `test_string.exe`：字符串操作
+
+每个测试程序通过 WriteFile 输出结果到 cmd.elf，与预期对比。
+
+## 覆盖率统计
+
+```
+已测试指令数 / 已实现指令数 = 覆盖率
+```
+
+目标：核心指令（MOV/ADD/SUB/CMP/JMP/CALL/RET/PUSH/POP）覆盖率 100%。