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,935 @@
+// 编译到 SYSTEM/boot/utsm.elf
+
+# UTSM 内核模块设计
+
+UTSM 是当前内核架构中的封缄内存模块。
+
+```text
+UTSM = UUID-Tuned Sealed Memory
+中文名：UUID 调谐封缄内存
+```
+
+UTSM 的目标是在单地址空间 Ring0 高性能内核中提供一种轻量内存语义：
+
+```text
+所有普通内存可以被直接读取，但直接读取到的是密文。
+真正有效的明文读写必须经过 UTSM 读写器。
+UUID 作为进程和内存段的调谐因子。
+DRR 负责 root key、checkpoint、recovery log 和回滚。
+```
+
+---
+
+## 1. 所属总架构
+
+```text
+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 密钥缓存
+```
+
+---
+
+## 2. UTSM 核心规则
+
+```text
+1. 数据区只存连续密文。
+2. UUID 不插入数据区。
+3. UUID 使用 128-bit 二进制格式。
+4. 每个加密段有独立 DMP。
+5. 每个任务有 process_uuid 和 capability table。
+6. 读写明文必须经过 UTRW。
+7. 直接读取 cipher_base 只得到密文。
+8. 直接写入 cipher_base 会破坏段一致性，段可被标记为 POISONED。
+9. DRR 保存 root key、checkpoint、recovery log 和恢复状态。
+10. 调度器只加载 crypto context，不扫描段，不破坏 O(1) 调度。
+```
+
+---
+
+## 3. 内存布局
+
+每个 UTSM 段由 DMP 和密文数据区组成。
+
+```text
+-------------------------------+
+| DMP: Descriptor Meta Page     |
+| 段描述符元页                  |
+-------------------------------+
+| Cipher Data Page 0            |
+-------------------------------+
+| Cipher Data Page 1            |
+-------------------------------+
+| Cipher Data Page 2            |
+-------------------------------+
+| ...                           |
+-------------------------------+
+```
+
+全局区域：
+
+```text
+--------------------------------------------------+
+| Normal Encrypted Segment Region                  |
+| 普通加密段数据区                                  |
+--------------------------------------------------+
+| DMP Pool                                         |
+| 段描述符元页池                                    |
+--------------------------------------------------+
+| Segment Table                                    |
+| 全局段表                                          |
+--------------------------------------------------+
+| PCKC Area                                        |
+| Per-CPU Key Cache 区                              |
+--------------------------------------------------+
+| DRR Reserved Region                              |
+| root key / checkpoint / recovery log             |
+--------------------------------------------------+
+```
+
+---
+
+## 4. 基础类型
+
+```c
+typedef struct {
+    uint64_t hi;
+    uint64_t lo;
+} uuid128_t;
+```
+
+UUID 不转十进制字符串，原因：
+
+```text
+16 字节固定长度
+比较快
+cache 友好
+适合 KDF
+适合 SIMD
+避免十进制解析和孔洞布局
+```
+
+---
+
+## 5. 进程加密上下文
+
+```c
+struct utsm_process_context {
+    uuid128_t process_uuid;
+
+    uint64_t crypto_epoch;
+    uint64_t recovery_generation;
+
+    uint32_t capability_table_slot;
+    uint32_t capability_count;
+
+    uint32_t flags;
+};
+```
+
+字段含义：
+
+```text
+process_uuid
+    创建任务时生成的进程 UUID。
+
+crypto_epoch
+    当前密钥版本，用于重加密、回滚和 crypto erase。
+
+recovery_generation
+    当前 DRR checkpoint 版本。
+
+capability_table_slot
+    该任务 capability table 的位置。
+
+capability_count
+    该任务拥有的段能力数量。
+
+flags
+    PWC、DMA、强恢复等策略标志。
+```
+
+---
+
+## 6. 加密段描述符
+
+```c
+struct utsm_segment_desc {
+    uuid128_t segment_uuid;
+    uuid128_t owner_process_uuid;
+
+    void *cipher_base;
+    uint64_t cipher_length;
+
+    void *dmp_base;
+
+    uint64_t key_epoch;
+    uint64_t tweak_seed;
+
+    void *dirty_bitmap;
+    void *mac_table;
+
+    uint32_t generation;
+    uint32_t flags;
+
+    uint32_t state;
+    uint32_t last_cpu;
+
+    uint64_t writer_seq;
+    uint64_t checkpoint_generation;
+};
+```
+
+段状态：
+
+```text
+FREE
+ACTIVE
+CHECKPOINTING
+SEALED
+RECOVERING
+POISONED
+DESTROYED
+```
+
+---
+
+## 7. DMP 段描述符元页
+
+DMP 是热路径加速结构，替代“UUID 数字位置表”。
+
+```c
+struct utsm_dmp {
+    uint64_t magic;
+    uint32_t version;
+    uint32_t segment_slot;
+
+    uint64_t fast_base;
+    uint64_t fast_limit;
+
+    uint64_t fast_tweak_seed;
+    uint64_t fast_key_epoch;
+
+    uint64_t dirty_bitmap_base;
+    uint64_t mac_table_base;
+
+    uint64_t last_writer_seq;
+    uint32_t last_cpu;
+    uint32_t flags;
+
+    uint64_t crc;
+};
+```
+
+DMP 用于：
+
+```text
+O(1) 段定位
+快速边界检查
+tweak 生成
+Dirty Bitmap 定位
+MAC Table 定位
+checkpoint
+recovery
+```
+
+---
+
+## 8. Capability
+
+任务访问段时使用 capability，而不是裸 UUID。
+
+```c
+struct utsm_capability {
+    uint32_t segment_slot;
+    uint32_t generation;
+
+    uint32_t rights;
+    uint32_t epoch;
+
+    uint64_t uuid_digest;
+    uint64_t auth_tag;
+};
+```
+
+权限：
+
+```text
+READ
+WRITE
+EXEC
+SHARE
+DMA
+```
+
+热路径通过：
+
+```text
+segment_slot + generation + epoch
+```
+
+直接定位并验证段。
+
+---
+
+## 9. 加密规则
+
+UTSM 不使用十进制凯撒和 UUID 孔洞，改为按 cache line 的 UUID 调谐流式加密。
+
+```text
+segment_key = KDF(
+    DRR_root_key,
+    process_uuid,
+    segment_uuid,
+    key_epoch
+)
+```
+
+每 64B cache line 生成 tweak：
+
+```text
+line_index = offset / 64
+tweak = hash(tweak_seed, line_index, key_epoch)
+```
+
+加密和解密：
+
+```text
+ciphertext = plaintext  XOR stream(segment_key, tweak)
+plaintext  = ciphertext XOR stream(segment_key, tweak)
+```
+
+---
+
+## 10. UTRW 读写器
+
+UTRW 分三层：
+
+```text
+Level 0: Raw Access
+    直接读 cipher_base，得到密文。
+
+Level 1: Fast Path
+    capability O(1) 定位段，PCKC 命中，无全局锁，无 trap。
+
+Level 2: Slow Path
+    key miss、epoch mismatch、checkpoint、recovery、MAC fail 等异常处理。
+```
+
+### 10.1 读流程
+
+```text
+UTRW_READ(cap, offset, len, dst)
+    -> segment_slot 找 desc
+    -> generation 检查
+    -> rights 检查
+    -> epoch 检查
+    -> 边界检查
+    -> PCKC 取 key
+    -> 按 64B line 解密
+    -> 返回明文
+```
+
+### 10.2 写流程
+
+```text
+UTRW_WRITE(cap, offset, len, src)
+    -> segment_slot 找 desc
+    -> generation 检查
+    -> rights 检查
+    -> epoch 检查
+    -> 边界检查
+    -> PCKC 取 key
+    -> 按 64B line 加密
+    -> 写入 cipher data
+    -> 标记 dirty bitmap
+    -> writer_seq++
+    -> 按策略写 recovery log
+```
+
+部分写必须先解密旧 64B line，合并新明文后重新加密整条 line。
+
+---
+
+## 11. PCKC 每 CPU 密钥缓存
+
+```c
+struct utsm_pckc {
+    uuid128_t current_process_uuid;
+
+    uint32_t hot_segment_slot[8];
+    uint64_t hot_key_epoch[8];
+
+    void *key_schedule[8];
+
+    uint64_t hit_count;
+    uint64_t miss_count;
+};
+```
+
+规则：
+
+```text
+每 CPU 一个 PCKC。
+调度切换时只加载 next.crypto 指针和 hot_segment_hint。
+不扫描 capability table。
+不刷新全部 key。
+不破坏 PCQ 的 O(1) 调度。
+```
+
+---
+
+## 12. 与 SAS-R0-PCQ 的整合
+
+任务结构扩展：
+
+```c
+struct task {
+    uint64_t tid;
+    uint32_t state;
+    uint32_t priority;
+
+    uint64_t runtime;
+    uint64_t time_slice;
+
+    void *stack_top;
+    void *entry;
+
+    struct context cpu_context;
+
+    uint32_t last_cpu;
+    uint64_t affinity_mask;
+
+    struct utsm_process_context *crypto;
+    struct utsm_capability_table *cap_table;
+
+    uint32_t hot_segment_hint;
+    uint32_t fault_segment_slot;
+
+    uint64_t recovery_generation;
+    uint64_t heartbeat_seq;
+
+    uint32_t flags;
+
+    struct task *prev;
+    struct task *next;
+};
+```
+
+任务状态：
+
+```text
+READY
+RUNNING
+BLOCKED
+SLEEPING
+RECOVERING
+FAULTED
+ZOMBIE
+```
+
+---
+
+## 13. 任务创建流程
+
+```text
+task_create(entry, priority, flags)
+    -> 分配 TCB
+    -> 生成 tid
+    -> 生成 process_uuid
+    -> 创建 utsm_process_context
+    -> 创建 stack segment
+    -> 创建 heap segment
+    -> 创建 ipc segment 可选
+    -> 生成 capability table
+    -> cap[0] = stack
+    -> cap[1] = heap
+    -> 初始化 CPU context
+    -> 通过 UTRW_WRITE 写入 start packet
+    -> hot_segment_hint = stack segment
+    -> state = READY
+    -> enqueue_task(current_cpu)
+```
+
+默认 capability：
+
+```text
+cap[0] = stack segment, READ | WRITE
+cap[1] = heap segment, READ | WRITE
+cap[2] = ipc segment, READ | WRITE | SHARE，可选
+cap[3] = code segment, READ | EXEC，可选
+```
+
+---
+
+## 14. 调度切换流程
+
+```text
+schedule()
+    -> old = current
+    -> utsm_switch_out(old)
+    -> next = pick_next_task()
+    -> utsm_switch_in(next)
+    -> context_switch(old, next)
+```
+
+`utsm_switch_out` 只做：
+
+```text
+标记 PWC dirty flush
+保存 hot_segment_hint
+更新 recovery_generation
+更新 heartbeat
+```
+
+`utsm_switch_in` 只做：
+
+```text
+设置 PCKC.current_process_uuid
+加载 next.crypto
+检查 recovery_generation
+预热 hot_segment_hint
+```
+
+禁止在调度路径中：
+
+```text
+扫描所有 segment
+扫描 capability table
+计算 MAC
+写 checkpoint
+重加密整段
+```
+
+---
+
+## 15. Checkpoint / Rollback 协议
+
+### 15.1 Checkpoint 类型
+
+```text
+Light Checkpoint
+    保存 segment table、DMP、dirty shard summary、writer_seq、key_epoch、MAC root。
+
+Dirty Page Checkpoint
+    保存 dirty page 的密文副本、dirty page MAC、dirty shard、segment descriptor。
+
+Boot Checkpoint
+    保存内核镜像 slot、UTSM root epoch、DRR boot status、启动阶段状态。
+```
+
+### 15.2 Dirty Shard 分片
+
+Dirty Bitmap 不再只是一整块大 bitmap，而是拆成多个 Dirty Shard。
+
+```c
+struct utsm_dirty_shard {
+    uint32_t dirty_count;
+    uint32_t shard_id;
+
+    uint64_t page_base;
+    uint64_t page_count;
+
+    uint64_t last_checkpoint_epoch;
+    void *bitmap;
+};
+```
+
+规则：
+
+```text
+1. 每个 shard 管理一段连续页范围。
+2. UTRW_WRITE 标记 dirty page 时，同时更新 dirty_count。
+3. checkpoint 时 dirty_count == 0 的 shard 直接跳过。
+4. checkpoint 只扫描 dirty_count > 0 的 shard。
+5. 每 CPU 可以维护 dirty shard list，避免全局扫描。
+```
+
+复杂度从：
+
+```text
+扫描全 dirty bitmap
+```
+
+优化为：
+
+```text
+O(number_of_dirty_shards + number_of_dirty_pages)
+```
+
+### 15.3 A/B Checkpoint Metadata 双槽
+
+每个 checkpoint metadata 使用双槽。
+
+```text
+Checkpoint Metadata Slot A
+Checkpoint Metadata Slot B
+```
+
+提交规则：
+
+```text
+当前 active = A
+新 checkpoint 写 B
+B 写完 metadata、dirty index、MAC root、CRC
+flush
+最后原子切换 active = B
+旧 A 保留为 fallback
+```
+
+恢复规则：
+
+```text
+优先读取 active slot
+如果 active slot CRC 错误或 generation 不完整
+    fallback 到另一个 slot
+如果两个 slot 都损坏
+    进入 system rollback
+```
+
+这样可以避免 checkpoint 写一半崩溃导致旧稳定点也损坏。
+
+### 15.4 正常 checkpoint 流程
+
+```text
+DRR 发起 checkpoint
+    -> checkpoint_generation++
+    -> 选择 inactive metadata slot
+    -> UTSM 遍历 dirty shard list
+    -> 跳过 dirty_count == 0 的 shard
+    -> 对 dirty shard 内的 ACTIVE 段执行 checkpoint
+    -> desc.state = CHECKPOINTING
+    -> 刷出 PWC / per-CPU dirty buffer
+    -> 复制 dirty ciphertext page 到 checkpoint region
+    -> 计算 page MAC
+    -> 写 segment desc snapshot
+    -> 写 DMP snapshot
+    -> 写 dirty shard summary
+    -> 写 checkpoint metadata CRC
+    -> flush checkpoint metadata
+    -> 原子切换 active metadata slot
+    -> CHECKPOINT_COMMIT
+    -> 清 dirty bitmap / dirty_count
+    -> desc.state = ACTIVE
+```
+
+### 15.5 rollback 级别
+
+```text
+Page Rollback
+    单页损坏，从 checkpoint slot 恢复密文页。
+
+Segment Rollback
+    整段损坏，恢复 segment desc、DMP、key_epoch、dirty shard、MAC table。
+
+System Rollback
+    控制面严重损坏，写 crash reason，reboot，由 bootloader 切换 last_good_slot。
+```
+
+### 15.6 DRR Emergency Pool
+
+DRR 启动时必须预留独立紧急内存池。
+
+```text
+DRR Emergency Pool
+    emergency pages
+    recovery log buffer
+    checkpoint metadata buffer
+    DRR private stack
+    DRR metadata slab
+    crash buffer
+```
+
+规则：
+
+```text
+1. 普通 allocator 永远不能分配 Emergency Pool。
+2. Emergency Pool 只供 watchdog、checkpoint、rollback、crash dump 使用。
+3. 普通系统 OOM 不等于 DRR OOM。
+4. recovery 路径禁止依赖普通堆分配器。
+5. Emergency Pool 耗尽时直接进入 system rollback。
+```
+
+---
+
+## 16. 启动流程
+
+### 16.1 Bootloader 阶段
+
+```text
+1. 读取 Boot Control Block。
+2. 校验 BCB CRC。
+3. 选择 active_slot。
+4. 如果 active_slot 失败次数超限，切换 last_good_slot。
+5. 将 SYSTEM 作为打包后 IMG 内的系统根目录。
+6. 加载 SYSTEM/boot/utsm.elf。
+7. 加载或暴露 SYSTEM/driver/manifest.json。
+8. 传入 memory map、BCB 地址、DRR reserved region 信息。
+```
+
+### 16.2 DRR 初始化
+
+```text
+1. 保留 DRR region。
+2. 初始化 watchdog。
+3. 建立 root key 或 root key handle。
+4. 初始化 recovery log。
+5. 初始化 checkpoint region。
+6. 初始化 heartbeat page。
+7. 初始化 DRR Emergency Pool。
+8. 初始化 A/B checkpoint metadata slot。
+```
+
+### 16.3 UTSM 初始化
+
+```text
+1. 接收 DRR root key handle。
+2. 初始化 global crypto epoch。
+3. 初始化 segment table。
+4. 初始化 DMP pool。
+5. 初始化 PCKC area。
+6. 初始化 dirty shard pool。
+7. 初始化 dirty bitmap pool。
+8. 初始化 MAC table pool。
+9. 注册 UTRW fast path / slow path。
+```
+
+### 16.4 Scheduler 初始化
+
+```text
+1. 初始化 per-CPU runqueue。
+2. 初始化 per-CPU heartbeat。
+3. 初始化每 CPU PCKC。
+4. 创建 bootstrap task。
+5. 创建核心服务 task。
+6. 将 task 加入 PCQ runqueue。
+```
+
+### 16.5 Driver Manifest 加载
+
+驱动清单位于系统根目录下：
+
+```text
+SYSTEM/driver/manifest.json
+```
+
+规则：
+
+```text
+1. manifest.json 是启动驱动模块的唯一默认清单。
+2. 驱动文件使用 ELF64 .drv 格式。
+3. 驱动按 stage 分阶段加载。
+4. required=true 的驱动失败时进入 DRR recovery 或 panic。
+5. required=false 的驱动失败时标记 FAILED 并继续启动。
+6. stage0/stage1 可由 bootloader 预加载为 boot module。
+7. stage2/stage3 在文件系统可用后从 SYSTEM/driver 扫描加载。
+```
+
+默认阶段：
+
+```text
+stage0: platform，timer / apic / acpi / pci
+stage1: boot，console / block / bootfs
+stage2: filesystem，vfs / fat32 / devfs
+stage3: optional，net / input / gpu
+```
+
+### 16.6 DKM 驱动 ABI 摘要
+
+驱动模块系统：
+
+```text
+DKM = Deshab Kernel Module
+DSM = Driver Startup Manager
+```
+
+每个 ELF .drv 必须导出：
+
+```text
+driver_desc
+driver_init
+driver_exit
+```
+
+`driver_desc` 至少描述：
+
+```text
+magic / abi_version / desc_size
+name / version / vendor
+driver_class / stage / flags / priority
+depends / provides
+min_kernel_abi / feature_bits
+```
+
+驱动入口：
+
+```c
+int driver_init(const struct dkm_kernel_api *api, struct dkm_driver_handle *handle);
+int driver_exit(struct dkm_driver_handle *handle);
+```
+
+驱动默认通过 `dkm_kernel_api` 访问内核服务：
+
+```text
+log
+mem
+utsm
+irq
+pci
+dma
+vfs
+net
+timer
+drr
+```
+
+ELF loader 第一版支持：
+
+```text
+必须支持：
+    R_X86_64_64
+    R_X86_64_RELATIVE
+    R_X86_64_GLOB_DAT
+    R_X86_64_JUMP_SLOT
+
+建议支持：
+    R_X86_64_PC32
+    R_X86_64_PLT32
+    R_X86_64_32 / R_X86_64_32S
+
+第一版禁止：
+    TLS relocation
+    IFUNC
+    lazy binding
+    外部动态库依赖
+    用户态 libc 依赖
+```
+
+驱动加载状态机：
+
+```text
+DISCOVERED
+    -> QUEUED
+    -> DEP_WAIT
+    -> LOADING
+    -> ELF_CHECKED
+    -> MEMORY_ALLOCATED
+    -> RELOCATED
+    -> ABI_CHECKED
+    -> INITING
+    -> ACTIVE
+```
+
+失败状态：
+
+```text
+FAILED_ELF
+FAILED_RELOCATION
+FAILED_DEPENDENCY
+FAILED_ABI
+FAILED_INIT
+FAILED_REQUIRED
+```
+
+stage0/stage1 boot module 查找规则：
+
+```text
+1. 如果 path 在 boot module table 中，直接从内存加载。
+2. 否则如果 VFS 已可用，从 SYSTEM/path 加载。
+3. 否则返回 BOOT_MODULE_NOT_FOUND。
+```
+
+完整设计见：
+
+```text
+RE/驱动模块ABI设计.md
+```
+
+---
+
+## 17. 错误处理
+
+UTRW 错误状态：
+
+```text
+OK
+KEY_MISS_RETRY
+STALE_CAPABILITY
+EPOCH_EXPIRED
+OUT_OF_BOUNDS
+ACCESS_DENIED
+CHECKPOINT_BUSY
+RECOVERING
+MAC_FAILED
+SEGMENT_POISONED
+CORRUPTED_DESCRIPTOR
+```
+
+严重错误处理：
+
+```text
+1. 记录 task.fault_segment_slot。
+2. task.state = FAULTED。
+3. 从 runqueue 移除。
+4. 通知 DRR。
+5. DRR 决定刷新 capability、回滚 segment、kill task 或 system rollback。
+```
+
+---
+
+## 18. UTSM v1 定稿
+
+```text
+UTSM v1 包含：
+    二进制 UUID
+    连续密文数据区
+    独立 DMP
+    全局 Segment Table
+    Segment Capability
+    Per-CPU Key Cache
+    UTRW 统一读写器
+    Dirty Shard + Dirty Bitmap
+    MAC Table
+    DRR Emergency Pool
+    A/B Checkpoint Metadata
+    DRR checkpoint / rollback 对接
+    SAS-R0-PCQ task 整合
+
+加密粒度：
+    64B cache line
+
+Dirty 粒度：
+    4KB page
+
+Dirty 分片：
+    Dirty Shard，checkpoint 只扫描 dirty_count > 0 的 shard
+
+MAC 粒度：
+    4KB page
+
+Checkpoint 元数据：
+    A/B 双槽，CRC 校验，原子切换 active slot
+
+大页优化：
+    2MB hugepage 可选
+```