Asterinas 学习与贡献路线图

Asterinas 学习与贡献路线图

第一阶段：环境搭建 + 跑起来

目标：把内核编译出来并在 QEMU 里跑通。

1. 准备一台 x86-64（或 ARM64）的 Linux 机器，安装 Docker。

2. 克隆代码并进入开发容器：

   git clone https://github.com/asterinas/asterinas
   docker run -it --privileged --network=host \
       -v /dev:/dev -v $(pwd)/asterinas:/root/asterinas \
       asterinas/asterinas:0.17.1-20260319
   

3. 在容器内构建并运行：

   make kernel
   make run_kernel
   

   顺利的话会看到 Asterinas 内核在 QEMU 里启动，进入一个带有 initramfs 的 shell。

---

第二阶段：理解架构

目标：吃透 framekernel 的设计思想。

按以下顺序阅读 The Asterinas Book（book/src/）：

1. 《The Framekernel Architecture》

   • 路径：book/src/kernel/the-framekernel-architecture.md
   • 核心概念：双层分区、safe/unsafe 边界、与宏内核和微内核的对比
   • 在线版：https://asterinas.github.io/book/kernel/the-framekernel-architecture.html

2. 《An Overview of OSTD》

   • 路径：book/src/ostd/README.md

3. 《Soundness Analysis》系列

   • 路径：book/src/ostd/soundness/
   • 这是理解整个架构安全性证明的关键文档
   • 重点阅读：
     • 敏感度分类原则（sensitivity-classification.md）
     • Typed/untyped frame 内存模型（safe-memory-management.md）
     • 用户-内核交互安全（safe-user-kernel-interactions.md）
     • 内核-外设交互安全（safe-kernel-peripheral-interactions.md）

4. 《Writing a Kernel in 100 Lines of Safe Rust》

   • 路径：book/src/ostd/a-100-line-kernel.md
   • 动手示例，用 ~100 行 safe Rust 写一个能跑 Hello World 的内核

5. 《OSDK User Guide》

   • 路径：book/src/osdk/guide/
   • 理解 cargo osdk 工具链的工作方式

核心概念速查

Framekernel 架构：整个内核运行在同一地址空间（像宏内核），但被严格分成两半：

层次	unsafe Rust	职责	代码量
ostd/（OS Framework / TCB）	允许	封装底层 unsafe 代码，对外提供 safe API	小
kernel/（OS Services）	禁止（编译期强制）	系统调用、文件系统、网络栈、设备驱动等	大

TCB（Trusted Computing Base，可信计算基）：一旦出问题整个系统安全就失效的代码。Asterinas 的内存安全 TCB 只有 OSTD 这一个 crate。

---

第三阶段：读代码

目标：熟悉代码库结构和关键路径。

推荐的代码阅读顺序（自上而下）

1. kernel/src/lib.rs——内核入口，#![deny(unsafe_code)] 的实际位置
2. kernel/src/syscall/——系统调用分发层，从用户请求到内核响应的完整链路
3. kernel/src/fs/——文件系统实现
4. kernel/src/process/——进程管理
5. kernel/comps/——组件 crate：
   • virtio/——VirtIO 驱动
   • pci/——PCI 总线
   • network/——网络栈
   • block/——块设备
6. ostd/src/mm/——OSTD 内存管理，typed/untyped frame 的具体实现
7. ostd/src/arch/x86/——x86-64 架构特定代码（页表、中断、上下文切换）

阅读时关注的点

• OSTD 的 pub API 就是 framekernel 的安全边界，看 OSTD 对外暴露了什么
• kernel 里找不到任何一个 unsafe 块——这是架构的硬约束
• OSTD 内部每个 unsafe 块前都有 // SAFETY: 注释说明为什么安全

---

第四阶段：做贡献

先读贡献规范

book/src/to-contribute/coding-guidelines/ 下的全部文档，重点关注：

• Rust Guidelines：命名、函数、类型、unsafety、模块、宏的规范
• Git Guidelines：commit message 格式（祈使语气、≤72字符）、原子提交
• Testing Guidelines：回归测试、公共 API 测试

找第一个任务

参考项目的 GitHub Issues（标记为 good first issue 的条目）和路线图（book/src/kernel/roadmap.md）。

当前重点：x86-64 虚拟机场景的生产化。

推荐的第一个贡献方向（按难度）

难度	方向	说明
入门	补充测试用例	kernel 层完全 safe，测试不需要理解 unsafe 细节
入门	文档修复	book 中的错别字、过时描述、示例代码修正
进阶	syscall flag 覆盖	已有 230+ 系统调用，按 SCML 规范补充缺失的 flag
进阶	组件驱动	kernel/comps/ 下用 safe Rust 写新的设备驱动
硬核	OSTD 改进	需要深入理解 unsafe Rust 和安全证明，门槛最高

---

关键资源汇总

资源	链接
在线文档（The Asterinas Book）	https://asterinas.github.io/book/
API 文档（OSTD）	https://asterinas.github.io/api-docs-nightly/ostd/
代码仓库	https://github.com/asterinas/asterinas
项目论文	USENIX ATC 2025（Asterinas 架构）、SOSP 2025（CortenMM 内存管理）
开发容器镜像	asterinas/asterinas:0.17.1-20260319

---

建议的学习节奏

1. 先跑通环境（第一阶段），边跑边读文档
2. 等 framekernel 架构在脑子里形成清晰模型后，再开始看代码
3. kernel 层的 safe Rust 代码可读性很高，是进入内核开发的友好起点
4. 从简单的测试或文档修复开始第一次 PR，熟悉贡献流程后再逐渐深入