# 零 

**Repository Path**: yywd123/zero

## Basic Information

- **Project Name**: 零 
- **Description**: 这 是 一 个 内 核
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-09-17
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zero

Zero 是一个面向 x86_64 的实验性操作系统内核，正在从现有的内核态设备代码和基础设施，逐步发展为以
capability、消息传递和用户态服务为中心的微内核系统。

我们想让运行软件的人掌握执行权，让软件与设备的失败停留在明确边界内。
Zero 是一个可以认真尝试这些想法的 hobby OS：不只关心程序能否运行，也关心谁能控制它、它能影响什么，
以及它出问题时，其他工作是否还可以继续。

项目目前仍处于 pre-production 阶段。代码、ABI、设备接口和文档都会随着实现和验证结果调整，不提供稳定的
原生 ABI 或真实硬件兼容承诺。

## 想做成什么

以下是项目的取向，不是已实现功能清单。权限与微内核边界已有机制和架构依据；执行控制、seal取舍和IO时间隔离
仍在设计，具体范围见当前设计任务，而不是由本README建立新契约。

- **权限显式。** 持有什么capability，才能影响什么。名称、路径、设备地址和程序自述不创造权限；
  权限的转交与撤销也必须有明确边界。
- **Kernel少管，边界管牢。** 服务选择、普通driver、文件系统和兼容语义留在用户态。Kernel提供不可绕过的
  隔离、调度、消息传递和资源安全机制，不替系统决定应该运行哪一种软件。
- **执行可以被接管。** 探索由明确获授权的控制者暂停、观察、修改和继续执行，并接管部分系统入口与外部交互。
  兼容层、逆向分析和隔离环境可以共享底层机制，但各自的策略留在用户态；不承诺不可检测或已经能控制所有输入。
- **不可变是一种承诺，不是所有代码的宿命。** 重新审视执行许可、W^X与永久seal的绑定，为JIT、热补丁和
  获授权的代码修改寻找合理表达。同时，真正承诺不可变的对象不能被悄悄修改后仍冒充原来的对象。
- **失败不应该绑架整机。** 慢设备可以等待与重试，但不依赖它的启动和运行路径不应陪着停摆。
  目标是约束等待链、资源占用和恢复影响范围，而不只是把driver搬到ring 3；共享硬件与延迟保证的前提必须说清楚。

