novus文档手册

设备管理器（M12，devmgmt）

Novus OS 的 Windows 11 设备管理器复刻：主窗口是菜单栏 + 工具栏 + 左侧可折叠 设备树 + 状态栏；双击/右键"属性"打开一个独立的模态属性子窗口（常规 / 驱动程序 / 详细信息 / 事件 / 资源），版式完全对齐 Win11。所有信息来自内核在启动期归一化的 设备表，应用本身不扫硬件。

状态：随 M12 生效 适用范围：内核 kernel/devtab.{h,c}、kernel/sysinfo.{h,c}、kernel/usb.{h,c} 窗口管理器 wm/novus-wm/nwm.c 与 apps/src/wm.rs 应用 apps/src/devmgr/{mod,tree,props,fields}.rs、apps/src/bin/devmgmt.rs

1. 入口

设备管理器可从四个入口启动，全部走 apps_launch() 按名字解析（devmgmt）：

  1. 桌面右侧磁贴（与文件管理器/任务管理器/设置/网络/终端/安装并列，常驻）；
  2. 底部任务栏固定图标（含运行时强调色指示圆点）；
  3. 开始菜单"设备管理器"按钮；
  4. nsh 终端直接输入 devmgmt。

kernel/session.c 的 desktop_app() 白名单与 apps.c 应用表都已登记，未登录时 apps_launch() 同样拒绝普通桌面应用。设置面板的"应用"页也把它列入"可启动" （固定顺序：文件管理器/任务管理器/设置/设备管理器）。

2. 架构

kernel/devtab.c  ── 启动期建表（PCI 缓存 + blkdev/net/display/CPU/ACPI/USB/IOAPIC/PS2）
        │  devtab_count / devtab_at / devtab_field_count / devtab_field_at
kernel/sysinfo.c ── REQ_DEVLIST(0x031B) / REQ_DEVFIELD(0x031D)，128 B 分页
        │  IPC
