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,504 @@
+# UTSM 算法记录
+
+```text
+UTSM = UUID-Tuned Sealed Memory
+中文名：UUID 调谐封缄内存
+```
+
+本文记录 UTSM v1 的核心算法。
+
+---
+
+## 1. 段创建算法
+
+目标：为任务创建一个只存密文的连续内存段，并返回 capability。
+
+```text
+utsm_create_segment(process, size, flags)
+    1. size 按 64B / 4KB 对齐。
+    2. 从 buddy/slab 分配 cipher data pages。
+    3. 从 DMP pool 分配 DMP。
+    4. 生成 segment_uuid。
+    5. key_epoch = process.crypto_epoch。
+    6. tweak_seed = hash(process_uuid, segment_uuid, key_epoch)。
+    7. 初始化 dirty_bitmap。
+    8. 初始化 mac_table。
+    9. 填写 utsm_segment_desc。
+    10. 填写 utsm_dmp。
+    11. generation++。
+    12. 生成 utsm_capability。
+    13. 将 capability 写入任务 capability table。
+    14. 返回 capability。
+```
+
+复杂度：
+
+```text
+段元数据初始化：O(1)
+数据页分配：O(page_count)
+热路径访问定位：O(1)
+```
+
+---
+
+## 2. 密钥派生算法
+
+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)
+```
+
+设计理由：
+
+```text
+1. 避免十进制 UUID 解析。
+2. 避免 UUID 孔洞破坏连续内存。
+3. 以 64B cache line 为单位，适合 CPU cache 和 SIMD。
+4. key_epoch 可用于快速作废旧段。
+```
+
+---
+
+## 3. UTRW Fast Read 算法
+
+```text
+UTRW_READ_FAST(cap, offset, len, dst)
+    1. desc = SEGMENT_TABLE[cap.segment_slot]。
+    2. 检查 desc.generation == cap.generation。
+    3. 检查 cap.rights 包含 READ。
+    4. 检查 cap.epoch == desc.key_epoch。
+    5. 检查 offset + len <= desc.cipher_length。
+    6. 检查 desc.state == ACTIVE。
+    7. key = PCKC_LOOKUP(desc.segment_slot, desc.key_epoch)。
+    8. 如果 key miss，进入 slow path。
+    9. 读取 writer_seq_before。
+    10. 如果 writer_seq_before 为奇数，重试或 slow path。
+    11. 对访问范围涉及的每个 64B line：
+        a. 计算 line_index。
+        b. 生成 tweak。
+        c. 读取密文 line。
+        d. 解密成明文 line。
+        e. 拷贝目标字节到 dst。
+    12. 读取 writer_seq_after。
+    13. 如果 before != after，重试。
+    14. 返回 OK。
+```
+
+复杂度：
+
+```text
+段定位：O(1)
+读写长度 n：O(n / 64)
+```
+
+---
+
+## 4. UTRW Fast Write 算法
+
+```text
+UTRW_WRITE_FAST(cap, offset, len, src)
+    1. desc = SEGMENT_TABLE[cap.segment_slot]。
+    2. 检查 desc.generation == cap.generation。
+    3. 检查 cap.rights 包含 WRITE。
+    4. 检查 cap.epoch == desc.key_epoch。
+    5. 检查 offset + len <= desc.cipher_length。
+    6. 检查 desc.state == ACTIVE。
+    7. key = PCKC_LOOKUP(desc.segment_slot, desc.key_epoch)。
+    8. 如果 key miss，进入 slow path。
+    9. 如果是强恢复段，写 WRITE_INTENT log。
+    10. writer_seq++，进入奇数写入状态。
+    11. 对访问范围涉及的每个 64B line：
+        a. 计算 line_index。
+        b. 生成 tweak。
+        c. 如果覆盖完整 line，直接使用 src 明文。
+        d. 如果部分覆盖 line，读取旧密文，解密旧明文，合并新明文。
+        e. 加密成新密文。
+        f. 写回 cipher data。
+    12. 标记 dirty_bitmap。
+    13. writer_seq++，回到偶数稳定状态。
+    14. 如果是强恢复段，写 WRITE_COMMIT log。
+    15. 返回 OK。
+```
+
+部分写规则：
+
+```text
+UTSM 的加密单位是 64B line。
+如果只写 line 的一部分，必须读旧密文、解密、合并、重新加密整条 line。
+```
+
+---
+
+## 5. UTRW Slow Path 算法
+
+Slow Path 触发条件：
+
+```text
+PCKC key miss
+generation mismatch
+epoch mismatch
+state != ACTIVE
+checkpoint busy
+recovery busy
+MAC failed
+segment poisoned
+out of bounds
+access denied
+```
+
+处理策略：
+
+```text
+KEY_MISS
+    -> 派生 segment_key
+    -> 生成 key_schedule
+    -> 写入 PCKC
+    -> 回到 fast path
+
+STALE_CAPABILITY
+    -> 尝试从 capability table 刷新
+    -> 失败则返回错误
+
+EPOCH_EXPIRED
+    -> 刷新 cap.epoch 和 auth_tag
+    -> 清除旧 PCKC key
+    -> 回到 fast path
+
+CHECKPOINT_BUSY
+    -> 短暂等待或写 side log
+
+RECOVERING
+    -> 阻塞任务，等待 DRR 完成恢复
+
+MAC_FAILED
+    -> 标记 suspicious page
+    -> 通知 DRR
+    -> 尝试 page rollback
+
+SEGMENT_POISONED
+    -> 拒绝访问
+    -> 交给 DRR 决定回滚、重建或 kill task
+```
+
+---
+
+## 6. PCKC 查找算法
+
+每 CPU 保存少量热段 key。
+
+```text
+PCKC_LOOKUP(slot, epoch)
+    1. 检查 current hot slot。
+    2. 检查 hot_segment_slot[0..N]。
+    3. 如果 slot 和 epoch 均匹配，返回 key_schedule。
+    4. 否则返回 MISS。
+```
+
+替换策略：
+
+```text
+第一版使用小型 LRU 或替换最冷 slot。
+```
+
+建议槽数：
+
+```text
+8 个 key slot 起步。
+高并发或服务型任务可扩展到 16 个。
+```
+
+---
+
+## 7. Checkpoint 算法
+
+### 7.1 Dirty Shard 标记算法
+
+Dirty Bitmap 分片为 Dirty Shard，避免 checkpoint 扫描整块大 bitmap。
+
+```text
+UTSM_MARK_DIRTY(desc, page_index)
+    1. shard = desc.dirty_shards[page_index / PAGES_PER_SHARD]。
+    2. bit = page_index % PAGES_PER_SHARD。
+    3. 如果 bit 原来是 0：
+        a. 设置 bitmap bit。
+        b. shard.dirty_count++。
+        c. 如果 shard.dirty_count 从 0 变为 1，加入 per-cpu dirty_shard_list。
+    4. 返回。
+```
+
+复杂度：
+
+```text
+Dirty 标记：O(1)
+Checkpoint 扫描：O(number_of_dirty_shards + number_of_dirty_pages)
+```
+
+### 7.2 A/B Checkpoint Metadata 提交算法
+
+```text
+CHECKPOINT_METADATA_COMMIT(gen)
+    1. active = checkpoint.active_slot。
+    2. inactive = opposite(active)。
+    3. 清理 inactive slot 的临时状态。
+    4. 写 inactive.metadata_header。
+    5. 写 segment desc snapshot。
+    6. 写 DMP snapshot。
+    7. 写 dirty shard summary。
+    8. 写 MAC root。
+    9. 写 generation。
+    10. 计算并写 CRC。
+    11. flush inactive slot。
+    12. 原子切换 checkpoint.active_slot = inactive。
+    13. 写 CHECKPOINT_COMMIT log。
+```
+
+恢复时：
+
+```text
+1. 读取 active slot。
+2. 校验 generation 和 CRC。
+3. 如果 active 有效，使用 active。
+4. 如果 active 无效，校验 fallback slot。
+5. 如果 fallback 有效，使用 fallback。
+6. 如果双槽都无效，进入 system rollback。
+```
+
+### 7.3 Dirty Page Checkpoint 算法
+
+```text
+DRR_CHECKPOINT()
+    1. checkpoint_generation++。
+    2. 写 CHECKPOINT_BEGIN log。
+    3. inactive_slot = opposite(active_slot)。
+    4. 遍历 per-cpu dirty_shard_list。
+    5. 跳过 dirty_count == 0 的 shard。
+    6. 对每个 dirty shard：
+        a. 找到关联 segment。
+        b. desc.state = CHECKPOINTING。
+        c. 冻结 writer。
+        d. flush PWC / per-CPU dirty buffer。
+        e. 只扫描 shard 内 dirty bit。
+        f. 复制 dirty ciphertext page 到 checkpoint region。
+        g. 计算 page MAC。
+        h. 写 dirty shard summary。
+        i. 清 shard bitmap。
+        j. shard.dirty_count = 0。
+        k. desc.state = ACTIVE。
+    7. 写 segment desc snapshot。
+    8. 写 DMP snapshot。
+    9. CHECKPOINT_METADATA_COMMIT(checkpoint_generation)。
+```
+
+提交规则：
+
+```text
+只有存在 CHECKPOINT_COMMIT 且 CRC 正确的 checkpoint 才是稳定点。
+中途崩溃的 checkpoint 直接丢弃。
+A/B metadata 至少保留一个旧稳定点。
+```
+
+### 7.4 DRR Emergency Pool 分配算法
+
+DRR Recovery 路径不能依赖普通 allocator。
+
+```text
+DRR_EMERGENCY_ALLOC(size, class)
+    1. 从 DRR emergency pool 的 class freelist 取对象。
+    2. 如果 freelist 非空，返回对象。
+    3. 如果 freelist 为空，从 emergency pages 切分。
+    4. 如果 emergency pages 不足：
+        a. 写 EMERGENCY_POOL_EXHAUSTED。
+        b. 进入 system rollback。
+```
+
+Emergency Pool 包含：
+
+```text
+DRR private stack
+recovery log buffer
+checkpoint metadata buffer
+crash buffer
+metadata slab
+emergency pages
+```
+
+规则：
+
+```text
+普通 allocator 不可使用 Emergency Pool。
+Emergency Pool 不参与普通内存回收。
+DRR OOM 直接视为不可恢复故障。
+```
+
+---
+
+## 8. Rollback 算法
+
+分三级。
+
+### 8.1 Page Rollback
+
+```text
+1. 定位最近稳定 checkpoint。
+2. 校验 checkpoint page MAC。
+3. 将旧密文页复制回 cipher data。
+4. 恢复 page MAC。
+5. 清 dirty bit。
+6. 段保持 ACTIVE。
+```
+
+### 8.2 Segment Rollback
+
+```text
+1. desc.state = RECOVERING。
+2. 恢复 segment desc snapshot。
+3. 恢复 DMP snapshot。
+4. 恢复 key_epoch。
+5. 恢复 dirty bitmap。
+6. 恢复 mac_table。
+7. 清除对应 PCKC key。
+8. desc.state = ACTIVE。
+```
+
+### 8.3 System Rollback
+
+```text
+1. DRR 写 crash reason。
+2. 标记 boot attempt failed。
+3. 触发 reboot。
+4. bootloader 读取 BCB。
+5. 如果失败次数超限，切换 last_good_slot。
+```
+
+---
+
+## 9. 任务创建算法
+
+```text
+task_create(entry, priority, flags)
+    1. 分配 TCB。
+    2. 生成 tid。
+    3. 生成 process_uuid。
+    4. 创建 utsm_process_context。
+    5. 创建 stack segment。
+    6. 创建 heap segment。
+    7. 可选创建 ipc segment。
+    8. 初始化 capability table。
+    9. cap[0] = stack。
+    10. cap[1] = heap。
+    11. 初始化 CPU context。
+    12. 通过 UTRW_WRITE 写入 task_start_packet。
+    13. hot_segment_hint = stack.segment_slot。
+    14. state = READY。
+    15. enqueue_task(current_cpu)。
+```
+
+---
+
+## 10. 调度切换算法
+
+```text
+schedule()
+    1. old = current。
+    2. utsm_switch_out(old)。
+    3. next = pick_next_task()。
+    4. utsm_switch_in(next)。
+    5. context_switch(old, next)。
+```
+
+`utsm_switch_out`：
+
+```text
+1. 如果 old 有 PWC dirty，登记 flush pending。
+2. 保存 old.hot_segment_hint。
+3. 更新 old.recovery_generation。
+4. 更新 heartbeat。
+```
+
+`utsm_switch_in`：
+
+```text
+1. 如果 next.state == RECOVERING，跳过。
+2. PCKC.current_process_uuid = next.crypto.process_uuid。
+3. PCKC.current_crypto_epoch = next.crypto.crypto_epoch。
+4. 预热 next.hot_segment_hint。
+```
+
+调度路径禁止：
+
+```text
+扫描段
+扫描 capability table
+计算 MAC
+写 checkpoint
+重加密整段
+```
+
+---
+
+## 11. 任务异常处理算法
+
+```text
+UTRW_DETECT_FAULT(task, segment, error)
+    1. task.fault_segment_slot = segment.slot。
+    2. task.state = FAULTED。
+    3. 从 runqueue 移除。
+    4. 写 DRR fault event。
+    5. DRR 判断：
+        a. 刷新 capability。
+        b. page rollback。
+        c. segment rollback。
+        d. kill task。
+        e. system rollback。
+```
+
+任务 kill：
+
+```text
+task_kill(task)
+    1. task.state = ZOMBIE。
+    2. 从 runqueue 移除。
+    3. revoke capability table。
+    4. owned segment key_epoch++。
+    5. desc.state = DESTROYED。
+    6. 加入 deferred free。
+    7. 写 TASK_KILL recovery log。
+```
+
+---
+
+## 12. 复杂度总结
+
+```text
+段定位：O(1)
+UTRW 读写：O(n / 64)
+PCKC 命中：O(1)
+PCKC miss：O(KDF + key schedule)
+Dirty 标记：O(1)
+Checkpoint：O(number_of_dirty_shards + number_of_dirty_pages)
+A/B metadata 切换：O(1)
+DRR emergency alloc：O(1)
+Page rollback：O(1 page)
+Segment rollback：O(segment_dirty_pages + metadata)
+调度切换额外成本：O(1)
+```
@@ -0,0 +1,485 @@
+# UTSM 设计架构记录
+
+本文记录 Deshab 内核当前 UTSM 相关架构定稿。
+
+---
+
+## 1. 架构目标
+
+UTSM 的目标不是传统强安全隔离，而是在极高权限、极高效率的单地址空间 Ring0 内核中提供一种封缄内存模型。
+
+核心目标：
+
+```text
+所有普通内存可读，但默认是密文。
+明文读写必须通过 UTRW。
+UUID 作为进程和内存段的调谐因子。
+数据区保持连续，避免 UUID 孔洞。
+DRR 提供 root key、checkpoint、recovery log 和回滚。
+调度器保持 O(1)。
+```
+
+---
+
+## 2. 总架构模块
+
+```text
+Deshab Kernel Core
+
+SAS-R0-PCQ
+    单地址空间 Ring0 任务模型
+    Per-CPU O(1) 位图调度器
+
+DRR
+    Dedicated Recovery Root
+    专用恢复根
+    watchdog / root key / checkpoint / recovery log / A-B rollback
+
+UTSM
+    UUID-Tuned Sealed Memory
+    UUID 调谐封缄内存
+
+UTRW
+    UTSM Tagged Reader/Writer
+    UTSM 带标记读写器
+
+DMP
+    Descriptor Meta Page
+    段描述符元页
+
+PCKC
+    Per-CPU Key Cache
+    每 CPU 密钥缓存
+```
+
+---
+
+## 3. UTSM 内存模型
+
+每个 UTSM 段由两部分组成：
+
+```text
+DMP + Cipher Data
+```
+
+布局：
+
+```text
+-------------------------------+
+| DMP: Descriptor Meta Page     |
+-------------------------------+
+| Cipher Data Page 0            |
+-------------------------------+
+| Cipher Data Page 1            |
+-------------------------------+
+| Cipher Data Page 2            |
+-------------------------------+
+| ...                           |
+-------------------------------+
+```
+
+规则：
+
+```text
+DMP 不属于用户数据。
+Cipher Data 只存密文。
+UUID 不插入 Cipher Data。
+数据区保持连续。
+```
+
+---
+
+## 4. 关键设计替代
+
+从原始构想到 UTSM v1 的替代关系：
+
+```text
+十进制 UUID
+    -> 128-bit 二进制 UUID
+
+UUID 数字间隔插入内存
+    -> 独立 DMP 元数据页
+
+UUID 数字位置表
+    -> segment_slot + generation + tweak_seed
+
+十进制凯撒
+    -> UUID 调谐的 cache-line 流式加密
+
+每次传统 syscall
+    -> Ring0 fast accessor + PCKC
+
+写入时避开 UUID
+    -> 连续密文数据区直接写
+```
+
+---
+
+## 5. 数据结构架构
+
+### 5.1 uuid128_t
+
+```c
+typedef struct {
+    uint64_t hi;
+    uint64_t lo;
+} uuid128_t;
+```
+
+### 5.2 utsm_process_context
+
+```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;
+};
+```
+
+### 5.3 utsm_segment_desc
+
+```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;
+};
+```
+
+### 5.4 utsm_dmp
+
+```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;
+};
+```
+
+### 5.5 utsm_capability
+
+```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;
+};
+```
+
+---
+
+## 6. 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。
+    poisoned segment。
+```
+
+读写基本流程：
+
+```text
+Read:
+    cap -> segment desc -> PCKC key -> 64B line 解密 -> 返回明文
+
+Write:
+    cap -> segment desc -> PCKC key -> 64B line 加密 -> 写密文 -> dirty bitmap -> recovery log
+```
+
+---
+
+## 7. DRR 协作架构
+
+DRR 保存：
+
+```text
+root_key 或 root_key handle
+global_crypto_epoch
+segment table snapshot
+DMP snapshot
+dirty shard summary
+dirty bitmap
+MAC root
+recovery log
+poisoned segment list
+Boot Control Block
+DRR Emergency Pool
+A/B checkpoint metadata slot
+```
+
+DRR 负责：
+
+```text
+watchdog 检测
+freeze-all
+checkpoint
+page rollback
+segment rollback
+system rollback
+A/B 镜像回滚
+```
+
+---
+
+## 8. Checkpoint / Rollback 架构
+
+Checkpoint 类型：
+
+```text
+Light Checkpoint
+    控制面快照。
+
+Dirty Page Checkpoint
+    dirty ciphertext page 快照。
+
+Boot Checkpoint
+    启动状态和 A/B slot 信息。
+```
+
+### 8.1 Dirty Shard
+
+Dirty Bitmap 采用分片结构。
+
+```text
+Dirty Shard
+    dirty_count
+    shard_id
+    page_base
+    page_count
+    last_checkpoint_epoch
+    bitmap
+```
+
+checkpoint 时：
+
+```text
+dirty_count == 0 的 shard 直接跳过。
+dirty_count > 0 的 shard 才扫描 dirty bit。
+```
+
+这样 checkpoint 成本为：
+
+```text
+O(number_of_dirty_shards + number_of_dirty_pages)
+```
+
+### 8.2 A/B Checkpoint Metadata
+
+checkpoint metadata 使用双槽：
+
+```text
+Checkpoint Metadata Slot A
+Checkpoint Metadata Slot B
+```
+
+写入规则：
+
+```text
+写 inactive slot
+写 metadata / dirty index / MAC root / CRC
+flush
+原子切换 active slot
+旧 slot 作为 fallback
+```
+
+恢复规则：
+
+```text
+active slot 有效 -> 使用 active
+active slot 无效 -> fallback 另一个 slot
+双槽都无效 -> system rollback
+```
+
+### 8.3 DRR Emergency Pool
+
+DRR 独立预留紧急内存池。
+
+```text
+DRR Emergency Pool
+    DRR private stack
+    recovery log buffer
+    checkpoint metadata buffer
+    crash buffer
+    metadata slab
+    emergency pages
+```
+
+约束：
+
+```text
+普通 allocator 不可使用。
+普通 OOM 不影响 DRR recovery。
+DRR recovery 路径禁止依赖普通堆分配器。
+Emergency Pool 耗尽时进入 system rollback。
+```
+
+Rollback 级别：
+
+```text
+Page Rollback
+    单页恢复。
+
+Segment Rollback
+    整段恢复。
+
+System Rollback
+    重启并由 bootloader 切换 last_good_slot。
+```
+
+---
+
+## 9. 与 SAS-R0-PCQ 的整合
+
+UTSM Task 是：
+
+```text
+Ring0 调度实体
+ process_uuid
+ crypto context
+ capability table
+ encrypted stack/heap
+ PCKC hot hint
+ DRR recovery generation
+```
+
+调度切换：
+
+```text
+schedule()
+    -> utsm_switch_out(old)
+    -> pick_next_task()
+    -> utsm_switch_in(next)
+    -> context_switch(old, next)
+```
+
+调度路径只允许：
+
+```text
+设置 crypto 指针
+加载 process_uuid
+预热 hot_segment_hint
+标记 PWC dirty flush
+```
+
+禁止：
+
+```text
+扫描段
+扫描 capability table
+计算 MAC
+写 checkpoint
+重加密整段
+```
+
+---
+
+## 10. 启动顺序
+
+```text
+Bootloader
+    -> 读取 Boot Control Block
+    -> 选择 active_slot / last_good_slot
+    -> 加载 SYSTEM/boot/utsm.elf
+    -> 传入 memory map 和 DRR region
+
+DRR Init
+    -> 初始化 watchdog
+    -> 建立 root key handle
+    -> 初始化 recovery log
+    -> 初始化 checkpoint region
+    -> 初始化 heartbeat page
+    -> 初始化 DRR Emergency Pool
+    -> 初始化 A/B checkpoint metadata slot
+
+UTSM Init
+    -> 初始化 global crypto epoch
+    -> 初始化 segment table
+    -> 初始化 DMP pool
+    -> 初始化 PCKC area
+    -> 初始化 dirty shard pool
+    -> 初始化 dirty bitmap / MAC table pool
+    -> 注册 UTRW fast path / slow path
+
+Scheduler Init
+    -> 初始化 per-CPU runqueue
+    -> 初始化 per-CPU heartbeat
+    -> 初始化每 CPU PCKC
+    -> 创建 bootstrap task
+    -> 创建核心服务 task
+```
+
+---
+
+## 11. 当前定稿边界
+
+UTSM v1 确定：
+
+```text
+加密粒度：64B cache line
+Dirty 粒度：4KB page
+Dirty 分片：Dirty Shard
+MAC 粒度：4KB page
+段定位：O(1)
+调度额外成本：O(1)
+checkpoint 成本：O(dirty shards + dirty pages)
+checkpoint metadata：A/B 双槽，CRC 校验，原子切换
+DRR recovery 内存：Emergency Pool 独立预留
+```
+
+暂不追求：
+
+```text
+完整 RAM 原地回滚
+对恶意 Ring0 代码的强安全隔离
+设备外部副作用回滚
+```
+
+设备恢复策略：
+
+```text
+内存恢复后，设备 reset/reinit。
+磁盘依赖文件系统 journal。
+网卡 TX 已发包不回滚，RX/TX ring 重建。
+```
@@ -0,0 +1,627 @@
+# Deshab 驱动模块 ABI 设计
+
+本文记录 Deshab 内核启动驱动模块系统的 ABI、manifest、ELF loader、加载状态机和 stage0/stage1 boot module 方案。
+
+---
+
+## 1. 总体定义
+
+驱动模块系统命名：
+
+```text
+DKM = Deshab Kernel Module
+DSM = Driver Startup Manager
+```
+
+当前规则：
+
+```text
+驱动目录：SYSTEM/driver
+驱动清单：SYSTEM/driver/manifest.json
+驱动格式：ELF64 .drv
+加载模式：module loading
+启动顺序：staged loading
+内存模型：UTSM
+```
+
+---
+
+## 2. driver_desc ABI
+
+每个驱动必须导出三个符号：
+
+```text
+driver_desc
+driver_init
+driver_exit
+```
+
+### 2.1 driver_desc
+
+```c
+#define DKM_DRIVER_MAGIC 0x444B4D31u /* "DKM1" */
+#define DKM_ABI_VERSION  1
+
+struct dkm_driver_desc {
+    uint32_t magic;
+    uint16_t abi_version;
+    uint16_t desc_size;
+
+    const char *name;
+    const char *version;
+    const char *vendor;
+
+    uint32_t driver_class;
+    uint32_t stage;
+    uint32_t flags;
+    uint32_t priority;
+
+    const char *const *depends;
+    uint32_t depends_count;
+
+    const char *const *provides;
+    uint32_t provides_count;
+
+    uint64_t min_kernel_abi;
+    uint64_t feature_bits;
+
+    uint64_t reserved0;
+    uint64_t reserved1;
+};
+```
+
+### 2.2 driver_class
+
+```text
+DKM_CLASS_PLATFORM
+DKM_CLASS_BUS
+DKM_CLASS_INTERRUPT
+DKM_CLASS_TIMER
+DKM_CLASS_CONSOLE
+DKM_CLASS_STORAGE
+DKM_CLASS_FS
+DKM_CLASS_NET
+DKM_CLASS_INPUT
+DKM_CLASS_GPU
+DKM_CLASS_MISC
+```
+
+### 2.3 flags
+
+```text
+DKM_F_REQUIRED
+    当前 stage 中失败则进入 DRR recovery 或 panic。
+
+DKM_F_BOOT_MODULE
+    可由 bootloader 预加载。
+
+DKM_F_NO_UNLOAD
+    不允许卸载。
+
+DKM_F_STRONG_RECOVERY
+    驱动 data 段使用 UTSM 强恢复策略。
+
+DKM_F_DMA_REQUIRED
+    驱动需要 DMA API。
+
+DKM_F_EARLY_LOG
+    驱动 init 期间允许使用 early log。
+```
+
+### 2.4 driver_init / driver_exit
+
+```c
+typedef int (*dkm_driver_init_fn)(const struct dkm_kernel_api *api,
+                                  struct dkm_driver_handle *handle);
+
+typedef int (*dkm_driver_exit_fn)(struct dkm_driver_handle *handle);
+```
+
+约定：
+
+```text
+driver_init 返回 0 表示成功。
+driver_init 返回负数表示失败。
+driver_exit 只用于非 NO_UNLOAD 驱动。
+required 驱动 init 失败会触发 DRR recovery 或 panic。
+optional 驱动 init 失败会被标记为 FAILED。
+```
+
+---
+
+## 3. kernel_api ABI
+
+驱动不直接依赖任意内核符号，默认通过 `dkm_kernel_api` 调用内核服务。
+
+### 3.1 API 总结构
+
+```c
+#define DKM_KERNEL_API_VERSION 1
+
+struct dkm_kernel_api {
+    uint32_t version;
+    uint32_t size;
+    uint64_t feature_bits;
+
+    const struct dkm_log_api *log;
+    const struct dkm_mem_api *mem;
+    const struct dkm_utsm_api *utsm;
+    const struct dkm_irq_api *irq;
+    const struct dkm_pci_api *pci;
+    const struct dkm_dma_api *dma;
+    const struct dkm_vfs_api *vfs;
+    const struct dkm_net_api *net;
+    const struct dkm_timer_api *timer;
+    const struct dkm_drr_api *drr;
+};
+```
+
+### 3.2 log API
+
+```c
+struct dkm_log_api {
+    void (*info)(const char *fmt, ...);
+    void (*warn)(const char *fmt, ...);
+    void (*error)(const char *fmt, ...);
+    void (*panic)(const char *fmt, ...);
+};
+```
+
+### 3.3 memory API
+
+```c
+struct dkm_mem_api {
+    void *(*alloc)(uint64_t size, uint32_t flags);
+    void (*free)(void *ptr);
+
+    void *(*alloc_pages)(uint32_t order, uint32_t flags);
+    void (*free_pages)(void *ptr, uint32_t order);
+
+    void *(*mmio_map)(uint64_t phys, uint64_t size, uint32_t flags);
+    void (*mmio_unmap)(void *virt, uint64_t size);
+};
+```
+
+### 3.4 UTSM API
+
+```c
+struct dkm_utsm_api {
+    int (*create_segment)(uint64_t size, uint32_t flags, struct utsm_capability *out);
+    int (*read)(struct utsm_capability cap, uint64_t off, void *dst, uint64_t len);
+    int (*write)(struct utsm_capability cap, uint64_t off, const void *src, uint64_t len);
+    int (*pin)(struct utsm_capability cap, uint64_t off, uint64_t len, void **window);
+    int (*unpin)(void *window, uint32_t flags);
+};
+```
+
+### 3.5 IRQ API
+
+```c
+struct dkm_irq_api {
+    int (*register_irq)(uint32_t vector, int (*handler)(void *ctx), void *ctx, uint32_t flags);
+    int (*unregister_irq)(uint32_t vector);
+    void (*ack)(uint32_t vector);
+};
+```
+
+### 3.6 PCI API
+
+```c
+struct dkm_pci_api {
+    int (*scan)(int (*cb)(const struct pci_device *dev, void *ctx), void *ctx);
+    int (*enable_device)(const struct pci_device *dev);
+    uint64_t (*bar_phys)(const struct pci_device *dev, uint32_t bar);
+    uint64_t (*bar_size)(const struct pci_device *dev, uint32_t bar);
+};
+```
+
+### 3.7 DMA API
+
+```c
+struct dkm_dma_api {
+    int (*alloc)(uint64_t size, uint32_t flags, struct dkm_dma_buffer *out);
+    void (*free)(struct dkm_dma_buffer *buf);
+    int (*sync_for_device)(struct dkm_dma_buffer *buf);
+    int (*sync_for_cpu)(struct dkm_dma_buffer *buf);
+};
+```
+
+### 3.8 VFS / NET / TIMER / DRR API
+
+第一版只定义边界：
+
+```text
+vfs: register_fs / mount / open / read / write / close
+net: register_netdev / submit_tx / poll_rx
+timer: sleep_ns / call_later / monotonic_ns
+drr: register_recovery_ops / report_fault / mark_critical
+```
+
+详细结构后续随对应子系统实现细化。
+
+---
+
+## 4. ELF Loader 支持的 relocation
+
+第一版仅支持 x86_64 ELF64 小型内核模型。
+
+### 4.1 必须支持
+
+```text
+R_X86_64_64
+    绝对 64-bit 地址重定位。
+
+R_X86_64_RELATIVE
+    base + addend。
+
+R_X86_64_GLOB_DAT
+    GOT 符号地址。
+
+R_X86_64_JUMP_SLOT
+    PLT 函数地址。
+```
+
+### 4.2 建议支持
+
+```text
+R_X86_64_PC32
+    32-bit PC-relative 调用。
+
+R_X86_64_PLT32
+    PLT-relative 调用。
+
+R_X86_64_32 / R_X86_64_32S
+    仅允许确认地址范围安全时使用。
+```
+
+### 4.3 第一版禁止
+
+```text
+TLS relocation
+IFUNC
+lazy binding
+外部动态库依赖
+用户态 libc 依赖
+异常展开表强依赖
+```
+
+### 4.4 加载流程
+
+```text
+DKM_ELF_LOAD(path_or_boot_module)
+    1. 读取 ELF header。
+    2. 校验 ELFCLASS64 / EM_X86_64 / endian / ABI。
+    3. 读取 program headers 或 section headers。
+    4. 计算模块内存大小和对齐。
+    5. 通过 UTSM 创建 code/data 段。
+    6. 加载 PT_LOAD 或 SHF_ALLOC section。
+    7. 清零 .bss。
+    8. 解析 symbol table。
+    9. 解析 relocation section。
+    10. 将内核导出符号或 kernel_api 符号填入。
+    11. 执行 relocation。
+    12. 查找 driver_desc / driver_init / driver_exit。
+    13. 设置 code 段 READ|EXEC|SEALED。
+    14. 设置 data 段 READ|WRITE|STRONG_RECOVERY。
+    15. 返回 module handle。
+```
+
+---
+
+## 5. manifest.json 格式
+
+当前使用 JSON，不再使用 ini 格式的 manifest.drv。
+
+路径：
+
+```text
+SYSTEM/driver/manifest.json
+```
+
+### 5.1 顶层字段
+
+```json
+{
+  "schema": "deshab.driver.manifest.v1",
+  "root": "SYSTEM",
+  "driverRoot": "SYSTEM/driver",
+  "format": "elf64-drv",
+  "abi": {},
+  "policy": {},
+  "stages": []
+}
+```
+
+### 5.2 abi 字段
+
+```json
+{
+  "name": "DKM",
+  "version": 1,
+  "entry": "driver_init",
+  "exit": "driver_exit",
+  "descriptor": "driver_desc"
+}
+```
+
+### 5.3 policy 字段
+
+```json
+{
+  "loadModel": "module",
+  "loadOrder": "staged",
+  "requiredFailure": "drr_recovery_or_panic",
+  "optionalFailure": "mark_failed_and_continue",
+  "memoryModel": "UTSM",
+  "codeSegment": "READ|EXEC|SEALED",
+  "dataSegment": "READ|WRITE|STRONG_RECOVERY",
+  "dmaSegment": "DMA|PINNED"
+}
+```
+
+### 5.4 stage 字段
+
+```json
+{
+  "id": 0,
+  "name": "platform",
+  "required": true,
+  "description": "平台发现、中断、总线、基础计时。",
+  "drivers": []
+}
+```
+
+### 5.5 driver 字段
+
+```json
+{
+  "name": "pci",
+  "path": "driver/bus/pci.drv",
+  "class": "bus",
+  "required": true,
+  "depends": ["irq"],
+  "provides": ["pci"]
+}
+```
+
+### 5.6 路径规则
+
+```text
+manifest 中的 path 相对 SYSTEM 根目录。
+SYSTEM/driver/manifest.json 内的 driver/bus/pci.drv 指向 SYSTEM/driver/bus/pci.drv。
+stage0/stage1 驱动允许来自 boot module，不要求文件系统已挂载。
+stage2/stage3 驱动默认从 SYSTEM/driver 加载。
+```
+
+---
+
+## 6. 驱动加载状态机
+
+```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
+```
+
+卸载状态：
+
+```text
+ACTIVE
+    -> QUIESCING
+    -> EXITING
+    -> UNLOADING
+    -> UNLOADED
+```
+
+恢复状态：
+
+```text
+ACTIVE
+    -> SUSPENDED_BY_DRR
+    -> RECOVERING
+    -> REINITING
+    -> ACTIVE
+```
+
+### 6.1 加载策略
+
+```text
+1. DSM 读取 manifest.json。
+2. 按 stage 顺序加载。
+3. 每个 stage 内按 priority 排序。
+4. 检查 depends 是否已由 provides 满足。
+5. 未满足依赖的驱动进入 DEP_WAIT。
+6. 每轮加载成功后更新 provides set。
+7. 一轮后仍 DEP_WAIT 的 required 驱动进入 FAILED_REQUIRED。
+8. optional 驱动失败只记录状态。
+```
+
+### 6.2 required 失败策略
+
+```text
+stage0/stage1 required 失败：
+    -> DRR report_fault
+    -> 尝试 boot fallback
+    -> 不可恢复则 panic / system rollback
+
+stage2 required 失败：
+    -> DRR recovery
+    -> fallback 到 bootfs 或只读模式
+
+stage3 optional 失败：
+    -> mark FAILED
+    -> continue boot
+```
+
+---
+
+## 7. stage0/stage1 boot module 方案
+
+问题：
+
+```text
+stage0/stage1 负责 timer、irq、pci、bootfs、block 等早期能力。
+此时 VFS 和普通文件系统可能还没准备好。
+所以不能完全依赖 SYSTEM/driver 的普通文件遍历。
+```
+
+### 7.1 Bootloader 预加载
+
+bootloader 负责把关键文件作为 boot module 交给内核：
+
+```text
+SYSTEM/driver/manifest.json
+SYSTEM/driver/platform/timer.drv
+SYSTEM/driver/platform/apic.drv
+SYSTEM/driver/bus/pci.drv
+SYSTEM/driver/fs/bootfs.drv
+```
+
+可选：
+
+```text
+SYSTEM/driver/console/console_fb.drv
+SYSTEM/driver/block/ahci.drv
+SYSTEM/driver/block/nvme.drv
+```
+
+### 7.2 Boot Module 表
+
+内核早期接收 boot module 表：
+
+```c
+struct dkm_boot_module {
+    const char *path;
+    void *base;
+    uint64_t size;
+    uint32_t type;
+    uint32_t flags;
+    uint64_t checksum;
+};
+
+struct dkm_boot_module_table {
+    uint32_t count;
+    struct dkm_boot_module modules[];
+};
+```
+
+### 7.3 查找规则
+
+```text
+DSM_LOAD_DRIVER(path)
+    1. 如果 path 在 boot module table 中，直接从内存加载。
+    2. 否则如果 VFS 已可用，从 SYSTEM/path 加载。
+    3. 否则返回 BOOT_MODULE_NOT_FOUND。
+```
+
+### 7.4 stage0/stage1 限制
+
+```text
+1. 不依赖普通 VFS。
+2. 不依赖普通 heap。
+3. 优先使用 early allocator 或 DRR emergency-safe allocator。
+4. 日志使用 early log。
+5. 不启动复杂后台任务。
+6. 只注册最小服务能力。
+```
+
+### 7.5 stage 切换点
+
+```text
+stage0 完成：
+    timer / irq / pci 基础能力可用。
+
+stage1 完成：
+    bootfs 或 block + fs 基础能力可用。
+
+stage2 开始：
+    VFS 可用，可以从 SYSTEM/driver 正常读取更多驱动。
+
+stage3 开始：
+    普通调度、网络、输入、图形等可异步加载。
+```
+
+---
+
+## 8. 与 UTSM / DRR 的关系
+
+### 8.1 UTSM 内存策略
+
+```text
+驱动 text：READ | EXEC | SEALED
+驱动 rodata：READ | SEALED
+驱动 data：READ | WRITE | STRONG_RECOVERY
+驱动 bss：READ | WRITE | STRONG_RECOVERY
+驱动 DMA：DMA | PINNED，必要时 CIPHERTEXT_DMA 或 NO_ENCRYPT
+```
+
+### 8.2 DRR 记录项
+
+DRR 为每个驱动记录：
+
+```text
+driver name
+stage
+state
+module memory range
+provided services
+recovery ops
+init result
+last fault
+```
+
+### 8.3 驱动 recovery ops
+
+驱动可注册：
+
+```c
+struct dkm_driver_recovery_ops {
+    int (*quiesce)(void *ctx);
+    int (*reset)(void *ctx);
+    int (*reinit)(void *ctx);
+    int (*dump_state)(void *ctx, void *buf, uint64_t len);
+};
+```
+
+DRR recovery 顺序：
+
+```text
+quiesce -> UTSM rollback -> device reset -> driver reinit -> resume
+```
+
+---
+
+## 9. 第一版定稿
+
+第一版驱动系统确定：
+
+```text
+1. SYSTEM 是 IMG 内系统根目录。
+2. 驱动清单为 SYSTEM/driver/manifest.json。
+3. 驱动文件为 ELF64 .drv。
+4. 驱动必须导出 driver_desc / driver_init / driver_exit。
+5. 驱动通过 dkm_kernel_api 调用内核服务。
+6. ELF loader 第一版支持常用 x86_64 relocation。
+7. 驱动按 stage 分阶段加载。
+8. stage0/stage1 支持 bootloader 预加载 boot module。
+9. stage2/stage3 从 SYSTEM/driver 加载。
+10. 驱动内存纳入 UTSM，驱动恢复纳入 DRR。
+```