Deshab-OS/CODE/UTSM/README.md

// 编译到 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 可选
```