apps/src/sinfo.rs ── devices() / dev_fields()
apps/src/devmgr/*  ── 主窗 + 设备树 + 模态属性窗
        │  wm::Win::create_ex(..., NWM_F_CREATE_MODAL) / next_event_any()
wm/novus-wm/nwm.c ── 120/160 显示列表预算、10 窗口、模态输入隔离

设计要点：

3. 协议契约

设备树节点（sysinfo_dev_t，40 B，3 条/包 = 4 + 120）：

字段 类型 说明
parent u16 父类别节点下标，0xFFFF 表示根
class_id u8 DEV_CAT_*（计算机/处理器/固件/显示/磁盘/存储控制器/网络/USB/输入/系统设备/未知）
status u8 DEV_STATUS_OK / DEV_STATUS_WARN（无驱动或未知设备）
kind u8 DEV_KIND_*（CPU/PCI/显卡/监视器/磁盘/网卡/USB 控制器/USB 设备/输入/系统/固件…）
idx u8 在所属子系统表中的下标（取 BAR/事件/扇区用）
flags u8 DEV_FLAG_REMOVABLE / DEV_FLAG_NODRV 等
name char[32] UTF-8 名称

属性字段（sysinfo_devfield_t，60 B，2 条/包 = 4 + 120）：

字段 类型 说明
key u8 DEV_F_*（制造商/位置/容量/MAC/链路/硬件 ID/状态/问题代码/内存范围/I/O 范围/IRQ/…）
group u8 事件行号或 BAR 序号（同一键多值时区分）
value char[56] UTF-8 值，过长截断

分页范式沿用 sysinfo_list_t：total 是整表/整 tab 数量，index 是起始项， n 是本次实际返回；客户端 index += n 直到到顶。

4. 主窗口

客户区 820×540，标题"设备管理器"，10 px 圆角 + 柔影，浅色主体。

键盘：↑/↓ 移动选中、Enter 打开属性、F5 刷新（重建设备表并关闭已开属性窗）、 Esc 取消菜单/浮层。

5. 模态属性窗口

客户区 520×600，标题"设备属性"，比主窗更高层级，打开时主窗不收输入。

只读边界：更新/回退/禁用/卸载等破坏性操作不做真实驱动变更，点击后仅在对话框内 显示说明行，界面完整、系统不损坏。

6. 窗口管理器支撑

7. 主题与双语

全部界面由 WM 图元（圆角填充/描边/文本）绘制，图标为程序化色块字形，不使用位图。 颜色随系统浅/深色与强调色联动（ui::init / ui::poll 监听主题版本）；标签中英双语 （ui::l(zh, en) 内联，未走 lang 字典）。

8. 构建与验证

NKM 内核模块二进制格式规范 V1.0

NKM 内核模块二进制格式规范

文档版本：V1.0（对应 Novus OS V1.6-FinalSpec） 适用对象：NKM 加载器开发者、驱动开发者、模块签名工具链开发者 平台：x86_64 UEFI 状态：格式冻结；哈希/签名规则已修复并固化，不得变更

1. 概述

NKM（Novus Kernel Module）是 Novus OS 的内核动态模块格式，扩展名 .nkm。 用途：驱动、文件系统扩展、Win32 兼容层、GPU DRM 驱动等可加载组件。

与 NUC（用户态程序）的本质区别：

维度 NUC（用户态） NKM（内核模块）
加载位置 用户虚拟地址空间 内核地址空间
权限 用户态页表，Ring3 内核页表，Ring0
签名 无要求 必须 Ed25519 签名
入口 entry_point 用户函数 nkm_init() + nkm_exit() 双入口
卸载 进程退出自动回收 需 nkm_unload 显式调用
访问范围 仅自己地址空间 可访问全部内核符号

2. 文件整体布局

偏移 0x0000 ┌──────────────────────────────┐
            │  NKM Header (nkm_hdr_t)      │   固定 208 字节
偏移 0x00D0 ├──────────────────────────────┤
            │  Module Dependencies         │   dep_count × nkm_dep_t (16B/条)
偏移 ...    ├──────────────────────────────┤
            │  Segment Table               │   seg_count × nkm_segment_t (32B/条)
偏移 ...    ├──────────────────────────────┤
            │  Symbol Table                │   sym_count × nkm_sym_t (24B/条)
偏移 ...    ├──────────────────────────────┤
            │  Relocation Table           │   rel_count × nkm_rel_t (16B/条)
偏移 ...    ├──────────────────────────────┤
            │  String Table               │
偏移 ...    ├──────────────────────────────┤
            │  段数据（.text/.data/.rodata）│   4KiB 对齐
            └──────────────────────────────┘

3. NKM Header（文件头）

固定长度 208 字节（0x00D0），位于文件偏移 0x0000，packed。

修订说明：本节原文写作「128 字节」，与 3.2 的字段偏移表矛盾——表中 reserved[32] 位于 0xB0，加 32 字节后头部实际结束于 0xD0；6.3 的 摘要规则（清零 0x50..0xB0）也只在 208 字节布局下成立。现按偏移表 统一为 208 字节，3.2 字段定义与 3.3 类型编号均未改动。

3.1 结构体定义

#define NKM_MAGIC 0x4E4B4D21   // "NKM!"

typedef struct __attribute__((packed)) {
    uint8_t  magic[4];           // 0x00  "NKM!" = 4E 4B 4D 21
    uint16_t abi_version;        // 0x04  bit[0..7]=minor, bit[8..15]=major
    uint16_t header_size;        // 0x06  = 208 (0xD0)，便于扩展
    uint64_t min_kernel_ver;     // 0x08  最低兼容内核版本
    uint32_t module_type;        // 0x10  模块类型（驱动/FS/兼容层...）
    uint16_t seg_count;           // 0x14  段数量
    uint16_t dep_count;           // 0x16  依赖模块数量
    uint32_t symtab_count;        // 0x18  符号数量
    uint32_t rel_count;           // 0x1C  重定位数量
    uint32_t strtab_offset;       // 0x20  字符串表偏移
    uint32_t rel_offset;          // 0x24  重定位表偏移
    uint32_t init_offset;         // 0x28  nkm_init() 在 .text 内偏移
    uint32_t exit_offset;         // 0x2C  nkm_exit() 在 .text 内偏移
    uint8_t  module_name[32];     // 0x30  模块名（'\0' 结尾）
    uint8_t  module_hash[32];     // 0x50  模块本体 SHA256（签名校验字段）
    uint8_t  module_sig[64];     // 0x70  Ed25519 签名
    uint8_t  reserved[0x20];      // 0xB0  预留 32 字节
} nkm_hdr_t;                        // 总大小 208 字节 (0xD0)

3.2 字段逐字节定义

偏移 大小 字段 取值规则
0x00 4 magic 固定 NKM!，不匹配拒绝加载
0x04 2 abi_version 高字节=major，低字节=minor。当前 0x0100
0x06 2 header_size 固定 208（0xD0），未来扩展用
0x08 8 min_kernel_ver 加载时校验 内核版本 >= min_kernel_ver
0x10 4 module_type 见 §3.3
0x14 2 seg_count 段数，1~16
0x16 2 dep_count 依赖模块数，0=无依赖
0x18 4 symtab_count 符号数量
0x1C 4 rel_count 重定位数量
0x20 4 strtab_offset 字符串表文件偏移
0x24 4 rel_offset 重定位表文件偏移
0x28 4 init_offset nkm_init() 在 .text 段内字节偏移
0x2C 4 exit_offset nkm_exit() 在 .text 段内字节偏移
0x30 32 module_name 模块名，\0 结尾，最长 31 字符
0x50 32 module_hash 模块本体 SHA256（见 §6）
0x70 64 module_sig Ed25519 签名（见 §6）
0xB0 32 reserved 必须全 0

3.3 module_type 取值

值 名称 说明
0 NKM_TYPE_DRIVER 硬件驱动（VGA/DP/存储/PCI）
1 NKM_TYPE_FS 文件系统驱动
2 NKM_TYPE_COMPAT 兼容层（Win32）
3 NKM_TYPE_CRYPTO 加密模块
4 NKM_TYPE_OTHER 其他扩展

4. 模块依赖表

紧接 Header 之后，共 dep_count 条，每条 16 字节。

typedef struct __attribute__((packed)) {
    uint32_t dep_name_off;      // 0x00  依赖模块名在 String Table 的偏移
    uint64_t min_dep_ver;       // 0x04  依赖模块最低版本
    uint32_t reserved;           // 0x0C  必须为 0
} nkm_dep_t;                     // 16 字节

加载规则：

  1. 加载器按依赖表顺序，先加载被依赖的模块；
  2. 依赖模块未加载 → 自动递归加载；
  3. 依赖模块版本不满足 min_dep_ver → 拒绝加载本模块；
  4. 依赖表出现循环依赖 → 拒绝加载，返回 NOVUS_EDEP。

5. 段表 / 符号表 / 重定位表

格式与 NUC 完全一致（见《NUC 二进制格式规范》第 4/5/7 节），差异点：

项 NKM 差异
段 vaddr 加载到内核地址空间（高地址区，非用户区）
段权限 全部 Ring0，不要求 VM_USER；TEXT 可执行，DATA 可写
外部符号 解析到内核导出符号表（nksym），而非系统 SDK
重定位类型 仅 R_X86_64_64（64 位绝对地址），内核模块不使用 PC32

内核导出符号示例（nksym 表，由内核 vmlinux 提供）：

mm_alloc, mm_free, vm_map, vm_unmap
sched_spawn, sched_exit
vfs_register_fs, vfs_read, vfs_write
hal_display_probe, hal_display_flush
cap_check, log_print, err_report
pci_enumerate, blk_read, blk_write

6. Ed25519 签名与哈希（核心，已冻结）

6.1 密码套件

6.2 内核公钥池

// 编译时固化在内核镜像中，运行时不可写、不可改
static const ed25519_pubkey_t kernel_trusted_keys[4] = {
    /* 公钥1 */, /* 公钥2 */, /* 公钥3 */, /* 公钥4 */
};
static const uint8_t trusted_key_count = 1; // 初始仅1把，后续版本追加

