273 lines
10 KiB
Markdown
273 lines
10 KiB
Markdown
# Kernel Design Guide
|
||
|
||
本文档记录 Tianole 当前阶段的顶层内核设计约束。它不是最终架构说明，也不是 Linux 的缩小版；它的作用是让后续实现不再只围绕单个文件局部修补，而是先确认子系统边界、调用方向和生命周期规则。
|
||
|
||
当代码改动影响目录职责、公共结构体、跨子系统 API、锁语义、生命周期或启动阶段顺序时，应该同步更新本文档或对应任务文档。
|
||
|
||
## 设计原则
|
||
|
||
- 参考 Linux 的分层和长期演进方式，但不照搬 Linux 的历史复杂度。
|
||
- 入口代码只编排流程，不承载具体策略。
|
||
- 子系统通过明确 API 交互，不直接访问对方内部结构。
|
||
- 公共结构体越少越好；公共头文件暴露的是契约，不是临时实现细节。
|
||
- 当前可以是单 CPU、单地址空间、简单调度，但接口不能把这些简化写成永久事实。
|
||
- 能力先闭环，再收紧边界；收紧边界时要补文档和自测。
|
||
|
||
## 顶层目录职责
|
||
|
||
- `arch/`：架构相关代码，包括启动入口、GDT/TSS/IDT、trap/IRQ entry、上下文切换、架构 timer、页表格式、TLB 和 CPU 指令封装。
|
||
- `kernel/`：架构无关的核心内核逻辑，包括 early log 前端、panic、IRQ 分发、调度、锁、时间抽象、进程和 syscall 的长期位置。
|
||
- `mm/`：架构无关内存管理，包括物理页、heap、后续 page metadata、buddy/slab、VMA、page cache 和回收。
|
||
- `drivers/`：设备驱动和设备模型，包括 input、block、PCI、ACPI、platform、GPU、network、sound 等。
|
||
- `block/`：通用块层。具体硬件驱动在 `drivers/`，块请求调度和块设备抽象在 `block/`。
|
||
- `fs/`：VFS 和具体文件系统。VFS 不依赖 shell、ELF loader 或具体块设备。
|
||
- `include/tianole/`：架构无关公共内核 API。只有跨子系统调用方真正需要的类型和函数才能放这里。
|
||
- `arch/<arch>/include/`：架构公开 API，例如中断控制、I/O port、上下文切换声明。
|
||
- `kernel/selftest/`：启动阶段自测和当前阶段演示线程，不放进具体实现目录。
|
||
- `scripts/`：构建、检查、QEMU 启动和结构规则工具。
|
||
- `docs/`：面向人的设计、路线和约束文档。
|
||
|
||
## 调用方向
|
||
|
||
允许的主要调用方向：
|
||
|
||
- `kernel/` 可以调用 `arch_` 前缀的架构 API。
|
||
- `kernel/` 可以调用 `mm/` 提供的分配和映射 API。
|
||
- `drivers/` 可以调用 IRQ、timer、wait queue、workqueue、MM 和 bus/resource API。
|
||
- `fs/` 可以调用 `mm/`、`block/` 和锁/等待 API。
|
||
- `user/` 或 `usr/` 里的用户程序只能通过 syscall/libc/VFS 暴露的接口进入 kernel。
|
||
|
||
禁止或需要重新设计的调用方向：
|
||
|
||
- 通用层不能直接读取 x86 页表编码、PIC/PIT 端口或 IDT gate 格式。
|
||
- 驱动不能直接调用 shell、VFS 内部对象或调度器内部链表。
|
||
- shell 和用户态工具不能包含 kernel 私有头或读取 kernel 内部结构体。
|
||
- 文件系统不能直接控制具体磁盘硬件。
|
||
- keyboard/input driver 不能直接操作 terminal 或 shell。
|
||
- boot/selftest 代码不能混进核心实现文件。
|
||
|
||
## 公共头文件规则
|
||
|
||
`include/tianole/` 只能放公共契约：
|
||
|
||
- 跨子系统需要调用的函数声明。
|
||
- 调用方必须知道的 opaque handle 或稳定结构。
|
||
- 明确属于公共 ABI 的枚举、flag 和错误码。
|
||
|
||
避免放入公共头文件：
|
||
|
||
- 只被一个子系统内部使用的字段。
|
||
- 具体链表节点、缓存节点、临时统计字段。
|
||
- 架构私有 bit 编码和寄存器布局。
|
||
- 调试或 selftest 专用结构。
|
||
|
||
如果公共结构体开始泄漏太多内部字段，优先考虑：
|
||
|
||
- 把结构改成 opaque。
|
||
- 拆出私有头，例如 `kernel/sched/sched.h`。
|
||
- 提供 accessor 或 helper，而不是让调用方直接改字段。
|
||
|
||
当前允许的阶段性妥协：
|
||
|
||
- `struct thread` 和 `struct wait_queue` 仍在公共头中暴露，方便早期调度和自测推进。
|
||
- 后续收紧调度状态机时，应逐步减少外部直接写 `thread->state`、`wait_next`、`next` 等字段。
|
||
|
||
## 启动阶段边界
|
||
|
||
启动路径按阶段推进：
|
||
|
||
1. bootloader 收集 boot info、memory map、kernel image。
|
||
2. kernel entry 建立最小运行环境。
|
||
3. early log 和 panic 可用。
|
||
4. trap/IRQ 基础可用。
|
||
5. MM 基础可用：物理页、页表、heap。
|
||
6. timer、thread、scheduler、wait queue 可用。
|
||
7. input、VFS、user mode、drivers 逐步接入。
|
||
|
||
启动阶段约束：
|
||
|
||
- early log/panic 不能依赖 heap、scheduler 或 VFS。
|
||
- trap/IRQ 初始化不能依赖复杂驱动模型。
|
||
- MM 初始化前不能使用 `kmalloc()`。
|
||
- scheduler 初始化前不能 sleep 或 wait。
|
||
- 驱动初始化不能假设 shell、VFS 或用户态已经存在。
|
||
|
||
## 中断、锁和 deferred work
|
||
|
||
中断路径分层：
|
||
|
||
- arch entry 保存现场并进入 C trap/IRQ 分发。
|
||
- IRQ core 根据 IRQ number 调用注册 handler。
|
||
- 具体设备 handler 做最短路径工作。
|
||
- 复杂处理应推迟到 deferred work、workqueue 或线程上下文。
|
||
|
||
锁规则：
|
||
|
||
- 中断和普通内核路径共享的数据，先使用 `spin_lock_irqsave()` 建立单 CPU 正确语义。
|
||
- 持有不可睡眠锁时不能调用 `sched_yield()`、`sched_sleep()` 或 wait queue sleep。
|
||
- 可睡眠路径和不可睡眠路径要从 API 命名、文档或调用约束上区分。
|
||
- 后续 SMP 前，需要把当前单 CPU lock 语义整理成可扩展接口。
|
||
|
||
等待规则：
|
||
|
||
- wait queue 负责“入队、睡眠、唤醒”的同步边界。
|
||
- 条件等待遵循“检查条件、入队睡眠、醒后重新检查”的模式。
|
||
- 唤醒方先修改受保护条件，再调用 wakeup。
|
||
- 条件所属数据如果不在 wait queue 内部，必须明确由哪把锁保护。
|
||
|
||
## 调度与线程生命周期
|
||
|
||
调度子系统职责：
|
||
|
||
- run queue 维护。
|
||
- 当前线程选择和上下文切换。
|
||
- thread state 转换。
|
||
- sleep/wakeup 和 wait queue 交互。
|
||
- DEAD/ZOMBIE 线程的安全回收。
|
||
|
||
调度状态机应逐步收紧：
|
||
|
||
- `READY -> RUNNING -> READY`
|
||
- `RUNNING -> SLEEPING/WAITING`
|
||
- `SLEEPING/WAITING -> READY`
|
||
- `RUNNING -> DEAD`
|
||
- 未来加入 `ZOMBIE` 支撑 join/wait 和进程退出。
|
||
|
||
约束：
|
||
|
||
- 外部子系统不应直接修改 run queue。
|
||
- 外部子系统不应长期直接写 `thread->state`。
|
||
- 当前线程不能释放自身内核栈。
|
||
- 线程入口返回必须进入统一 exit 路径。
|
||
- IRQ 中不直接做完整线程切换；调度请求应在明确的 interrupt-exit 边界消费。
|
||
|
||
## 内存、VFS 和缓存边界
|
||
|
||
MM 层负责：
|
||
|
||
- boot memory map 转换成内核长期内存区域模型。
|
||
- 物理页分配和 page metadata。
|
||
- 内核 heap 和后续 slab/slub。
|
||
- 用户地址空间、VMA、page fault 策略。
|
||
- page cache 和内存回收。
|
||
|
||
VFS 层负责：
|
||
|
||
- superblock、inode、dentry、file 等对象边界。
|
||
- path lookup。
|
||
- open/read/write/close/readdir 等通用文件操作。
|
||
- mount、权限、时间戳和错误码语义的长期位置。
|
||
|
||
block 层负责：
|
||
|
||
- block device 抽象。
|
||
- block request 和完成状态。
|
||
- 具体硬件驱动与 VFS 之间的隔离。
|
||
|
||
约束：
|
||
|
||
- 具体文件系统不直接访问磁盘硬件。
|
||
- 具体块设备驱动不解析文件系统。
|
||
- page cache 不属于某个具体文件系统或驱动。
|
||
- ELF loader 通过 VFS 读文件，不直接读取块设备或 initramfs 私有结构。
|
||
|
||
## 设备模型与驱动边界
|
||
|
||
长期设备模型包含：
|
||
|
||
- device
|
||
- driver
|
||
- bus
|
||
- resource
|
||
- probe/remove
|
||
- IRQ/DMA/MMIO/PIO resource 管理
|
||
|
||
驱动约束：
|
||
|
||
- probe 失败必须释放已申请资源。
|
||
- 驱动不修改无关子系统内部状态。
|
||
- 驱动不能长期 busy wait；应使用 IRQ、wait queue 或 deferred work。
|
||
- QEMU 专用设备支持不能破坏真机路径。
|
||
- ACPI/PCI/Device Tree 等平台信息隔离在平台层，通用驱动消费抽象资源。
|
||
|
||
输入路径：
|
||
|
||
- keyboard driver 产生 input event。
|
||
- input core 提供队列和等待。
|
||
- terminal/tty 消费 input event 并生成字节流或行。
|
||
- shell 读取 terminal，不读取 scancode。
|
||
|
||
存储路径：
|
||
|
||
- storage driver 接入 block layer。
|
||
- block layer 服务 filesystem。
|
||
- VFS 服务 kernel loader、用户态程序和 shell。
|
||
|
||
## 用户态与 syscall 边界
|
||
|
||
用户态相关对象要分开：
|
||
|
||
- process
|
||
- thread
|
||
- address space
|
||
- open file table
|
||
- credentials
|
||
- signal state
|
||
|
||
syscall 规则：
|
||
|
||
- syscall number、参数寄存器、返回值和错误码必须稳定记录。
|
||
- 用户指针必须复制和检查，不能直接解引用。
|
||
- syscall handler 不暴露 kernel 内部结构体。
|
||
- 用户态异常终止进程或转换成后续 signal，不能默认 panic。
|
||
- `fork/exec/wait`、signal、pipe、poll/select、futex 等长期路径要在 ABI 上预留。
|
||
|
||
用户程序规则：
|
||
|
||
- shell 和工具通过 libc 或 syscall ABI 访问 kernel。
|
||
- 用户程序不包含 kernel 私有头。
|
||
- 调试信息通过 syscall、procfs/debugfs 或等价虚拟文件接口暴露。
|
||
|
||
## 测试和回归边界
|
||
|
||
测试分层：
|
||
|
||
- `kernel/selftest/`：启动阶段内核自测，验证当前内核能力。
|
||
- `scripts/checks/`：主机侧检查，例如 build、boot、trap、page fault、structure。
|
||
- `scripts/tools/`：项目结构和自定义规则工具。
|
||
|
||
规则：
|
||
|
||
- 具体实现目录不放 selftest 主体。
|
||
- 新增公共 API 要有自测或 boot check 观察点。
|
||
- 调整目录边界要更新 `docs/agents/linux-layout.md`、`code-style.md` 或本文档。
|
||
- `scripts/check.sh` 是本地和 CI 的完整回归入口。
|
||
- 只改文档至少运行 `git diff --check`。
|
||
|
||
## 设计变更流程
|
||
|
||
遇到以下情况，先更新设计或任务文档，再改代码：
|
||
|
||
- 新增顶层目录或改变目录职责。
|
||
- 公共头文件新增跨子系统结构体。
|
||
- 修改 thread、wait queue、page、inode、file、process 等核心对象生命周期。
|
||
- 新增锁规则、等待规则或 IRQ 调用约束。
|
||
- 引入新硬件路径或新驱动模型。
|
||
- 新增 syscall ABI 或用户态可见行为。
|
||
|
||
遇到以下情况，可以直接小步改代码，但完成后要同步文档：
|
||
|
||
- 当前任务文档已经明确要求的局部实现。
|
||
- 不改变 API 的内部重构。
|
||
- selftest 或 check 脚本补强。
|
||
- 修复明显 bug，且不改变子系统边界。
|
||
|
||
## 当前主线
|
||
|
||
当前主线仍是 `docs/agents/tasks/04-time-scheduler.md`：
|
||
|
||
- wait queue 内部锁已经建立。
|
||
- 下一步应收紧 thread state helper，减少外部直接写状态。
|
||
- 然后继续完善 thread lifecycle 和 interrupt-exit reschedule。
|
||
- 在这些边界稳定前，不进入 keyboard/input 代码实现。
|