这些方向的设计入口是[`当前设计任务`](doc/status/current_todo.md#本轮设计任务仅讨论不激活实现)中的
`DSN-001`（执行与seal）、`DSN-002`（可控执行环境）和`DSN-003`（IO影响边界）。它们尚未激活实现，
不是启动普通程序之前必须全部完成的一套框架。

## 项目现状

当前代码已经包含一套可以在 UEFI/OVMF 和 QEMU q35 环境中运行的 x86_64 内核基础设施，包括：

- UEFI 启动、SMP、多级页表、早期页表和基础 CPU/APIC 初始化。
- 物理内存、buddy、SLUB、kmalloc、memory object 和用户地址空间管理。
- 进程、线程、抢占式调度、用户态执行、syscall、user-copy 和异常隔离。
- capability、resource domain、endpoint、wait operation、waitset、call/completion 和 futex 等内核机制。
- 受限的用户态 runtime、production init、registry 和 supervisor 服务骨架。
- Experimental Device epoch 1 的设备发现、resource claim、typed PIO/MMIO/IRQ authority 和事务化清理机制。
- 启动环境交接、EFI memory ownership、firmware mapping membership 和物理资源归属记录。

这些能力主要用于验证内核机制、ownership、生命周期和失败处理，不代表已经形成完整桌面系统、通用驱动栈或
稳定的用户空间发行版。

用户态不是空白：受限外置启动路径已实际运行init，再由普通supervisor通过spawn启动payload及其下级线程。
但目前不少用户程序仍服务于机制验证；storage、用户态firmware/device manager与VFS链路尚未闭合，
距离可以日常使用的用户空间仍有明显缺口。执行控制与兼容层愿景也不等于已有可用的分析环境或应用兼容能力。

VT-d/DMA 目前处在能力发现和隔离基础建设阶段：已经有 DMAR topology proof、逐unit capability snapshot、table image
事务、fault record 原始日志和deny-all隔离验证。generic production保持`translation=disabled`；独立deny-all profile可以启用
全requester阻断，但仍没有通用DMA、AHCI用户态服务、requester allowing-domain attach或正式通用IOMMU containment。AHCI当前只保留启动期诊断路径。

## 开发方式

Zero 采用一种以代码、文档和验证相互约束的开发方式。AI 会参与代码搜索、设计整理、实现草稿、测试补充和文档
维护，但生成内容不被视为自动正确；重要改动仍需要结合源码、边界条件、测试结果和人工 review 进行确认。

文档在这里不只是说明材料，也用来记录当前事实、明确非目标、冻结接口边界和保存验证条件。实现应从可审查的
模块文档和生命周期不变量中脱胎；实践中发现的新约束、失败模式和边界条件也必须反向更新文档。这样可以先审查
模块“应该成立什么”，再将文档条目映射到代码、测试、静态 Gate 和 QEMU 证据。文档审查不能替代代码和硬件验证，
但能让实现审查拥有明确的契约、状态机、ownership、错误语义和验收条件。详见
[`文档与实现双向约束`](doc/engineering/document-centered-development.md)。主README只保留项目概览，具体进度和历史证据不在这里维护。

## 阅读入口

- 当前实现和验证状态：[`doc/status/current.md`](doc/status/current.md)
- 文档层次和权威来源：[`doc/README.md`](doc/README.md)
- 整体内核架构与裁决层：[`doc/architecture/README.md`](doc/architecture/README.md)
- 专题设计与阶段路线：[`doc/roadmap/README.md`](doc/roadmap/README.md)
- ABI 生命周期与实验性接口：[`doc/abi/README.md`](doc/abi/README.md)
- 实现契约：[`doc/implementation/README.md`](doc/implementation/README.md)
- 构建、产物和硬件边界：[`doc/gates/README.md`](doc/gates/README.md)
- 工程流程和 review 规则：[`doc/engineering/README.md`](doc/engineering/README.md)

## 构建与验证

### 依赖

- GCC 或 Clang，以及 GNU binutils
- NASM
- GNU Make
- Python 3.11或更高版本
- Git
- QEMU，提供 `qemu-system-x86_64`
- OVMF，用于 UEFI 启动
- dosfstools和mtools，提供`mkfs.vfat`和`mcopy`
- socat，用于部分有界 QMP 测试流程
- GDB，可选；只在交互式terminal dump attach流程中使用

克隆后初始化第三方submodule：

```sh
git submodule update --init --recursive
```

### 普通开发

日常开发直接使用Make完成增量构建、简单运行和手动调试。默认production构建：

```sh
make
```

构建并启动QEMU，或选择构建模式和编译器：

```sh
make build-run QEMU_EXTRA_ARGS=""
make BUILD_MODE=release
make CC=clang CXX=clang++
```

已有serial log包含完整terminal dump时，使用Scaffold提供的离线decoder，不需要重新运行测试：

```sh
./scaffold decode-dump - # 读标准输入 输入后记得EOF
./scaffold decode-dump path/to/serial.log
./scaffold decode-dump path/to/serial.log --symbols output/obj/debug/x86_64-gcc-production-generic/libzero.so
```

### 自动测试

Scaffold是项目的自动测试与证据编排框架，不是普通开发构建的包装层。它负责测试profile、依赖计划、QEMU生命周期、
PASS/FAIL oracle、失败现场、结果identity和大规模matrix；自动测试内部可受控调用Make生成artifact。

运行单个自动测试profile：

```sh
./scaffold debug qemu-integration
./scaffold debug qemu-integration --launch-gdb-on-fault
```

`--launch-gdb-on-fault`只适用于单个integration Debug：typed fatal和completion/test-fail可attach；completion/test-pass与
production-acceptance不attach，diagnostic按诊断策略收尾且不冒充fatal。Scaffold先解码完整terminal envelope并校验本次
BuildResult的精确`libzero.so` build-id，再启动GDB。退出GDB后QEMU通过QMP收尾并保留证据。
该模式不会进入matrix或release。

大规模自动测试运行声明式matrix。Matrix默认在首个失败实例停止：

```sh
./scaffold debug-matrix topology --output live
./scaffold debug-matrix host-unittest
```

诊断完整失败分布时添加`--continue-on-error`；使用可重复的`--filter factor=value1,value2`缩小matrix。完整MatrixResult
按内容identity写入`output/scaffold-results/matrix/<identity>.json`，各实例保留独立DebugResult。

运行repository静态Gate和Scaffold自身测试：

```sh
./scaffold check repository
```

查看计划不会执行构建或QEMU：

```sh
./scaffold plan debug-matrix topology
./scaffold plan release milestone
```

基础命令、输出目录、filter、build policy和失败证据读取见
[`Scaffold构建、检查与调试框架`](doc/engineering/build-test-framework.md)开头的“快速入门”；事务模型、schema、receipt和
release机制属于该文后续进阶内容。

### 测试介质

构造可持久化复用的测试boot media：

```sh
./scaffold image qemu-integration -P ensure
./scaffold debug qemu-integration -P reuse --image-result <ImageResult路径>
```

第一条命令会打印`esp.img`和ImageResult路径。相同输入默认复用已经验证的image，显式`-f`才重新构造。该介质明确是
`test-boot-media`且`publication=not-release`，不是发行版镜像；安装目标、最终分区布局、升级策略和发布签名由未来的上层发行工具决定。

Image profile中的`capacity_bytes`是ESP介质的固定总容量；`debug_profile`绑定提供Build/RunSpec输入的Debug profile；
成员使用`member_role`表示镜像内角色，使用`source_role`表示BuildResult artifact来源，或使用`generator`表示Scaffold生成器。

当前Scaffold QEMU与OVMF位置由`scaffold.toml`的`[runtime].qemu_path`和`[runtime].ovmf_path`配置；profile可显式覆盖。

### Release acceptance

查看完整release acceptance步骤：

```sh
./scaffold plan release milestone
```

完整执行要求Git worktree为clean，并生成统一ReleaseResult：

```sh
./scaffold release milestone
```

开发期间可以验证单一步骤，例如：

```sh
./scaffold release milestone --only xapic-release --output quiet
```

单步结果明确标记为`PARTIAL_PASS`，不能作为完整milestone或发布证据。

其他设备、waitset、call/completion和production smoke入口见
[`doc/roadmap/testing.md`](doc/roadmap/testing.md)及[`doc/gates/README.md`](doc/gates/README.md)。

当前主要验证环境是 QEMU q35 + OVMF。通过这些测试不等于已经验证非OVMF固件、真实CPU/APIC/IOAPIC组合、真实AHCI
设备或其他物理硬件。

## 参考项目

Zero 会参考 Linux、Managarm 以及其他系统项目来理解机制、失败模式和工程取舍，但不继承它们的内部 ABI、对象
模型或兼容承诺。进入 Zero 的接口、实现、注释和测试需要按本项目的约束独立设计和表达。

- [Linux](https://kernel.org/)：调度、内存、设备和成熟硬件机制的参考。
- [Managarm](https://github.com/managarm/managarm)：微内核集成、用户态驱动、IPC、服务发现和DMA/IOMMU方向的参考。

## 仓库结构

```text
zero/
├── include/          头文件、内核接口和实验性用户 ABI
├── src/              内核、架构代码、驱动和集成框架
├── user/             production userspace runtime 和服务组合
├── unittests/        host 单元测试
├── mk/               构建与测试规则
├── scripts/          静态 Gate、runner 和辅助脚本
├── tools/scaffold/   Scaffold事务、image、QEMU/QMP和evidence实现
├── scaffold.toml     Build、Image和Debug profile配置
└── doc/              状态、roadmap、ABI、实现契约和验证边界
```

第一次阅读代码可以从 [`doc/learning/`](doc/learning/) 开始，再根据当前状态进入对应的源码和实现契约。