6.3 哈希计算范围（已修复冲突，冻结）

关键规则：SHA256 计算范围 = 整个模块文件，但跳过 module_hash[32] 和 module_sig[64] 两个字段。

具体操作（签名工具与加载器必须一致）：

1. 拷贝整个模块文件到内存 temp_buf
2. 将 temp_buf 中偏移 0x50 起共 96 字节（32+64）置 0
   —— 即把 module_hash 和 module_sig 两个字段清零
3. computed_hash = SHA256(temp_buf, 文件总长度)
4. 比对 computed_hash 与头部原始 module_hash：
     不一致 → 哈希校验失败，拒绝加载

6.4 签名验证流程

1. 计算出 computed_hash（同 §6.3）
2. 比对 computed_hash == nkm_hdr.module_hash
3. 取头部 module_sig（64 字节）作为 Ed25519 签名
4. 取 nkm_hdr.module_hash（32 字节）作为签名原文
5. 遍历 kernel_trusted_keys[]：
     if ed25519_verify(module_hash, module_sig, pubkey[i]):
         → 校验通过，跳出
6. 全部公钥校验失败 → 拒绝加载

6.5 为什么跳过 hash+sig 字段

如果哈希包含自身签名，会造成"鸡生蛋"问题：签名依赖哈希，哈希依赖签名字节。 置零后计算哈希，使哈希与签名解耦：哈希覆盖"除自描述字段外的全部内容"，签名再对这个哈希做签名。

7. 模块入口函数约定

每个 NKM 模块必须导出两个函数，通过 init_offset / exit_offset 指向：

// 模块初始化（加载时调用一次）
// 返回 0 成功，负数错误码
int nkm_init(void);

// 模块卸载（卸载时调用一次）
// 返回 0 成功
int nkm_exit(void);

调用约定：

8. 加载完整流程（冻结）

1. nkm_load(path) 被调用
2. 校验调用者 cap_check(mod.load)，无权限 → NOVUS_EPERM
3. VFS 打开文件，读取前 208 字节（Header）
4. 校验 magic == "NKM!"
5. 校验 abi_version 主版本号
6. 校验 min_kernel_ver <= 当前内核版本
7. 拷贝整个文件到内核内存
8. 执行哈希校验：
   a. 临时副本中 0x50..0xB0 置 0
   b. 计算 SHA256
   c. 与 module_hash 比对
   失败 → NOVUS_ECORRUPT
9. 执行 Ed25519 签名校验（轮询公钥池）
   失败 → NOVUS_EMODULE
   （管理员单次临时放行：跳过第 9 步，打警告日志）
10. 按依赖表递归加载依赖模块
11. 映射段到内核地址空间
12. 解析重定位（外部符号查内核 nksym 表）
13. 调用 nkm_init()
14. init 返回 0 → 注册到模块列表，返回成功
15. init 失败 → 回滚段映射，返回错误

9. 卸载流程

1. nkm_unload(name) 被调用
2. 校验 cap_check(mod.unload)
3. 检查模块是否被其他模块依赖（dep_count 反向引用）
   被依赖 → 拒绝卸载，NOVUS_EBUSY
4. 调用 nkm_exit()
5. 解除段映射
6. 从模块列表移除
7. 释放模块内存

10. 管理员临时放行策略

11. 错误码

错误码 含义
NOVUS_OK (0) 加载成功
NOVUS_EPERM (-4) 无 mod.load / mod.unload CAP
NOVUS_EINVAL (-1) 头部字段非法
NOVUS_ECORRUPT (-7) SHA256 哈希不匹配
NOVUS_EMODULE (-8) Ed25519 签名验证失败
NOVUS_EBUSY (-5) 模块被依赖，无法卸载
NOVUS_ENOTFOUND (-3) 依赖模块缺失
NOVUS_EDEP (-12) 循环依赖
NOVUS_EIO (-6) 文件读取失败
NOVUS_ENOMEM (-2) 内核内存不足

