Deshab-OS/CLAUDE.md

Deshab 项目上下文

项目概览

Deshab 当前包含一个内核/系统实验方向，其中启动内核与主内核目标为：

CODE/UTSM -> SYSTEM/boot/utsm.elf
CODE/dsk  -> SYSTEM/system/deshab64/deshab.elf

utsm.elf 是当前由 bootloader 直接加载的首阶段内核，负责 UTSM、DKM 驱动加载、平台发现和早期系统服务。当前已实现两阶段 DSK 加载：优先通过 kernel_api.block + 内嵌 FAT32 解析从真实块设备读取 /system/deshab64/deshab.elf（在 SATA FAT32 盘场景已验证）；无块设备时自动回退 Limine boot module 预加载。

DSK 主内核（deshab.elf）当前已实现：

• 内嵌 FAT32 只读解析器（256 扇区批量读取 + 内存内文件查找）
• PIE ELF loader（PT_LOAD + PT_DYNAMIC + R_X86_64_RELATIVE 重定位）
• 静态启动 Logo（嵌入 Logo.png RGBA 数据，居中 alpha 混合绘制于渐变背景上，取代原旋转加载动画）
• 首次启动检测：读取 firstInit.txt，值为 0 则触发首次启动流程
• 系统初始化调度：DSK 直接加载并调用 mouseInit.elf（PS/2 鼠标安全初始化）
• 用户设置向导：DSK 加载并跳转 FirstInit.elf（圆角卡片 UI、键盘输入、SHA256 密码、加密配置缓冲）

FirstInit（CODE/firstInit）只负责用户级设置向导：

• 淡蓝背景 → "欢迎使用 Deshab"（中英双语，英文小字副标题）→ 设置提示 → 账户设置卡片
• PS/2 键盘轮询输入：计算机名、用户名、密码
• SHA256 密码摘要 + XOR 加密配置缓冲（user.conf 格式已定义，写盘待 FAT32 write API）
• 18px 黑体中文位图（预渲染嵌入 ELF）

mouseInit（CODE/mouse）是 DSK 直接调度的系统输入初始化器：

• 当前为安全 stub（只读 PS/2 状态，不写控制器），避免阻塞首次启动
• 后续将实现完整 IRQ12 + 鼠标包解码

当前核心架构

SAS-R0-PCQ
    单地址空间 Ring0 任务模型
    Per-CPU O(1) 位图调度器

DRR
    Dedicated Recovery Root
    看门狗 / checkpoint / recovery log / A-B 回滚

UTSM
    UUID-Tuned Sealed Memory
    UUID 调谐封缄内存

UTRW
    UTSM Tagged Reader/Writer
    UTSM 带标记读写器

DMP
    Descriptor Meta Page
    段描述符元页

PCKC
    Per-CPU Key Cache
    每 CPU 密钥缓存

FUCK
    内核启动配置文件
    INI 分区格式，控制启动行为/驱动开关/算法参数/桌面行为

关键设计约束

1. 优先考虑极高权限和极高效率。
2. 主系统采用单地址空间 Ring0 模型。
3. 不追求传统多用户强安全隔离。
4. DRR 作为恢复根，应尽量独立于普通调度器。
5. UTSM 数据区连续存密文，UUID 不嵌入数据区。
6. 调度器热路径必须保持 O(1)。
7. checkpoint 只处理 dirty shard / dirty page，不扫描全内存。
8. DRR 必须拥有独立 Emergency Pool，普通 OOM 不应阻断 recovery。
9. checkpoint metadata 使用 A/B 双槽、CRC 校验和原子 active slot 切换。
10. 驱动模块采用 DKM ELF64 .drv ABI，通过 driver_desc / driver_init / driver_exit 暴露入口。
11. 驱动默认通过 dkm_kernel_api 调用内核服务，不直接依赖任意内核符号。
12. stage0/stage1 驱动必须支持 bootloader 预加载 boot module 方案。

重要文件

