Record networking and DMA development progress

Add the current OS source tree, build scripts, system image layout, and development notes covering DMA page allocation, e1000 bring-up, net API dispatch, and DHCP work in progress.
2026-07-02 16:17:09 +08:00
parent fbc14631e3
commit f1a2a110d7
182 changed files with 16472 additions and 0 deletions
@@ -0,0 +1,366 @@
+# DSK 主内核说明
+
+`CODE/dsk` 是 Deshab 的主内核工程目录，目标产物为：
+
+```text
+CODE/dsk -> SYSTEM/system/deshab64/deshab.elf
+```
+
+当前启动链路分为两层：
+
+```text
+bootloader
+  -> SYSTEM/boot/utsm.elf
+       UTSM 首阶段内核 / DKM 驱动加载 / 平台发现
+       -> SYSTEM/system/deshab64/deshab.elf
+            DSK 主内核
+```
+
+也就是说，`utsm.elf` 不是最终长期运行的完整主内核，而是当前已经具备启动、封缄内存、DKM 驱动加载、平台发现和早期系统服务能力的前置内核阶段。后续 UTSM 需要继续执行到 `deshab.elf`，把控制权交给 DSK 主内核。
+
+---
+
+## 1. 模块定位
+
+DSK 是 Deshab 的主内核，负责承接 UTSM 阶段已经建立的系统基础，并进入完整内核运行期。
+
+DSK 的职责：
+
+```text
+1. 接收 UTSM 传入的 boot context / platform context。
+2. 接管主调度器、内存管理、系统服务和长期运行状态。
+3. 使用 UTSM/DKM 已完成的平台发现结果。
+4. 继续使用或接管 DKM 驱动状态。
+5. 推进真实块设备、网络、VFS 和用户任务模型。
+6. 与 DRR 恢复根协作，支持 checkpoint / recovery / rollback。
+```
+
+DSK 不应重复做已经由 UTSM 阶段完成的早期工作，例如：
+
+```text
+- Limine request 原始解析
+- early serial 初始化
+- 早期 arena 初始化
+- DKM manifest 的首轮 stage 加载
+- 纯 discovery 型平台枚举
+```
+
+DSK 应关注从“可启动实验内核”进入“可长期运行主内核”。
+
+---
+
+## 2. 产物路径
+
+主内核 ELF 固定输出到：
+
+```text
+SYSTEM/system/deshab64/deshab.elf
+```
+
+建议目录语义：
+
+```text
+SYSTEM/
+  boot/
+    utsm.elf                 # bootloader 直接加载的首阶段内核
+
+  system/
+    deshab64/
+      deshab.elf             # DSK 主内核
+
+  driver/
+    manifest.json
+    ... *.drv                # DKM 驱动模块
+```
+
+`deshab64` 表示当前主内核目标架构为 x86_64 long mode。
+
+---
+
+## 3. UTSM 到 DSK 的执行关系
+
+当前 UTSM 已完成：
+
+```text
+- long mode C 入口
+- serial log
+- UTSM/PCKC/UTRW selftest
+- IDT 0-47
+- PIC IRQ fallback
+- irq_register
+- Limine RSDP/framebuffer/module/HHDM request
+- DKM/DSM 外部 .drv 加载
+- 14/14 真实 DKM 驱动 discovery/加载闭环
+```
+
+下一步需要让 UTSM 在完成早期阶段后定位并加载：
+
+```text
+/system/deshab64/deshab.elf
+```
+
+推荐执行链：
+
+```text
+kernel_main()
+  -> serial_init()
+  -> idt_init()
+  -> utsm_init()
+  -> dkm_init()
+  -> dsm_load_from_manifest()
+  -> utsm_selftest()
+  -> dsk_load_main_kernel("/system/deshab64/deshab.elf")
+  -> dsk_build_boot_context()
+  -> dsk_jump_entry()
+```
+
+DSK 入口不应假设自己由 bootloader 直接加载，而应假设由 UTSM 传入上下文。
+
+---
+
+## 4. DSK Boot Context
+
+UTSM 跳转 DSK 时应传入一个明确版本化的上下文结构。
+
+建议第一版结构：
+
+```c
+#define DSK_BOOT_MAGIC 0x44534B31424F4F54ULL /* "DSK1BOOT" */
+#define DSK_BOOT_ABI_VERSION 1
+
+struct dsk_boot_context {
+    uint64_t magic;
+    uint32_t abi_version;
+    uint32_t size;
+
+    uint64_t flags;
+
+    uint64_t hhdm_offset;
+
+    uint64_t rsdp_address;
+
+    uint64_t framebuffer_address;
+    uint64_t framebuffer_width;
+    uint64_t framebuffer_height;
+    uint64_t framebuffer_pitch;
+    uint32_t framebuffer_bpp;
+    uint32_t reserved_fb;
+
+    uint64_t boot_modules_response;
+
+    uint64_t dkm_kernel_api;
+    uint64_t dkm_driver_table;
+    uint64_t dkm_driver_count;
+
+    uint64_t utsm_state;
+    uint64_t drr_state;
+
+    uint64_t memory_map;
+    uint64_t memory_map_count;
+    uint64_t memory_map_entry_size;
+
+    uint64_t kernel_stack_top;
+    uint64_t reserved[8];
+};
+```
+
+传参建议：
+
+```text
+RDI = struct dsk_boot_context *
+RSI = 0
+RDX = 0
+interrupt state = disabled 或明确约定
+paging = UTSM 当前页表
+address model = higher-half + HHDM
+```
+
+第一版可以只填必要字段：
+
+```text
+magic / abi_version / size
+hhdm_offset
+rsdp_address
+framebuffer 信息
+boot_modules_response
+dkm_kernel_api
+```
+
+其余字段后续逐步补齐。
+
+---
+
+## 5. DSK ELF 加载要求
+
+`deshab.elf` 建议先采用 ELF64 executable 或 relocatable-friendly layout。
+
+第一版 loader 可只支持最小集合：
+
+```text
+ELFCLASS64
+ELFDATA2LSB
+EM_X86_64
+ET_EXEC 或 ET_DYN（二选一先固定）
+PT_LOAD segment
+PF_R / PF_W / PF_X
+入口 e_entry
+```
+
+推荐第一版限制：
+
+```text
+1. 不支持动态链接。
+2. 不支持 TLS。
+3. 不支持用户态权限切换。
+4. 不支持 demand paging。
+5. 不支持 symbol resolution。
+6. 所有 PT_LOAD 一次性复制/清零。
+7. 入口地址由 e_entry 给出。
+```
+
+加载路径：
+
+```text
+1. 从 bootfs/VFS 或 Limine module 查找 /system/deshab64/deshab.elf。
+2. 校验 ELF header。
+3. 计算 PT_LOAD 覆盖范围。
+4. 分配或确认目标虚拟地址范围。
+5. 复制 file-backed bytes。
+6. 清零 memsz - filesz。
+7. 设置段权限（第一版可沿用当前 RWX 简化策略）。
+8. 构造 dsk_boot_context。
+9. 跳转 e_entry。
+```
+
+---
+
+## 6. DSK 初始功能目标
+
+第一阶段 DSK 不追求完整功能，先做可验证闭环。
+
+最小启动目标：
+
+```text
+1. 接收 dsk_boot_context。
+2. 校验 magic / abi_version / size。
+3. 复用 serial log 或 framebuffer log。
+4. 打印 DSK boot banner。
+5. 打印 hhdm / rsdp / framebuffer / driver_count。
+6. 执行 DSK selftest。
+7. 返回或 halt。
+```
+
+成功日志建议：
+
+```text
+[DSK] boot
+[DSK] context ok
+[DSK] hhdm offset=...
+[DSK] framebuffer=...
+[DSK] dkm drivers=...
+[DSK] SELFTEST PASS
+```
+
+---
+
+## 7. 后续主内核路线
+
+DSK 阶段建议按以下顺序推进：
+
+```text
+P0: DSK ELF loader + dsk_boot_context + 跳转入口
+P1: 物理页分配器 + 页表/MMIO 映射接口
+P2: DMA buffer / cache barrier / IOMMU 预留接口
+P3: AHCI IDENTIFY/READ 已具备最小 DMA 验证路径；继续推进 AHCI block provider 与 NVMe admin queue/identify
+P4: FAT32 接入真实 block provider，替代 test.fat32
+P5: IDT 256 vectors + APIC/IOAPIC/MSI IRQ backend
+P6: e1000 / virtio_net RX-TX 数据路径
+P7: 主调度器 SAS-R0-PCQ 与任务模型
+P8: DRR checkpoint / recovery log / A-B rollback
+```
+
+优先级原则：
+
+```text
+先让 UTSM 能加载并跳到 DSK。
+再补内存/MMIO/DMA。
+再做块设备真实读取。
+再迁移文件系统和网络数据路径。
+最后进入调度器和恢复系统深化。
+```
+
+---
+
+## 8. 与 UTSM 的边界
+
+UTSM 保留职责：
+
+```text
+- 封缄内存模型
+- UTRW 明文读写路径
+- DMP/PCKC
+- DKM 首轮驱动加载
+- early recovery hook
+- DSK 加载前的早期平台发现
+```
+
+DSK 接管职责：
+
+```text
+- 主内核生命周期
+- 完整内存管理
+- 完整 IRQ backend
+- 块设备与文件系统运行期
+- 网络栈运行期
+- 调度器和任务模型
+- 系统调用或内核服务入口
+```
+
+二者关系不是互斥，而是阶段化：
+
+```text
+UTSM = boot/runtime substrate
+DSK  = main kernel runtime
+```
+
+---
+
+## 9. 当前待办
+
+短期需要实现：
+
+```text
+1. 已完成：build.ps1 增加 CODE/dsk -> SYSTEM/system/deshab64/deshab.elf 构建目标。
+2. 已完成：SYSTEM/boot/limine.conf 预加载 /system/deshab64/deshab.elf。
+3. 已完成：UTSM 中实现 DSK ELF64 PT_LOAD loader，优先通过 `kernel_api.block` + 内嵌 FAT32 解析从真实块设备读取 `DESHAB.ELF`（SATA FAT32 盘已验证）；无块设备时自动回退 Limine boot module 预加载。
+4. 已完成：定义 dsk_boot_context 头文件，UTSM 与 DSK 共用。
+5. 已完成：编写 DSK 最小入口，打印 boot banner 和 SELFTEST PASS。
+6. 已完成：QEMU 验证从 UTSM 继续执行到 DSK。
+7. 已完成：把 "Limine 预加载 deshab.elf" 替换为 UTSM 通过 FAT32 block provider 读取。
+   后续：在 FAT32 中支持子目录路径，统一 DSK 加载与 VFS 路径语义。
+8. 下一步：按“块设备优先”推进 AHCI/NVMe IDENTIFY/READ 和真实 FAT32 挂载。
+```
+
+当前验证日志：
+
+```text
+[UTSM] SELFTEST PASS
+[UTSM] loading DSK
+[UTSM] DSK module size=...
+[UTSM] DSK image base=...
+[UTSM] DSK entry=...
+[UTSM] jumping to DSK
+[DSK] boot
+[DSK] context ok
+[DSK] SELFTEST PASS
+```
+
+验证标准：
+
+```text
+[UTSM] SELFTEST PASS
+[UTSM] loading DSK
+[DSK] boot
+[DSK] context ok
+[DSK] SELFTEST PASS
+```