12. 完整示例：一个最小驱动模块

12.1 Header 关键字段

magic:          4E 4B 4D 21  ("NKM!")
abi_version:    00 01        (major=1, minor=0)
header_size:    D0 00        (208)
min_kernel_ver: 00 00 00 00 00 00 00 01   (要求内核 >= 1.0)
module_type:    00 00 00 00  (DRIVER)
seg_count:      02 00         (2段)
dep_count:      00 00         (无依赖)
symtab_count:   01 00 00 00
rel_count:      02 00 00 00
strtab_offset:  00 02 00 00   (0x200)
rel_offset:     C0 01 00 00   (0x1C0)
init_offset:    10 00 00 00   (.text+0x10)
exit_offset:    30 00 00 00   (.text+0x30)
module_name:    "nvme.ko" 00 00...
module_hash:    <32字节SHA256>
module_sig:     <64字节Ed25519签名>

12.2 模块源码骨架（C）

#include <novus/nkm.h>
#include <novus/mm.h>
#include <novus/log.h>

static void* buf = NULL;

int nkm_init(void)
{
    log_print(LOG_INFO, "nvme driver init\n");
    buf = mm_alloc(1);
    if (!buf) return NOVUS_ENOMEM;
    // 注册 NVMe 控制器
    return NOVUS_OK;
}

int nkm_exit(void)
{
    log_print(LOG_INFO, "nvme driver exit\n");
    if (buf) mm_free(buf, 1);
    return NOVUS_OK;
}

NUC 与 NKM 是不同格式：cppcc 只生成用户态 .nuc，不参与 NKM 目标文件编译或签名。 当前仓库的 tools/nkmgen 是主机端 NKM 测试镜像生成器，复用内核 Ed25519/SHA 实现生成并签名测试模块；它不是通用 C/C++ NKM 编译器。通用驱动目标文件到 NKM 的生产工具链不属于 cppcc。

13. 文档冻结声明

本规范为 NKM 内核模块格式唯一基准文档。约束：

任何变更必须走 ABI 变更 RFC，升版本号。

文档状态： 可作为 M3（NKM 加载器）与 M10（驱动生态）的实现基准。

Novus OS Debug 级接口手册 V1.0

Novus OS Debug 级接口手册

文档版本：V1.0（对应 Novus OS V1.6-FinalSpec） 用途：开发调试手册，每个接口展开到参数级、错误码级、前置/后置条件、调试检查点 配套：《全部接口总表》《NUC 格式规范》《NKM 格式规范》 状态：冻结

0. 阅读指南

每个接口条目包含：

  1. 原型：C 函数签名
  2. 所属子系统
  3. 调用方 / 被调用方
  4. 前置条件：调用前必须满足什么（锁、CAP、中断状态、内存）
  5. 参数表：逐字段类型、取值范围、单位、默认值、说明
  6. 返回值：逐情况说明
  7. 错误码对照表：什么情况返回什么错误码
  8. 后置条件：返回后系统状态变化
  9. 调试检查点：开发时应该打日志/断言的位置
  10. 使用示例：最小调用代码
  11. 常见 Bug：易犯错误

1. 通用错误码（全局复用）

值 宏名 含义 触发场景举例
0 NOVUS_OK 成功 一切正常
-1 NOVUS_EINVAL 参数无效 指针为NULL、长度为0、枚举值越界
-2 NOVUS_ENOMEM 内存不足 页分配失败、缓冲区不够
-3 NOVUS_ENOTFOUND 对象不存在 路径不存在、符号未找到、设备不存在
-4 NOVUS_EPERM 权限不足 cap_check() 返回 false
-5 NOVUS_EBUSY 资源忙 锁超时、文件被占用、模块被依赖
-6 NOVUS_EIO IO错误 磁盘读失败、PCI读写错误
-7 NOVUS_ECORRUPT 数据损坏 SHA256不匹配、CRC32校验失败
-8 NOVUS_EMODULE 模块错误 签名校验失败、ABI不兼容
-9 NOVUS_EFULL 队列满 IPC队列满、WAL日志满
-10 NOVUS_EAGAIN 重试 资源暂时不可用
-11 NOVUS_EOVERFLOW 溢出 段大小越界、文件偏移超出文件长度
-12 NOVUS_EDEP 循环依赖 模块依赖图成环

2. SMP / AB 双核接口

2.1 smp_shmem_write

void smp_shmem_write(uint32_t offset, uint64_t val);
参数 类型 范围 说明
offset uint32_t 0 ~ 4095 共享内存内偏移，必须 8 字节对齐
val uint64_t 任意 要写入的值

2.2 smp_shmem_read

uint64_t smp_shmem_read(uint32_t offset);

2.3 smp_shmem_lock / smp_shmem_unlock

int smp_shmem_lock(void);
void smp_shmem_unlock(void);

2.4 acore_enter_sleep

void acore_enter_sleep(void);

2.5 smp_wake_ap

int smp_wake_ap(uint64_t ap_id);

2.6 smp_ap_signal_ready