SYSTEM/
    打包为 IMG 后的系统根目录。

SYSTEM/driver/manifest.json
    内核启动驱动模块清单，控制 ELF .drv 驱动的分阶段加载。

SYSTEM/system/deshab64/FUCK
    内核启动配置文件（INI 分区格式），控制启动行为开关、驱动加载开关、UTSM 算法参数、DSK 桌面行为。
    UTSM 通过 Limine boot module 预加载读取（cmdline="fuck:config")。
    DSK 通过 FAT32 子目录遍历读取（路径 "SYSTEM  /DESHAB64 /FUCK    ")。
    缺失或为空时使用硬编码默认值，行为与无配置文件时一致。

CODE/UTSM/kernel/ini_parser.h / ini_parser.c
    UTSM INI 配置解析器，支持分区格式解析、key/value 查询、整型和布尔值便捷获取。

CODE/DKM/README.md
    DKM 驱动模块系统说明，记录驱动加载目标、ABI、loader、状态机和实现清单。

CODE/UTSM/README.md
    UTSM 模块设计说明。

RE/UTSM_算法记录.md
    UTSM 核心算法记录。

RE/UTSM_设计架构.md
    UTSM 架构记录。

RE/驱动模块ABI设计.md
    DKM 驱动模块 ABI、kernel_api、ELF relocation、manifest、状态机和 boot module 方案。

ISO/deshab.img
    build.ps1 将 SYSTEM 打包生成的 GPT 磁盘镜像，包含一个 FAT32 EFI System Partition。

ISO/run_qemu.bat
    使用 QEMU 启动 ISO/deshab.img 的脚本。

构建相关

已知说明：

SYSTEM/ 是唯一打包输入：build.ps1 只扫描 SYSTEM/，不从 /home 或其它路径取发行物。
所有要进镜像的软件（utsm.elf、deshab.elf、.drv、bzImage/initrd、
linux-rootfs.img、linux-extra-rootfs.img、Python/KDE 内容）必须先落到 SYSTEM/。
打包成 GPT 双分区：p1 FAT32 ESP（SYSTEM/EFI + SYSTEM/limine + SYSTEM/boot
+ SYSTEM/driver + SYSTEM/system — Limine 10 不能读 ext4，boot(): 模块必须在 ESP），
p2 ext4（其余 SYSTEM/，并保留 driver/system 副本）。由 WSL
CODE/linux/pack_system_image.sh 执行 mkfs.vfat + mkfs.ext4。
ext4 UUID 固定为 64657368-6162-4000-8000-000000000002。
内核/驱动/DSK 一律走 boot(): （FAT32 ESP）。
FAT32 单文件上限 4GiB-1 仍适用于 ESP 上的 /boot 文件，linux-extra-rootfs.img 必须小于 4GiB。
SYSTEM/boot/ 存放启动模块，例如 utsm.elf。
SYSTEM/driver/ 存放 ELF .drv 驱动模块和 manifest.json。
CODE/UTSM/README.md: 编译到 SYSTEM/boot/utsm.elf
build.bat: 调用 build.ps1，透传参数（如 -Variant dev）。
build.ps1: 编译 UTSM/DSK/工具/驱动，把整个 SYSTEM/ 打成 GPT(FAT32 ESP + ext4) 镜像：
  - ISO/deshab-dev.img     开发者模式（dev_mode=1，自动跑 shell.elf 测试，调试全开，QEMU 验证选项）
  - ISO/deshab-release.img 发布版（dev_mode=0，进桌面+登录，调试零开销，真机安全选项）
  参数 -Variant dev|release|both（默认 both）。both 模式构建后恢复 SYSTEM 为 dev 配置。
  配置模板在 build/configs/{dev,release}/（FUCK + firstInit.txt），打包前注入到 SYSTEM。
