# x-kernel
**Repository Path**: openkylin/x-kernel
## Basic Information
- **Project Name**: x-kernel
- **Description**: X-Kernel 是一个使用 Rust 编写的多架构单体内核。
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 66
- **Forks**: 57
- **Created**: 2025-12-16
- **Last Updated**: 2026-11-17
## Categories & Tags
**Categories**: os
**Tags**: os, Rust, kernel
## README
# X-Kernel
[English](README.md) · [代码仓库](https://gitee.com/openkylin/x-kernel) · [Issues](https://gitee.com/openkylin/x-kernel/issues) · [社区](https://x-kernel.zulipchat.com)
[](LICENSE)
X-Kernel 是一个使用 Rust 编写、面向 Linux ABI 的单体内核。它可以在 x86_64、AArch64、RISC-V 64 和 LoongArch64 上运行基于 musl/glibc 构建的 Linux 用户态程序,在内核内为机密计算 guest 提供 TEE 支持,并可运行 Chromium、niri、Xorg/Xwayland 等 Wayland/X11 桌面负载。
X-Kernel 上的 niri + Chromium(哔哩哔哩)+ PCManFM(x86_64,virtio-gpu,1600x900)。
各子系统按明确的职责与所有权边界拆分为 crate,详见[源码布局](#源码布局)。
## 目录
- [为什么选择 X-Kernel](#为什么选择-x-kernel)
- [快速开始](#快速开始)
- [真实负载](#真实负载)
- [平台支持](#平台支持)
- [能力状态](#能力状态)
- [桌面负载](#桌面负载)
- [设计](#设计)
- [验证](#验证)
- [性能](#性能)
- [配置](#配置)
- [源码布局](#源码布局)
- [文档](#文档)
- [社区与贡献](#社区与贡献)
- [安全](#安全)
- [已知限制](#已知限制)
- [许可证](#许可证)
- [致谢](#致谢)
## 为什么选择 X-Kernel
- **Linux ABI,面向生产用户态。** X-Kernel 在 `core/ksyscall`、`posix/` 和 `api/linux_sysno` 中实现 Linux 兼容的系统调用与 POSIX 接口。systemd 以 PID 1 启动并运行 glibc 用户态,Docker hello-world 可运行,Wayland/X11 桌面也可运行在同一内核上;Starry Test Harness 从用户态验证这套 ABI。
- **四种架构。** x86_64、AArch64、RISC-V 64、LoongArch64 均受支持;x86_64、AArch64、RISC-V 持续构建和测试。
- **内核内的机密计算。** 海光 CSV 支持硬件根密钥(HUK)和 attestation(远程证明);ARM virtCCA 支持 HUK 派生;pKVM 是实验性的 guest 模式。TEE 支持 TA(可信应用)生命周期、安全存储,以及基于 RustCrypto 的 SM2/ECC/RSA。
- **桌面级图形能力。** DRM/KMS、virtio-gpu 2D/3D、EDID、page-flip/vblank、fbdev 与 virtio-input 支持 Chromium(Wayland)、niri、Xorg/Xwayland,包含键盘/鼠标输入和宿主窗口 resize。合成器与 rootfs 属于用户态产物;内核提供显示、GPU 和输入接口。
- **Linux 基线验证。** 内核单测、[Starry Test Harness](https://gitee.com/openkylin/starry-test-harness) 和 TEE 测试覆盖系统调用、文件系统、网络、桌面和机密计算 workload。
## 快速开始
### 前置条件
| 依赖 | 说明 |
|---|---|
| Rust | 使用 `rust-toolchain.toml` 固定的工具链。 |
| QEMU | `make run` 需要对应架构的 QEMU system emulator。 |
| `cargo-binutils`、`rust-objcopy` | 生成内核镜像所需。 |
| Musl 交叉工具链 | 仅用于 uapps、TEE 测试和 Harness guest 用例;内核本身不编译 C,见[交叉工具链](#交叉工具链)。 |
| rootfs 工具 | `make rootfs` 需要 `curl` 和 `xz`。 |
| x86_64 启动介质 | UEFI 需要 OVMF/EDK2,FAT 介质需要 `mkfs.fat` 和 mtools,LinuxBoot setup 代码需要 GNU i386 工具链。 |
| 单测覆盖率 | `debugfs`、`rust-profdata`、`rust-cov`。 |
| 仓库检查工具 | `make install-tools` 安装固定版本的 `cargo-shear`、`licensure` 和 dylint 工具。 |
CI builder 镜像提供 CI 构建环境(项目工具链由 CI 安装),见 [`scripts/ci/docker/`](scripts/ci/docker/) 和 [`docs/jenkins-pipeline.md`](docs/jenkins-pipeline.md)。完整前置条件参考 [`docs/ai/skills/build-workflow/SKILL.md`](docs/ai/skills/build-workflow/SKILL.md)。
### 构建与运行
```bash
# AArch64 QEMU:最短路径
cp platforms/kplat-aarch64/qemu_defconfig .config
make defconfig
make rootfs # 需要 curl 和 xz
make build
make run
```
```bash
# x86_64 QEMU,可选 UEFI 启动
cp platforms/kplat-x86_64/qemu_defconfig .config
make defconfig
make run
make run UEFI=y
```
x86_64 上 `make run` 默认使用 LinuxBoot,`make run UEFI=y` 选择 OVMF/UEFI。可通过 `OVMF_CODE` 和 `OVMF_VARS_TEMPLATE` 指定固件路径。
x86_64 CSV 使用 `scripts/start.sh` 构建 UEFI 镜像并以 SEV 启动 QEMU。脚本需要 OVMF,以及默认名为 `cvm_1_launch_blob.bin` 和 `cvm_1_guest_owner_dh.cert` 的 SEV 启动产物。
```bash
bash scripts/start.sh
```
### 真实负载
这些端到端负载用于区分 X-Kernel 与只实现系统调用表的 Linux ABI 内核。
| 负载 | 命令 | 预期结果 |
|---|---|---|
| systemd + glibc | `make rootfs ROOTFS_VARIANT=debian-systemd` | systemd + glibc 进入 shell |
| Docker | `docker run --network=host --rm hello-world` | `Hello from Docker!` |
| Wayland 桌面 | `make run GRAPHIC=y DISK_IMG=` | Chromium/niri/Xorg 启动 |

*Debian 13 上的 systemd 257 + glibc 2.41(x86_64,`debian-systemd` rootfs)。*
### 运行参数
```bash
make run XKMAKE_ARGS='--memory 2g --smp 2 --no-net'
make run XKMAKE_ARGS='--no-vsock'
make run QEMU_ARGS='-d guest_errors'
make run QEMU_ARGS='-no-reboot'
```
`XKMAKE_ARGS` 透传给 xkmake;`QEMU_ARGS` 会原样追加在 `--` 之后,适合传递 QEMU 原生参数。`GRAPHIC=y` 会添加 GTK 显示窗口和 virtio 键盘/鼠标;配合桌面 rootfs 即可运行 Chromium、niri 或 Xorg/Xwayland,详见[桌面负载](#桌面负载):
```bash
# 需要 Wayland/X11 桌面 rootfs
make run GRAPHIC=y GPU_XRES=1920 GPU_YRES=1080
```
默认的 `make rootfs` 是控制台镜像;桌面 rootfs 与合成器镜像独立于内核代码树分发,构建或启动内核本身不依赖它们。
### 单元测试
```bash
make unittest
make unittest UNITTEST_CRATE=kvfs,kprocess
make ci-test # 拉取 Starry Test Harness 并运行 CI suite
```
在启用覆盖率(默认启用)时,单测成功运行后会在 `target///` 下生成 `coverage.txt`、`coverage.info` 和 `coverage.xml`。
### 交叉工具链
以下工具链仅用于 uapps、TEE 测试和 Harness guest 用例;内核本身不编译 C。
| 架构 | GCC | Musl | 下载 |
|---|---|---|---|
| x86_64 | 11.2.1 | git-b76f37f (2021-09-23) | [musl.cc](https://musl.cc/x86_64-linux-musl-cross.tgz) |
| aarch64 | 11.2.1 | git-b76f37f (2021-09-23) | [musl.cc](https://musl.cc/aarch64-linux-musl-cross.tgz) |
| riscv64 | 11.2.1 | git-b76f37f (2021-09-23) | [musl.cc](https://musl.cc/riscv64-linux-musl-cross.tgz) |
| loongarch64 | 13.2.0 | 1.2.5 | [LoongsonLab](https://github.com/LoongsonLab/oscomp-toolchains-for-oskernel/releases/download/loongarch64-linux-musl-cross-gcc-13.2.0/loongarch64-linux-musl-cross.tgz) |
## 平台支持
### 已支持目标
| 目标 | defconfig | 说明 |
|---|---|---|
| x86_64 QEMU | [`qemu_defconfig`](platforms/kplat-x86_64/qemu_defconfig) | 默认 x86_64 目标。 |
| x86_64 CSV | [`qemu_csv_defconfig`](platforms/kplat-x86_64/qemu_csv_defconfig) | CSV HUK + attestation;[`scripts/start.sh`](scripts/start.sh)。 |
| AArch64 QEMU | [`qemu_defconfig`](platforms/kplat-aarch64/qemu_defconfig) | 默认 AArch64 目标。 |
| RISC-V 64 QEMU | [`qemu_defconfig`](platforms/kplat-riscv64/qemu_defconfig) | RISC-V 64 目标。 |
### 其他目标
| 目标 | defconfig | 说明 |
|---|---|---|
| AArch64 crosvm | [`qemu_crosvm_defconfig`](platforms/kplat-aarch64/qemu_crosvm_defconfig) | AArch64 crosvm 目标。 |
| AArch64 virtCCA | [`qemu_virtcca_defconfig`](platforms/kplat-aarch64/qemu_virtcca_defconfig) | AArch64 virtCCA guest;HUK 派生。 |
| AArch64 RK3588 | [`rk3588_defconfig`](platforms/kplat-aarch64/rk3588_defconfig) | Orange Pi 5 Plus;UART 控制台。 |
| LoongArch64 QEMU | [`qemu_defconfig`](platforms/kplat-loongarch64/qemu_defconfig) | LoongArch 64 目标。 |
| Kylin-x pKVM | 无 defconfig | Kylin pKVM guest feature flag。 |
## 能力状态
状态:**已实现**表示已有测试或 workload 覆盖;**部分实现**表示已具备但只覆盖已知子集;**尚未**表示 `main` 中不可用。
| 领域 | 状态 | 范围与已知缺口 | 代码 |
|---|---|---|---|
| 内存管理 | 已实现 | 地址空间、缺页、COW、`mmap`/`brk`;Linux 语义子集。 | `mm/` |
| 进程与调度 | 已实现 | `fork`/`exec`、`wait*`、信号、futex、定时器、EEVDF 调度。 | `process/`, `task/` |
| VFS 与路径解析 | 已实现 | `namei`、mount 遍历、`openat2` `RESOLVE_*` 约束;Linux 子集。 | `fs/kvfs` |
| ext4 | 部分实现 | 读写和 project quota;尚未完整通过 xfstests。 | `fs/filesystems/kext4` |
| 其他文件系统 | 部分实现 | tmpfs/ramfs、procfs、sysfs、devfs/devpts、pipefs、9p、fat、cgroup2fs、bpffs;覆盖程度不一。 | `fs/filesystems/` |
| 网络 | 部分实现 | TCP/IP、Unix socket、netfilter、vsock、netlink、TIPC;Linux 子集。 | `net/knet` |
| 驱动与设备模型 | 已实现 | 类型化驱动核心;virtio blk/net/gpu/input/console;PCI 与 IRQ 基础设施。 | `drivers/`, `io/` |
| 图形(内核) | 部分实现 | DRM/KMS、virtio-gpu 2D/3D、EDID、page-flip/vblank、fbdev;单 scanout virtio-gpu 路径。 | `io/drmdevice`, `io/fbdevice`, `io/inputdev` |
| 桌面负载 | 已实现 | Chromium(Wayland)、niri、Xorg/Xwayland;键盘/鼠标输入与宿主窗口 resize。 | 用户态合成器 + `io/drmdevice`, `io/inputdev` |
| TEE | 已实现 | TA(可信应用)生命周期、安全存储、基于 RustCrypto 的 SM2/ECC/RSA;CSV HUK + attestation;virtCCA HUK。 | `tee/`, [`docs/tee.md`](docs/tee.md) |
| 容器 guest | 部分实现 | `docker run --network=host --rm hello-world` smoke;user namespace 与 cgroup 仍有缺口。 | `uapps/mini-oci`, [`docs/container-architecture.md`](docs/container-architecture.md) |
### 桌面负载
桌面路径使用内核的 DRM/KMS、virtio-gpu(2D/3D、EDID)和 virtio-input 驱动。已验证的用户态包括:
- **Chromium(Wayland)**:窗口、frame callback、键盘/鼠标输入。
- **niri**:基于 niri v26.04 构建的参考合成器磁盘;支持宿主窗口 resize 和指针/键盘输入。
- **Xorg/Xwayland**:通过 Xorg/Xwayland 路径运行 X11 负载。
合成器与桌面 rootfs 作为独立的用户态产物维护;内核的构建和启动不依赖它们。参考桌面镜像维护在 [openkylin/x-agentos](https://gitee.com/openkylin/x-agentos)。
## 设计
X-Kernel 在运行时是单体内核,但在契约上按组件拆分。安全价值来自 API 隔离和可界定的审计范围,而不是 crate 之间的运行时隔离。
- **API 优先的所有权。** `mm/memspace`、`core/kuaccess`、`process/kexec`、`kirq`/`device_res` 是独立契约,不是某个 catch-all crate 的实现细节。200 多个 crate 共同定义所有权地图。
- **审计边界。** 每个 crate 在适用时提供 `docs/design.md` 和 `docs/security.md`;评审可以把改动限定在 API 契约及其下游使用者。
- **Unsafe 边界。** 每个 `unsafe` 块都需要 `SAFETY:` 说明;MMIO、DMA、上下文切换、TEE glue 等 unsafe 密集区域收在子系统 API 后面。
- **隔离边界。** crate 边界是编译期的,不是特权边界。TEE 为 TA/guest 提供运行时隔离;内核本身仍是单一地址空间。
```text
Linux 用户态:systemd / Docker / Wayland / X11
------------------------------------------------
ABI:ksyscall / posix / tee
------------------------------------------------
子系统:mm | process/task | fs | net | drivers/io
------------------------------------------------
架构 HAL:x86_64 | AArch64 | RISC-V 64 | LoongArch64
------------------------------------------------
平台:QEMU | crosvm | virtCCA | CSV | RK3588
```
## 验证
验证分为三层:
- 内核单测(`make unittest`);
- 通过 [Starry Test Harness](https://gitee.com/openkylin/starry-test-harness) 运行 Linux/POSIX 用户态回归(`make ci-test`);
- TEE 的安全存储与加密测试。
Harness 还包含 LTP、Open POSIX、libc-test、文件系统、网络、桌面和容器 workload。
## 性能
性能表现依赖 workload:计算、调度和 pagecache 路径与 Linux 有竞争力;存储和 TCP 吞吐是主要差距。
## 配置
```bash
make menuconfig # 修改配置
make olddefconfig # Kconfig 变更后非交互刷新
make savedefconfig # 写出最小化 ./defconfig
```
`make defconfig` 会把复制的平台 `defconfig` 展开为完整的 `.config`。构建产物位于 `target/xkmake///`。配置与构建编排详见 [`docs/xkmake-design.md`](docs/xkmake-design.md)。
## 源码布局
| 路径 | 职责 |
|---|---|
| `arch/` | 架构 HAL:CPU、异常、分页、定时器、IPI。 |
| `boot/` | 启动协议交接、早期 stub、内核镜像解析。 |
| `core/` | 系统调用分发、运行时、tracing、用户内存访问、服务。 |
| `mm/` | 地址空间、VMA、缺页、page cache、分配器。 |
| `process/`, `task/` | 进程、线程、信号、调度、futex。 |
| `fs/` | VFS(`fs/kvfs`)与各文件系统实现。 |
| `net/` | TCP/IP、socket、netfilter、vsock、netlink。 |
| `drivers/`, `io/` | 驱动核心、virtio、PCI、中断与显示/输入子系统。 |
| `tee/` | TEE 内核、TA 生命周期、安全存储、加密。 |
| `platforms/` | 平台粘合层和平台 `defconfig`。 |
| `util/` | 共享工具 crate。 |
各 crate 的设计与威胁模型文档位于代码旁的 `docs/design.md` 和 `docs/security.md`(如有)。
## 文档
- [发布规范](docs/release.md)与 [v0.1.0-2606 发布说明](docs/releases/v0.1.0-2606.md)
- [TEE 构建指南](docs/tee.md)
- [容器架构](docs/container-architecture.md)
- [Jenkins 流水线契约](docs/jenkins-pipeline.md)
- [XKMake 设计](docs/xkmake-design.md)
- [代码规范](docs/code-guidelines/README.md)
- [构建流程与前置条件](docs/ai/skills/build-workflow/SKILL.md)
## 社区与贡献
- 代码仓库:
- Issues:
- Pull requests:
- 社区聊天:
提交 PR 前:
1. 阅读 [`docs/code-guidelines/README.md`](docs/code-guidelines/README.md) 以及相关 crate 的 `docs/design.md` / `docs/security.md`。
2. 运行 `make fmt`、`make clippy`,以及范围最小的相关 `make unittest`。
3. 改动涉及系统调用或用户态行为时,运行 `make ci-test`。
4. 重构提交与功能/行为提交分开;代码变更同步更新设计/安全文档。
## 安全
X-Kernel 使用 Rust 的内存安全模型、带 `SAFETY:` 说明的显式 `unsafe` 边界,以及面向机密计算 workload 的 TEE 隔离。
如发现疑似漏洞,请私下联系维护者,不要直接开公开 issue。
## 已知限制
- Linux ABI 覆盖是子集;部分系统调用、文件系统/网络能力和内存管理路径仍不完整。
- 各平台成熟度不同;部分目标需要额外配置,测试覆盖也较轻。
- 桌面和容器端到端运行不在默认 CI 路径中;CI 聚焦内核侧构建和单测。
- 性能表现依赖 workload:计算、调度和 pagecache 有竞争力,存储和 TCP 吞吐仍落后 Linux。
## 许可证
本项目基于 Apache License 2.0 发布。详见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。
## 致谢
X-Kernel 受 [StarryOS](https://github.com/Starry-OS/StarryOS) 和 [ArceOS](https://github.com/arceos-org/arceos) 启发。