void smp_ap_signal_ready(void);

3. 内存管理接口

3.1 mm_alloc

void* mm_alloc(size_t pages);
参数 类型 单位 说明
pages size_t 4KiB/页 要分配的连续物理页数

3.2 mm_free

void mm_free(void* vaddr, size_t pages);

3.3 vm_map

int vm_map(uint64_t va, uint64_t pa, uint64_t len, uint32_t flags);
参数 类型 单位 说明
va uint64_t 字节 虚拟起始地址，4KiB 对齐
pa uint64_t 字节 物理起始地址，4KiB 对齐
len uint64_t 字节 长度，4KiB 对齐
flags uint32_t 位掩码 bit0=READ bit1=WRITE bit2=EXEC bit3=USER

3.4 vm_unmap

int vm_unmap(uint64_t va, uint64_t len);

3.5 oom_scan

int oom_scan(proc_info_t* out);

3.6 oom_reclaim

int oom_reclaim(uint32_t level);

4. 调度器接口

4.1 sched_spawn

int sched_spawn(const char* path, uint64_t caps, pid_t* out_pid);
参数 说明
path .nuc 文件路径，如 "/system/bin/novus-settings"
caps 进程初始 CAP 掩码（低64位）
out_pid 输出参数，成功写入新 PID

4.2 sched_ctl

int sched_ctl(pid_t pid, uint32_t op, void* arg);

4.3 sched_exception_report

int sched_exception_report(pid_t pid, exc_info_t* exc);

typedef struct {
    uint64_t pid;
    uint64_t rip;        // 出错指令地址
    uint64_t cr2;        // 页错误地址
    uint32_t err_code;   // 错误码
    char proc_name[64];
    uint8_t  cause;      // 0=页错误 1=非法指令 2=除零 3=断点
} exc_info_t;

5. 安全/CAP 接口

5.1 cap_check

int cap_check(proc_cap_t* p, uint32_t bit);

5.2 cap_drop

int cap_drop(proc_cap_t* p, uint32_t bit);

5.3 nkm_load

int nkm_load(const char* path);

6. VFS 接口

6.1 vfs_open

int vfs_open(const char* path, uint32_t flags, uint32_t mode);

6.2 vfs_read / vfs_write

int vfs_read(int fd, void* buf, uint64_t len);
int vfs_write(int fd, const void* buf, uint64_t len);

7. NovusFS 接口

7.1 novusfs_alloc_block

int novusfs_alloc_block(uint64_t* out_block);

7.2 WAL 事务

wal_begin_tx

int wal_begin_tx(uint32_t type, uint64_t block_no, wal_tx_t* out);

wal_commit

int wal_commit(wal_tx_t* tx, const void* data, uint32_t len);

wal_rollback

void wal_rollback(wal_tx_t* tx);

WAL 满判定

// 满条件：write_ptr == tail_ptr
if (wal_write_ptr == wal_tail_ptr) {
    // 推进 tail 到下一个完整事务边界
    wal_advance_tail();
}

8. Merkle 树接口

8.1 merkle_verify_root

int merkle_verify_root(dev_t dev, const uint8_t expect[32]);

8.2 节点磁盘映射

// idx: 节点索引（根=1）
uint64_t node_to_block(uint64_t idx) {
    return merkle_start_block + (idx / 64);
}
uint64_t node_offset_in_block(uint64_t idx) {
    return (idx % 64) * 64;
}

9. 图形栈系统调用

9.1 sys_gfx_create_surface

int sys_gfx_create_surface(uint32_t w, uint32_t h, uint32_t fmt, fb_handle_t* out);

9.2 sys_gfx_submit_dirty

int sys_gfx_submit_dirty(fb_handle_t h, const rect_t* rects, uint32_t n);

10. IPC 接口

10.1 ipc_send

int ipc_send(novus_ipc_hdr_t* hdr, const void* payload);

11. 系统调用 ABI（debug 要点）

11.1 寄存器约定

用途 寄存器
调用号 rax
参数1 rdi
参数2 rsi
参数3 rdx
参数4 rcx
参数5 r8
参数6 r9
返回值 rax
被调用者保存 rbp, rbx, r12, r13, r14, r15

11.2 常见调试技巧

  1. 系统调用号打印：在 syscall 入口打印 rax 和参数
  2. 返回值检查：用户态库包装后检查 rax 是否为负
  3. 栈对齐：进入内核时检查 rsp % 16 == 0
  4. 权限拒绝：syscall 入口先 cap_check，拒绝时打印 bit 号

12. 日志接口

12.1 log_print

void log_print(uint32_t level, const char* fmt, ...);

12.2 panic_handler

void panic_handler(cpu_state_t* state);

13. 调试通用建议

13.1 打印策略

13.2 断言

13.3 常见 Bug 清单

  1. 忘记持锁 → 多进程竞态
  2. 锁顺序错误 → 死锁（必须按 超级块→目录→inode→块分配）
  3. 双重释放 → 内存 corruption
  4. 偏移未对齐 → x86_64 严格对齐异常
  5. CAP 忘记检查 → 越权访问
  6. WAL 写了 PREP 没写 COMMIT → 崩溃后数据丢失
  7. Merkle 哈希包含了自身 hash 字段 → 校验永远失败
  8. NKM 签名时公钥不匹配 → 模块无法加载