ISO/run_qemu.bat: 用 QEMU + UEFI 固件启动 ISO/deshab-dev.img，串口输出到 stdio。
ISO/run_qemu_kvm.sh: 默认 12G 内存（Limine 会把 SYSTEM/boot 里的 rootfs 模块装进内存）。
build.ps1 自动把 Git usr/bin 加入 PATH（sh.exe + mkdir），解决 make `mkdir -p` 在 cmd.exe 下失败的问题。

当前 UTSM 已有首阶段内核代码骨架和构建脚本，可生成 utsm.elf 与 GPT（FAT32 引导分区 + ext4 数据分区）镜像。早期启动要求：进入 C 前 cli/cld，early serial 不允许无限等待硬件 ready 位，未启用 FPU/SSE 前编译必须使用 -mno-sse -mno-sse2 -mno-mmx -msoft-float。DATA/BSS 段使用 PF_R|PF_W|PF_X（SAS-R0 下驱动模块内存需可执行）。

DKM/DSM 驱动加载系统已完工：内置 console_early + manifest.json 解析 + Limine boot module 预加载 + 4 stage 分阶段加载 + 全部 14 个外部 .drv ET_REL 装载（ELF64/SHT_NOBITS/R_X86_64_64/32/32S/PC32 relocation + driver_desc 校验 + driver_init 调用）。当前镜像额外预加载 driver/test.fat32 作为 FAT32 驱动测试镜像。

当前已实现 14 个真实 DKM 驱动：

• timer (stage0): PIT 校准, 100ms busy-wait demo
• apic (stage0): CPUID Local APIC 探测, IA32_APIC_BASE MSR, ACPI MADT 枚举, LAPIC enable + IOAPIC 重定向表编程（ISO 表感知）; B7: FUCK apic_route=1 时 IOAPIC→LAPIC 接管（注册 UTSM LAPIC EOI 钩子 + PIC 全屏蔽 + TPR=0 + tick vec 0x20 链路自验，失败自动完整降级回 PIC）; apic_route_legacy=1 额外放开 IRQ1/12/11 持续投递（e1000 强制 level/active-low）; apic_diag=1 HPET 绝对时基对拍 + 键鼠流观察窗
• acpi (stage0): Limine RSDP → XSDT, ACPI 表枚举
• pci (stage0): PCI config space 扫描, 设备枚举
• console_fb (stage1): Limine framebuffer, 淡蓝色背景清屏（原四色圆弧加载环已移除，启动画面改由 DSK 静态 Logo 接管）
• ahci (stage1): PCI AHCI 8086:2922 探测, BAR5/ABAR HHDM MMIO 映射, HBA CAP/GHC/PI/VS 与 port 枚举；已接入 kernel_api.dma，支持 SATA disk IDENTIFY 与 LBA0 READ 最小 DMA 路径；可向 kernel_api.block 注册 ahci0 block provider；默认无 SATA 盘/ATAPI 场景会跳过命令
• nvme (stage1): PCI NVMe 1b36:0010 探测, BAR0/BAR1 解析, IRQ line 读取；当前 QEMU BAR0 位于 4G 以上，MMIO register 读取等待高位 PCI MMIO 映射能力
• bootfs (stage1): Limine boot module 内存文件系统
• vfs (stage2): 挂载 bootfs, 文件查找/读取
• devfs (stage2): 暴露 /dev/version, /dev/platform, /dev/fb0, /dev/modules, /dev/boot/
• fat32 (stage2): 只读 FAT32 BPB/FAT/目录项解析, 通过 driver/test.fat32 验证读取 README.TXT
• ps2kbd (stage3): PS/2 IRQ1 注册, 端口 0x60 扫描码读取, scan code set 1 → ASCII demo
• e1000 (stage3): PCI 8086:10d3 探测, BAR0 HHDM MMIO 映射, MAC 读取, IRQ 注册, 基础 link setup
• virtio_net (stage3): PCI virtio-net 1af4:1001 探测, BAR 枚举, modern virtio PCI capability 枚举；暂不进行 feature negotiation / virtqueue / 收发包

