# 零 **Repository Path**: yywd123/zero ## Basic Information - **Project Name**: 零 - **Description**: 这 是 一 个 内 核 - **Primary Language**: C++ - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2023-09-17 - **Last Updated**: 2026-07-26 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Zero Zero 目前是一个基于 x86_64 架构的内核，当前处于从单体内核向**微内核**迁移的过程中。 ## Zero 当前是什么 - UEFI 引导的 x86_64 内核，支持 SMP（多核）。 - 具备 pmem、buddy、SLUB 与 kmalloc 物理/内核内存管理。 - 仅支持 x86_64 4 级页表；检测到 LA57 固件模式会明确停止启动。支持多核 TLB shootdown 和空中间页表回收。 - 具备抢占式多任务调度器（32 级优先级、per-CPU 状态、deferred reaper）。 - 已跑通 ring 3 process/thread construction、capability、memory mapping、暂停/恢复、 yield/exit 等 syscall；用户 page fault 只终止本进程。 ## 长期目标 Zero 的最终形态是一个以**消息传递和 capability 为核心的微内核**： - 所有普通可调度线程运行在 ring 3。 - 驱动作为独立 ring 3 进程向其他进程提供服务。 - ring 0 内核只提供执行、内存、IPC、权限、中断和硬件隔离等基础机制。 - 当前仍能看到 ring 0 驱动和单体内核遗留代码，这些将在后续迁移阶段逐步移出内核。 详见 [`doc/microkernel_roadmap.md`](doc/microkernel_roadmap.md)。 ## 当前迁移进度 Phase 2和Phase 3的软件Gate已通过，但这不等于完成正式硬件发布：非OVMF固件、多类真机 APIC/IOAPIC拓扑和真实AHCI失控设备证据仍未关闭。Phase 3 V1 ABI已冻结；clean commit `f58ca02`已开放memory slice、bounded endpoint create/send/receive/shutdown/inspect、WAIT+absolute deadline、 一次性wait-token cancel以及process-private 32-bit futex wait/wake。`ipcbuf`/`wqueue`仍只是内部原型， 不能视为公开IPC ABI；对应snapshot已由归档commit `7d9ab19`纳入仓库，用户waitset/call/completion 仍保留到Phase 6。 Phase 4.0 mechanism/core candidate现已实现resource domain、显式process factory、thread V2参数与FS base、stable process wait、owner-bound endpoint、production init bootstrap、registry状态机/codec/worker core和restart-backoff policy。它不表示通用spawn service、native loader、registry endpoint loop或完整 supervisor已经投入production运行。clean commit `88d9a93`的host `24/24`、QEMU `50 tests`、1/2/4/8 CPU topology、Phase 4 fault Gate和exact-hash production EFI smoke均通过；snapshot已归档到 `milestone-snapshots/88d9a93d346bc8ddbdd04d3658ddbad586214a96/`。当前权威状态见 [`doc/migration_status.md`](doc/migration_status.md) 末尾。 x86_64 最低能力和可选扩展策略见 [`doc/dev/cpu-baseline.md`](doc/dev/cpu-baseline.md)。 详细进度见 [`doc/migration_status.md`](doc/migration_status.md)。各阶段目标与验收条件见 [`doc/roadmap/phases.md`](doc/roadmap/phases.md)。Phase 3 精确设计见 [`doc/dev/phase3-v1-abi.md`](doc/dev/phase3-v1-abi.md)，后续阶段统一推进流程见 [`doc/dev/phase-workflow.md`](doc/dev/phase-workflow.md)。 ## 构建与运行 ### 依赖 - GCC（默认）或 Clang，均使用 x86_64 ELF target 和 GNU binutils - NASM - GNU Make - OVMF（UEFI firmware，用于 QEMU） - QEMU（提供 `qemu-system-x86_64`） - socat（集成测试通过有界 QMP shutdown 使用） ### 普通构建 ```sh make all ``` 使用 Clang 时可执行 `make all CC=clang CXX=clang++`。 默认 GCC 输出：`output/obj/debug/x86_64-gcc/zero.efi`；Clang 使用并行隔离的 `output/obj/debug/x86_64-clang/zero.efi`。 ### 运行 QEMU ```sh make build-run ``` 这会将 EFI 文件复制到 FAT 镜像并启动 QEMU（4 核、q35 芯片组）。 当前自动发布验证平台是 **QEMU q35 + OVMF**。启动还要求四级分页固件模式、ACPI MADT/IOAPIC 和 HPET；bootstrap direct-map 能覆盖的最高物理/MMIO 地址低于 512 GiB。 ACPI namespace 或中断拓扑验证失败会明确停止启动。多 IOAPIC、非零 BSP APIC ID 的 算法已实现，但在宣称通用真机支持前仍需要对应平台证据，详见 [`doc/dev/acpi-ioapic-release-gate.md`](doc/dev/acpi-ioapic-release-gate.md)。 ### 集成测试 ```sh make run-qemu-integration ``` 自动构建后启动 QEMU，正常路径由 guest 自行退出并返回结果。宿主 watchdog 超时后 优先通过 QMP 请求退出；若 QMP 已损坏，最终只终止本次 runner 创建的 QEMU 子进程， 保证测试命令有界返回。 默认使用TCG。仅在本机明确需要KVM压力时可执行： ```sh ZERO_QEMU_ACCEL=kvm make run-qemu-integration ``` KVM不是默认release Gate，测试流程、seed/injection、skip和证据边界见 [`doc/roadmap/testing.md`](doc/roadmap/testing.md)。 ### 单元测试 ```sh make run-unittest ``` 运行24组non-boot单元测试；除原有基础组外，还覆盖capability batch/dependency、层级resource domain、 formal wait cleanup ownership、deadline、wait token、memory slice、blocking endpoint、private futex、 registry/spawn/supervisor状态机和Phase 4故障事务。 ### 里程碑快照 | 范围 | 当前状态 | |---|---| | Phase 2 core / syscall ABI / allocator | 新增 remote TLB 定向证据；host `12/12`、QEMU `30` 项、Release 100 轮通过 | | Boot OVMF | 正常启动与 x2APIC/xAPIC partial-start fatal-stop Gate 通过 | | IPC/wait | Phase 3 ABI已冻结；clean commit `f58ca02`已开放blocking endpoint、deadline/cancel和private futex `25..34`，snapshot归档commit为`7d9ab19`；waitset/call仍保留到Phase 6 | | Init / spawn / registry | Phase 4 V1 clean commit `88d9a93`已实现resource domain、process/thread/endpoint V2、process wait、production init及bounded registry watch/result-slice；snapshot已归档 | | AHCI | 仅 boot-time IDENTIFY 诊断；masks `8/16/32` 可恢复错误与 mask `256` quiesce fatal-stop 通过，不绑定、不发布块服务 | | Logging / CPU interrupt | 普通、注入、xAPIC fallback 和四核 fatal-stop 软件 Gate 通过 | | Build/release | 本轮四组合 matrix、Release 100 轮、interleaving、relocation、xAPIC 与 fatal-stop 已复跑通过；clean commit 才能生成 manifest | | 真机 | 非 OVMF、xAPIC/x2APIC、多 IOAPIC、非零 BSP APIC ID、真实 AHCI 异常均未关闭 | 阶段性验证归档入口是 `make milestone-snapshot`。入口不绑定具体 Phase，会依次要求 clean tree、机械静态检查、四组合构建、 Release 长压测、interleaving、AHCI error injection、EFI relocation、xAPIC fallback、 四核普通/partial-AP fatal-stop；正式Gate显式固定TCG。QEMU证明带测试代码的integration variant运行， 随后在私有output中强制重建production variant，经test隔离、ELF/PE契约与可复现性静态检查，并对 最终同hash EFI执行production init smoke，再将其二进制和环境manifest归档到 `milestone-snapshots//`；任一 前置 Gate 失败，后续未运行项不能记录为通过。详情见 [`doc/dev/build-release-gate.md`](doc/dev/build-release-gate.md)。 该 manifest 会明确写入 `scope=validated-software-qemu-q35-ovmf` 和 `formal_hardware_release=false`。里程碑快照是阶段性开发检查点，不是非 OVMF/真机发布证明；正式硬件支持仍以各设备、 固件和 CPU Gate 中列出的外部证据为准。 ## 仓库目录结构 ```text zero/ ├── README.md 本文件 ├── Makefile 构建系统 ├── include/ 公共头文件 │ ├── base.h 基础宏、类型和工具 │ ├── kernel/ 内核机制（process、sched、intr、paging …） │ ├── mm/ 内存管理（pmem、buddy、slub、kmalloc、memory_object） │ ├── arch/x86_64/ x86_64 架构补充头文件 │ ├── drv/ 早期驱动接口 │ ├── efi/ UEFI 类型定义 │ └── utils/ 工具（list、lock、atomic、debug …） ├── src/ 实现文件 │ ├── arch/x86_64/ x86_64 架构代码 │ │ ├── boot/ 启动（EFI entry、早期页表） │ │ ├── kernel/ 调度、中断、页表、APIC … │ │ ├── mm/ 架构相关内存管理 │ │ └── drv/ 架构相关驱动 │ ├── kernel/ 内核通用实现（分阶段迁移） │ ├── mm/ 通用内存管理实现 │ ├── drv/ 通用驱动实现 │ └── third-party/ 第三方代码（uACPI、nanoprintf） ├── doc/ 文档 │ ├── roadmap/ 长期架构设计和迁移路线 │ ├── dev/ 开发文档和改进计划 │ └── learning/ 学习文档（面向新读者） ├── unittests/ 单元测试 └── scripts/ 辅助脚本 ``` ## 推荐阅读顺序 第一次阅读代码时，建议从高层往下、从简单往复杂。**不要**从 UEFI protocol、LA57 或 TLB shootdown 开始。 ```text README.md → src/arch/x86_64/main.c 内核入口，看初始化顺序 → include/kernel/process.h 进程与地址空间契约 → include/kernel/sched.h 调度器与线程契约 → src/arch/x86_64/bin/ring3_smoke.nasm 最小 ring 3 用户程序 → src/kernel/syscall.c syscall 分发与用户态交互 → src/mm/memory_object.c 用户态内存映射抽象 → src/arch/x86_64/kernel/sched.c 调度器实现 → src/mm/pmem.c → buddy.c → slub.c → kmalloc.c 内存管理四层链路 → src/arch/x86_64/kernel/paging.c 页表操作与 TLB shootdown → src/arch/x86_64/boot/efi_entry.c UEFI 启动流程 → src/arch/x86_64/boot/early_pagetable.c 早期页表构建 ``` 学习文档见 [`doc/learning/`](doc/learning/)，roadmap 见 [`doc/roadmap/`](doc/roadmap/)。 推进新的实施阶段前，先阅读 [`doc/dev/phase-workflow.md`](doc/dev/phase-workflow.md)。该流程要求 先确认前一阶段 Gate，再基于当前文档和实现打磨架构；需要参考 Linux 实现时，会在当次任务中 向用户询问本机 Linux 源码绝对路径，之后才进行 API 文档、公共头文件和具体实现。 ## 常见概念入口 - `doc/learning/glossary.md` — 术语表（process、thread、memory object、page table …） - `doc/learning/architecture-headers.md` — 架构头文件与 `#include_next` 机制 - `doc/learning/memory-layers.md` — 物理内存管理四层（pmem → buddy → SLUB → kmalloc） - `doc/learning/process-and-thread.md` — 进程与线程模型 - `doc/learning/scheduler.md` — 调度器状态机与并发规则 - `doc/learning/interrupt-and-syscall.md` — 中断、异常和 syscall 路径 - `doc/learning/virtual-memory.md` — 虚拟内存、页表和内存对象 - `doc/learning/capability-and-kobject.md` — capability handle、rights、引用与移动语义