文档状态

本文档为 Debug 级接口手册，开发时对照此文档逐行检查代码。 所有函数签名、参数、错误码、前置条件已冻结。

文档状态：✅ 冻结，可作为 M0–M10 开发调试基准。

Novus OS 自研分级增量更新体系完整规范

1. Novus OS 自研更新架构核心体系

Novus OS 搭载完全自研、独立可控、工业级稳定的分类补丁、分级推送、分通道灰度、断点续传、事务原子回滚、服务端统一管控更新体系，专为自研操作系统量身设计，架构轻量化、逻辑透明、可手动调试、可全自动批量部署，为系统长期迭代、安全风控、软件运维提供标准化底层支撑。

1.1 Novus OS 三大官方补丁体系（永久冻结）

1.2 Novus OS 五级官方更新推送通道（永久冻结）

系统内置自研五级更新分级机制，覆盖从紧急安全修复、稳定版本推送、灰度功能预览、普通可选更新、开发者内测更新全场景，分级策略独立、权限隔离、互不干扰，适配普通用户、进阶用户、开发者、企业批量运维全群体需求：

  1. 紧急安全推送（level_urgent）：专属安全漏洞热修复，系统最高优先级，无拦截、无延后、强制即时修复

  2. 稳定推荐推送（level_recommend）：系统与软件稳定版迭代更新，默认推荐安装，保障设备稳定性与兼容性

  3. 版本预览推送（level_preview）：新功能灰度尝鲜版本，仅主动查询可见，无被动弹窗推送

  4. 普通可选推送（level_optional）：非必要体验优化、辅助功能迭代，用户自主选择安装或忽略

  5. 开发者内测推送（level_dev）：开发调试版、未稳定内测版本，默认隐藏，仅开发者模式解锁可见

2. Novus OS 自研更新核心机制与技术规范

2.1 服务端核心：全局唯一统一更新大表架构

Novus OS 远程更新服务端采用自研单全局唯一更新索引大表架构，为所有终端设备更新的唯一权威数据源，摒弃分散分表的复杂设计，架构极简、检索高效、运维便捷。

核心运行逻辑：

2.2 客户端核心：分层优先级更新队列机制（冻结）

系统内置固定优先级更新队列，多补丁同时存在时，严格按照既定优先级串行执行，避免更新冲突、资源抢占、版本错乱问题。

更新执行优先级（从高至低，永久冻结）：

.hotpth 紧急安全热修复 > .npth 系统累积更新 > .apth 关键软件更新 > 预览版灰度更新 > 普通可选更新 > Dev开发者内测更新

2.3 自研事务性原子更新与智能回滚机制

2.4 自研差分增量更新与断点续传机制

7. Novus OS 更新体系二进制文件头规范（全局冻结｜可直接编码）

本节定义 .novu / .npth / .apth / .hotpth 四类更新载体的统一二进制文件头结构。所有结构体强制 packed、4字节对齐、字段偏移永久锁定，用于解析器精准识别文件类型、校验合法性、读取更新策略，杜绝后缀伪造、文件篡改、格式错乱。

核心设计原则：后缀与文件头魔数强绑定、类型字段二次校验、标志位控制行为、全局哈希防篡改、预留位保证向前兼容。

7.1 全局公共定义（全部文件通用｜冻结）

// 全局版本冻结
#define NOVUS_UPDATE_HDR_VER_MAJOR 1
#define NOVUS_UPDATE_HDR_VER_MINOR 0

// 文件类型枚举（永久唯一）
#define NOVU_TYPE_FULL       0   // .novu 全量安装包
#define NOVU_TYPE_SYS_PATCH  1   // .npth 系统通用补丁
#define NOVU_TYPE_APP_PATCH  2   // .apth 软件专属补丁
#define NOVU_TYPE_HOT_PATCH  3   // .hotpth 紧急热修复补丁

// 五级更新分级枚举（绑定服务端大表策略）
#define UPDATE_LVL_OPTIONAL    0
#define UPDATE_LVL_RECOMMEND   1
#define UPDATE_LVL_PREVIEW     2
#define UPDATE_LVL_URGENT      3
#define UPDATE_LVL_DEV         4

7.2 四类文件专属魔数（防伪造｜一一对应｜冻结）

文件头魔数为第一校验依据，后缀仅为系统展示用，解析器以魔数为准，防止手动改后缀伪装补丁。

// 小端内存序、文件存储序统一
#define NOVU_FULL_MAGIC    0x554E5653  // NVUS → .novu
#define NOVU_NPTH_MAGIC    0x50544853  // PTHS → .npth
#define NOVU_APTH_MAGIC    0x41505448  // APTH → .apth
#define NOVU_HOTPTH_MAGIC  0x484F5450  // HOTP → .hotpth

7.3 统一标准文件头结构体（128Byte 固定｜四类文件通用）

四类更新文件共用同一套128字节头部布局，仅 magic、file_type、默认 update_level 不同，极大降低解析器代码冗余，同时严格隔离四类载体行为。