当前内核平台能力：IDT 0–255 stub 全覆盖、异常处理、PIC remap 到 0x20–0x2f、IRQ handler 注册与 EOI、UTSM 侧 LAPIC EOI 钩子（idt_register_apic_eoi，IRQ 分发末尾调用，spurious 0xFF 特判跳过）、IOAPIC→LAPIC 路由接管（B7，legacy IRQ1/12/11 可持续投递）、Limine RSDP/framebuffer/module/HHDM request。

kernel_api 已暴露能力：log, rsdp_address, fb_address/width/height/pitch/bpp, boot_modules_response, irq_register, hhdm_offset, dma.alloc_pages, block provider registry, mmio/mm_map_mmio/mm_unmap_mmio, register_apic_eoi（尾部追加，ABI 兼容）。

当前 manifest 中 14 个外部 .drv 均已替换为真实 DKM 驱动并可加载执行。

下一阶段优先路线（活跃路线 = docs/ROADMAP_INSANE.md 五期填补计划，任务编号 F/U/D/R/E；状态唯一来源 = docs/STATUS.md）：

1. 一期 F 系列剩余: F2 统一帧缓冲控制台抽象、F3 跨平台构建（Make/CMake）。（F1 莲花 panic / F4 boot 分级自检 / F5 skip_firstinit 已完成）
2. 二期 U 系列: UTRW Slow Path 真分支（slow_path.c 当前为 stub）、@sealed 段标记、密文页 dump、selftest 修 chacha20 KAT 间歇 FAIL。
3. 三期 D 系列: DKM 热卸载（引用计数）、裸机器码加载器、按名 API 导出表、彩色日志。
4. 四期 R 系列收尾: drr_emergency_pool_kb/drr_recovery_log_size 接线、segment/system 级回滚验证、PCQ per-cpu 多核。
5. 五期 E 系列: 启动莲花动画、假想时光键彩蛋、提交信息规范、风味 ISO。
6. 工程债（Phase 存档遗留）: vector allocator/MSI-X、NVMe 高位 BAR、virtio-net virtqueue、DKM 零 warning。

M1 里程碑完成状态（2026-07-29）

任务 A: B6 FirstInit 按键崩溃修复

状态: [RESOLVED-NOT-REPRODUCIBLE]

验证结果:

• QEMU 复现测试完成，系统完整运行 FirstInit 流程无崩溃
• 按键扫描码处理正常，字段输入正确（测试序列: a, b, Enter, shift+comma, Enter, 1, 2, Enter）
• user.conf 成功写入磁盘，firstInit.txt 成功更新为 "1"
• 系统继续加载 desktop

证据: .build_tmp/qemu_serial_b6.log 串口日志，调试记录 debug-firstinit-key-crash.md

结论: B6 崩溃在当前构建中未复现，可能已在之前的修改中修复，或崩溃条件较特殊未触发。

任务 B: PS/2 鼠标完整实现

状态: [COMPLETED]

实现内容:

1. 完整初始化序列 (CODE/mouse/main.c):

   • ps2_drain() 冲刷控制器残留数据
   • 读配置字节 → 启用 AUX 时钟/IRQ/翻译 → 写回
   • 启用 AUX 端口
   • 复位鼠标 → 验证 ACK/自检/设备 ID
   • Set Defaults → 采样率 100 → 分辨率 2 → 启用数据报告
   • 全程超时保护（100000 次），单步失败只记日志继续

2. IRQ12 中断处理:

   • 经 kernel_api.irq_register 注册 IRQ12 handler
   • 读数据前检查 AUX 位（键盘数据留给键盘路径）
   • 3 字节包解码：同步位验证、溢出检测、9 位有符号位移合成
   • 坐标累计并钳位到 framebuffer 边界
   • 安全不变式：注册但不解屏蔽 PIC，DSK 阶段 IF=0

3. 共享状态接口:

   • mouse_state_t 结构体（magic/version/x/y/buttons/计数器/边界）
   • g_mouse_state 导出全局符号
   • mouse_poll_state() 只读快照查询接口