typedef struct __attribute__((packed)) {
    // 0x00 基础魔数与版本
    uint32_t magic;               // 四类文件专属魔数
    uint16_t ver_major;
    uint16_t ver_minor;

    // 0x08 文件类型 + 更新分级
    uint8_t  file_type;           // 0=novu 1=npth 2=apth 3=hotpth
    uint8_t  update_level;        // 0~4 对应五级更新通道
    uint8_t  remote_support;      // 1=允许远程下发 0=仅本地手动安装
    uint8_t  reserved_0;

    // 0x0C 全局标志位（位掩码控制更新行为）
    uint32_t flag_bits;

    // 0x10 版本适配区间
    uint64_t target_os_ver;       // 目标适配系统版本
    uint64_t min_compat_ver;      // 最低兼容兜底版本

    // 0x20 内容块计数
    uint32_t entry_count;         // 文件操作项/资源项总数
    uint32_t delta_block_count;   // 差分块数量（全量包可为0）

    // 0x28 各区块文件偏移与长度
    uint32_t meta_offset;         // 元数据/Manifest 偏移
    uint32_t meta_len;
    uint32_t table_offset;        // 操作表/索引表偏移
    uint32_t table_len;
    uint32_t data_offset;         // 原始数据/差分数据区偏移
    uint32_t data_len;
    uint32_t snapshot_offset;     // 快照回滚哈希表偏移
    uint32_t snapshot_len;

    // 0x60 全局完整性校验
    uint8_t  file_sha256[32];     // 整包除签名区外哈希

    // 0x80 签名信息
    uint32_t sig_offset;
    uint32_t sig_len;

    // 0x88 补丁唯一ID（16位十六进制ID二进制存储）
    uint8_t  patch_uuid_bin[8];   

    // 0x90 预留填充至128字节，向前兼容扩展
    uint8_t  reserved_fill[24];
} novus_update_header_t;

7.4 全局 Flag 位掩码定义（冻结）

统一位掩码控制各类更新行为，客户端/服务端按位判定策略。

bit0  = 1 开启快照回滚
bit1  = 1 差分增量模式 / 0 全量替换模式
bit2  = 1 支持断点续传
bit3  = 1 支持内核热更新（无需重启）
bit4  = 1 允许覆盖系统只读路径
bit5  = 1 更新后自动刷新桌面/服务
bit6  = 1 远程静默安装模式
bit7  = 1 安全紧急强制兜底模式
bit8~31 保留

7.5 四类文件头部字段差异化绑定规则（永久冻结）

统一结构体 + 差异化固化参数，保证格式统一、行为隔离、层级严谨。

文件后缀 Magic file_type 默认 update_level 核心行为固化
.novu 全量包 NVUS 0 1（推荐级） 大版本替换、支持回滚、仅重大迭代使用
.npth 系统补丁 PTHS 1 1（推荐级） 系统核心迭代、后台执行、可延后次数管控
.apth 软件补丁 APTH 2 0（可选级） 用户态更新、弹窗询问、可永久忽略
.hotpth 热修复 HOTP 3 3（紧急级） 最高优先级、静默强制、禁止延后、插队执行

7.6 16进制补丁UUID 二进制存储规范

对外文件名：16位大写十六进制字符串

对内文件头：8字节原生二进制存储（16Hex = 64bit）

校验逻辑双向绑定冻结：

  1. 打包器由SHA256摘要截取前64bit生成唯一ID

  2. 写入头部 patch_uuid_bin[8]

  3. 同时格式化输出16位大写Hex作为文件名

  4. 解析器校验：文件名Hex <-> 头部二进制ID 必须一致，不一致直接拒绝安装，判定为非法篡改包

7.7 头部合法性校验流水线（硬件级可靠｜冻结流程）

客户端/服务端接收任意更新文件，严格按以下顺序校验，任意一步失败直接丢弃：

  1. 校验前128字节头部完整性

  2. 匹配对应魔数，判定真实文件类型

  3. 校验主次版本兼容

  4. 校验二进制UUID与文件名一致性

  5. 校验系统版本适配区间

  6. 校验全局SHA256完整性

  7. 校验Ed25519数字签名合法性

  8. 通过后按 update_level 进入对应更新队列

7.8 区块偏移通用排布规则（四类文件统一）

所有更新文件从偏移0开始排布顺序永久固定：

128B文件头 → Meta元数据区 → 文件操作索引表 → 差分数据表 → 数据正文区 → 快照哈希区 → 签名区

保证解析器线性读取、无需自适应判断，极致降低解析复杂度与BUG率。

3. Novus OS 自研更新体系增强策略规范

基于自研架构迭代优化，新增多项工业级增强策略，完善全场景更新能力，所有扩展规则兼容原有冻结底层结构，无破坏性变更。

3.1 智能空闲时段静默更新策略

为兼顾更新时效性与用户使用体验，自研分时更新调度机制：

3.2 更新失败智能重试与设备自愈降级策略

3.3 设备维度精细化灰度放量机制

服务端统一大表内置完整灰度管控逻辑，支撑版本平稳迭代：

3.4 系统后台驻留更新服务（完整后台能力闭环）

Novus OS 更新体系内置系统级常驻后台更新守护服务，独立于前台UI、独立生命周期、低功耗驻留系统内核服务层。所有更新检测、版本比对、下载预载、静默安装、状态同步、撤回预处理全部支持后台无感知运行，支持前台退出、锁屏待机、用户离线状态下持续完成更新全流程。

3.4.1 后台服务核心属性（系统常驻级）

3.4.2 后台完整可执行能力清单

所有更新核心逻辑完全后台化，无需前台介入：

3.4.3 后台任务场景适配规则

3.4.4 后台权限与安全隔离机制

3.4.5 后台与五级更新分级联动策略

3.5 更新撤回与卸载回滚子系统（工业级完整闭环）

3.5 更新撤回与卸载回滚子系统（工业级完整闭环）

Novus OS 原生支持已完成更新的可逆撤回能力，支持所有增量补丁与小版本迭代更新一键卸载、还原更新前状态、自动清理更新残留、恢复原始文件权限与注册表配置，适配用户误更新、版本兼容异常、功能迭代不适配等场景，形成「更新-生效-撤回-复原」完整闭环。

本机制为系统原生底层能力，无需重装系统、不丢失用户数据、不破坏应用环境，区分「可撤回更新」与「永久固化更新」，权限分级可控、日志全程溯源。

3.5.1 撤回适用范围界定（永久冻结规则）

四类更新载体撤回权限差异化管控：

3.5.2 更新快照增量存档机制（撤回核心底层）

系统摒弃全量备份冗余方案，采用增量快照存档，仅备份更新被修改、替换、删除的原始文件与配置，节省磁盘空间同时保证100%可复原：

3.5.3 系统更新索引注册表（撤回溯源核心）

系统内置专属更新索引数据库，记录每一条已安装更新的完整元数据，为撤回功能提供精准索引：

单条更新索引固定字段：

所有已安装更新在系统更新列表可视化展示，支持按时间、类型、版本筛选，用户可自主选择指定更新单独撤回，支持精准单条回滚、不影响后续其他更新。

3.5.4 分层撤回执行流程（原子事务级冻结）

撤回操作全程事务化，遵循「要么完全撤回、要么原样保留」的原子原则，杜绝半撤回异常状态：

  1. 前置校验：校验补丁合法性、快照完整性、当前系统基线匹配度，检测是否存在依赖后置更新

  2. 依赖检测：若当前更新被后续高阶更新依赖，弹窗提示依赖关系，支持「连带撤回后续增量更新」或「禁止单独撤回」

  3. 文件复原：依据增量快照覆盖还原原始文件、恢复权限、修复目录结构

  4. 配置回滚：还原系统服务项、开机自启、环境变量、应用配置旧状态

  5. 残留清理：自动删除本次更新新增冗余文件、无效注册表项、废弃差分缓存

  6. 状态刷新：静默刷新系统核心服务、桌面环境、应用挂载状态，无需冗余重启（内核级变更按需提示重启）

  7. 日志归档：记录撤回时间、操作主体、回滚结果，同步更新索引数据库状态

3.5.5 特殊锁定与豁免策略

3.5.6 服务端同步撤回策略

3.5.7 撤回能力差异化总表

补丁类型 可用户撤回 可自动自愈回滚 快照保留周期 依赖联动策略
.hotpth 紧急热修复 否（锁定保护） 是（故障自愈） 永久保留 禁止单独回滚，保障安全基线
.npth 系统累积补丁 是（非基线版） 是 30天 检测后续依赖，支持连带回滚
.apth 软件补丁 是（完全开放） 是 30天 独立应用隔离，无系统依赖
.novu 全量版本包 是（大版本回退） 是 60天 整体基线还原，清空增量迭代记录

3.4 稳定版更新延后管控策略

4. Novus OS 自研更新体系能力总览表

系统能力模块 Novus OS 自研实现方案 能力状态
紧急安全漏洞修复 .hotpth 最高优先级静默热修复体系 已完全落地冻结
系统核心累积迭代 .npth 系统通用增量补丁体系 已完全落地冻结
用户软件独立更新 .apth 应用软件专属增量补丁体系 已完全落地冻结
系统大版本升级 .novu 全量安装包兜底方案 已完全落地冻结
远程统一更新管控 全局唯一大表 + 客户端后台轮询架构 已完全落地冻结
五级精细化更新分级 紧急/推荐/预览/可选/开发 全通道体系 已完全落地冻结
字节级增量差分更新 自研Delta差分数据块更新机制 已完全落地冻结
原子更新与事务回滚 快照备份+全自动异常回滚体系 已完全落地冻结
断点续传续更能力 下载与安装进度持久化机制 已完全落地冻结
智能时段调度更新 空闲识别+免打扰时段自定义策略 待编码落地
精细化灰度推送管控 设备维度百分比放量+白名单机制 已支持
更新失败自愈与重试 梯度重试+设备兼容拉黑+日志上报闭环 待编码落地

5. Novus OS 自研更新体系定位总结

Novus OS 更新体系为100%纯自研、完全独立知识产权、工业级稳定的操作系统原生更新架构，无任何第三方架构依赖，完全适配自研系统生态：

  1. 搭建了独有的「三类补丁格式+五级更新通道」分层更新模型，精准区分安全修复、系统迭代、软件更新场景，权责隔离、层级清晰。

  2. 采用轻量化服务端大表管控+客户端极简执行架构，兼顾批量运维效率与终端系统稳定性。

  3. 融合自研差分增量、原子事务回滚、断点续更、智能调度、灰度自愈核心能力，形成安全、高效、可控、可调试的完整更新生态闭环。

6. 后续开发落地清单