验证结果:

• mouseInit 初始化成功：cfg byte=0x47, data reporting enabled, IRQ12 handler registered
• FirstInit 中鼠标轮询正常：AUX 端口启用、复位、自检、流模式启用成功
• 鼠标数据包正确接收和解码（串口日志显示 "[mouse] pkt"）

证据: .build_tmp/qemu_serial_mouse.log 串口日志

技术要点:

• 严格遵守"任何单步失败只记日志继续执行，绝不阻塞或崩溃首次启动"准则
• handler 存活性结论：镜像会被后续模块覆盖，IRQ12 保持屏蔽避免野指针执行
• 后续集成路径：DKM 输入驱动 或 DSK 加载器增加"常驻"标志

M4 里程碑完成状态（2026-09-15）：SAS-R0-PCQ 调度器 + DRR 恢复根

任务 A: SAS-R0-PCQ 调度器（ROADMAP Phase 7）

状态: [COMPLETED]

实现内容:

1. O(1) 位图调度器 (CODE/UTSM/sched/sched.c):
   • 64 槽 TCB 表 + 8 CPU runqueue（当前 BSP-only），ready_bitmap ctz 选最高优先级（0 最高）
   • 侵入式 O(1) FIFO runqueue（slot 索引非指针），冻结 ABI 9 API 真实现
   • 任务栈从 arena 分配，entry/arg/stack_base 存 task_aux
2. xv6 式栈驱动切换 (CODE/UTSM/sched/switch.S):
   • 抢占 = IRQ 帧落在被抢占任务自己的栈上，切换只换 rsp
   • trampoline 跳 entry；schedule/yield/sleep/exit 全路径
   • 切换路径只触碰 crypto_context 指针（禁止扫描 capability/MAC/checkpoint）
3. LAPIC timer tick (CODE/UTSM/arch/x86_64/lapic_timer.c):
   • MMIO 映射 + TSC 延时校准（10ms 逆计数法）+ 周期模式
   • tick_hz/timeslice_ms 由 FUCK [sched] 配置（默认 100Hz/10ms）
   • demo 窗口含 tick 失速兜底：心跳无进展自动中止窗口，不卡死 bootstrap
4. FUCK 配置: [sched] enable/tick_hz/timeslice_ms/demo_ms/demo_fault

验证结果:

• selftest: runqueue O(1) PASS、block/wake PASS
• demo 窗口: 3 任务（prio 1/20/40）按优先级交错运行并正常退出
• 窗口结束 quiesce → timer stopped → 正常交接 DSK

任务 B: DRR 恢复根（ROADMAP Phase 8）

状态: [COMPLETED-MAC占位]

实现内容 (CODE/UTSM/drr/drr_stub.c):

1. 快照区: 静态区域（128 页容量，编译期），页条目含 seg_slot/page_index/crc
2. snapshot_dirty: 遍历 ACTIVE 段 dirty_shard 位图收集脏页 → 拷贝+CRC64 → 清位图
3. A/B 双槽 checkpoint: ckpt_a/ckpt_b + CRC + active slot 切换
4. rollback: 页级回滚 + CRC verify；segment/system 级接口就位
5. 看门狗: register/kick/timeout 检测，任务退出自动注销；异常钩子接入 fault 路径
6. FUCK 配置: [drr] watchdog_enabled；[utsm] drr_emergency_pool_kb/drr_recovery_log_size

验证结果（含负向测试 demo_fault=1）:

• ckpt snapshot ok（1 page）→ rollback done → rollback verify ok
• 看门狗负向测试: fault 任务（slot 3）死循环 → watchdog timeout task_slot=0x3 检出 → 回滚执行 → demo 窗口正常结束
• 证据: .build_tmp/qemu_serial_sched_m4.log

遗留:

• MAC 为 CRC64 占位（Phase 9 换真实加密）
• task_kill crypto erase（key_epoch++）、Per-CPU 真启用、驱动 recovery ops 待做