hust-open-atom-club · zevorn · Nov 17, 2025 · Nov 17, 2025 · Nov 17, 2025 · Nov 17, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -133,9 +133,8 @@
 格式如下，不同作者名字之间用中文全角顿号（「、」）分隔：
 
 ```markdown
-!!! note "主要作者"
-
-    [@example][github.com/example]、[@new-contributor][github.com/new-contributor]
+!!! note "主要贡献者"
+   - 作者：[@example][github.com/example]、[@new-contributor][github.com/new-contributor]
 ```
 
 ### 3. 为图片添加配字

diff --git a/docs/articles/ch0/01-rust-for-qemu-introduction.md b/docs/articles/ch0/01-rust-for-qemu-introduction.md
@@ -0,0 +1,73 @@
+# Rust for QEMU 概述
+
+!!! note "主要贡献者"
+    - 作者：[@zevorn](https://github.com/zevorn)
+
+## 技术演进历史
+
+关于 Rust for QEMU（官方称 Rust in QEMU）的发展历史，最早可以追溯到 2020 年。彼时 QEMU 社区的维护者 Stefan Hajnoczi 发表了一篇名为 [Why QEMU should move from C to Rust][1] 的文章，系统地阐述了 QEMU 的安全需求，引起社区广泛响应，由此进入构想与社区讨论阶段。
+
+2021 年 KVM Forum 2021 [针对 Rust 展开专题讨论][2]，聚焦具体的技术路径和核心挑战。此后，Rust for QEMU 一直在 QEMU 主线外开发，并伴随 Rust 本身一起迭代。
+
+2024 年进入实验性探索阶段，QEMU 9.2 首次官方支持 Rust，默认禁用需手动开启，该版本引入构建系统支持，创建核心 Crate，提供 PL011 串口设备作为概念验证。
+
+2025 年进入功能完善阶段，QEMU 10.0 实现了 Rust 相关源码的构建稳定和测试覆盖，新增 HPET 设备支持，同时大幅减少设备代码所需的 unsafe 代码量，并提升 Safe Rust 代码比例，以及日志记录、迁移支持等核心功能的完善。
+
+!!! example "温馨提示"
+    - 关于 Rust for QEMU 技术路线演进的更多细节，请阅读我们的[新闻栏目][3];
+    - 本文档使用的 QEMU 源码仓库地址是：[rust-for-qemu-insides-src][4];
+
+## 整体架构介绍
+
+Rust for QEMU 的核心架构采用"外围扩展，核心桥接"的设计理念，旨在允许开发者用安全的 Rust 代码编写设备模型，同时与庞大的 C 代码库无缝交互（而非重写 C 部分）。整体架构呈现清晰的分层结构（采用模块化的 Crate 结构，各层职责明确）：
+
+| 层级           | 核心模块                                      | 核心功能                                              |
+|----------------|-----------------------------------------------|------------------------------------------------------|
+| 应用层         | pl011, hpet                                   | 用 Rust 重写的具体设备模型，目标完全使用安全代码        |
+| 公共层         | common                                        | 提供纯 Rust 的实用工具函数和数据结构                   |
+| 中间绑定       | bql, chardev, hw/core, migration, qom, system, util | 对自动生成 FFI 进行手动封装，提供初步安全抽象     |
+| 底层绑定       | 自动生成绑定                                  | 由 bindgen 自动生成，提供对 QEMU C API 的原始 FFI 绑定  |
+
+QEMU 使用 Meson 构建系统协调 C 和 Rust 的编译过程，其核心机制包括：
+
+| 核心机制     | 描述                                                                                               |
+|------- ------|----------------------------------------------------------------------------------------------------|
+| 自动绑定     | 构建过程中调用 bindgen 工具解析 QEMU 核心头文件（如 hw/qdev-core.h），自动生成对应的 Rust FFI 绑定代码 |
+| 静态库链接   | 将 Rust 代码编译为静态库（如 libqemu-aarch64-softmmu-rust.a），与 C 代码对象文件链接成最终可执行文件   |
+
+另外还有许多关键设计，比如 QOM 类型注册机制：
+
+| 语言 | 区别                                                                                                           |
+|------|----------------------------------------------------------------------------------------------------------------|
+| C    | QOM 系统要求每个设备类型提供 TypeInfo 结构体，包含类初始化函数和实例初始化函数                                     |
+| Rust | 通过 `#[qom_object]` 等宏生成符合 C 约定的 extern "C" 函数，在生成的 class_init 函数中通过 FFI 调用 C 函数注册属性 |
+
+比如内存安全边界设计：
+
+| 主要设计       | 描述                                                                                                |
+|----------------|----------------------------------------------------------------------------------------------------|
+| Unsafe 边界限制 | 所有对 C 代码的直接调用必须标记为 `unsafe`，架构目标是将 `unsafe` 限制在少数底层绑定代码中             |
+| 安全抽象模式    | 底层提供 `unsafe fn raw_memory_read()` 等原始函数，上层通过安全函数包装进行边界检查、参数验证          |
+
+以及所有权与生命周期管理：
+
+| 管理思路       | 描述                                                                                                    |
+|----------------|---------------------------------------------------------------------------------------------------------|
+| 所有权系统      | 通过桥接层封装 QOM 的引用计数，利用 Rust 所有权系统自动管理原本由 C 手动管理的生命周期                      |
+| 智能指针封装    | 使用 `ObjectPtr `等结构体包装 `*mut Object` 指针，通过 `Deref`、`Clone`、`Drop trait` 实现自动引用计数管理 |
+
+我们会在后面的章节，针对 Rust for QEMU 的关键设计，展开详细讲解。
+
+## 新手快速入门
+
+目前，Rust for QEMU 的基础设施已经非常完善，对于刚接触这部分的读者，不需要成为 Rust 专家才开始研究这部分。如果读者对 QEMU 很熟悉，那么你的 QEMU C 知识将是宝贵资产，推荐研究的重点在于理解：如何用 Rust 的安全抽象调用你熟悉的 C API；如果读者刚刚接触 QEMU 也没有问题，本系列会结合 Rust 讲解 QEMU 相关的原理与概念，帮助你快速上手。
+
+!!! tips "推荐学习"
+    - 关于 QEMU 部分，推荐读者学习 [QEMU 训练营 2025 在线讲义 · 专业阶段][5]；
+    - 关于 Rust 部分，推荐读者提前掌握：所有权规则、借用规则、生命周期等常用知识。
+
+[1]: https://blog.vmsplice.net/2020/08/why-qemu-should-move-from-c-to-rust.html
+[2]: https://etherpad.opendev.org/p/KVMForum2021-QEMU+Rust-BoF
+[3]: ../../news/2025/rust-in-qemu-update-2025-10-15.md
+[4]: https://github.com/hust-open-atom-club/qemu/tree/rust-for-qemu-insides
+[5]: https://gevico.github.io/learning-qemu-docs/ch2/
diff --git a/docs/articles/ch0/02-compile-and-debug.md b/docs/articles/ch0/02-compile-and-debug.md
@@ -0,0 +1 @@
+# 开发环境搭建与调试
diff --git a/docs/articles/ch0/03-simulate-rust-model-from-zero.md b/docs/articles/ch0/03-simulate-rust-model-from-zero.md
@@ -0,0 +1 @@
+# 从零建模 Rust 设备
diff --git a/docs/index.md b/docs/index.md
@@ -4,6 +4,8 @@ Rust for QEMU Insides 是华中科技大学开放原子开源俱乐部发起的
 
 无论是虚拟化领域初学者、Rust 技术实践者，还是开源爱好者，都能从本项目中获取 QEMU 底层原理的清晰解读与 Rust 落地实践的参考案例。
 
+点击我开始正式的阅读 [Rust for QEMU 文档][docs]。
+
 !!! example "项目背景"
 
     - QEMU 的技术价值：QEMU 是开源虚拟化领域的核心工具，支持多架构硬件模拟、全系统虚拟化，但其核心代码基于 C 语言开发，存在内存安全、并发控制等工程挑战。
@@ -39,4 +41,5 @@ Rust for QEMU Insides 是华中科技大学开放原子开源俱乐部发起的
     - 文档部分（docs/ 目录）：采用 CC BY-SA 4.0 国际许可证（可共享、修改，需注明出处且以相同许可证分发）。
     - 代码部分（examples/、scripts/ 目录）：采用 MIT 许可证（可自由使用、修改、分发，需保留版权声明）。
 
+[docs]: articles/ch0/01-rust-for-qemu-introduction.md
 [contributing]: https://github.com/hust-open-atom-club/rust-for-qemu-insides/blob/main/CONTRIBUTING.md
diff --git a/docs/news/2024/rust-in-qemu-update-2024-11-26.md b/docs/news/2024/rust-in-qemu-update-2024-11-26.md
@@ -1,6 +1,6 @@
 # 2024 年 11 月 QEMU 中的 Rust 更新
 
-!!! note "主要作者"
+!!! note "主要贡献者"
 
     - 原文链接：[Rust in QEMU roadmap](https://lore.kernel.org/qemu-rust/[email protected]/)
     - 翻译：[@zevorn](https://github.com/zevorn)

diff --git a/docs/news/2025/rust-in-qemu-update-2025-01-28.md b/docs/news/2025/rust-in-qemu-update-2025-01-28.md
@@ -1,6 +1,6 @@
 # 2025 年 1 月 QEMU 中的 Rust 更新
 
-!!! note "主要作者"
+!!! note "主要贡献者"
 
     - 原文链接：[Rust in QEMU update, January 2025](https://lore.kernel.org/qemu-rust/[email protected]/)
     - 翻译：[@zevorn](https://github.com/zevorn)

diff --git a/docs/news/2025/rust-in-qemu-update-2025-05-02.md b/docs/news/2025/rust-in-qemu-update-2025-05-02.md
@@ -1,6 +1,6 @@
 # 2025 年 5 月 QEMU 中的 Rust 更新
 
-!!! note "主要作者"
+!!! note "主要贡献者"
 
     - 原文链接：[Rust in QEMU update, April 2025](https://lore.kernel.org/qemu-rust/[email protected]/)
     - 翻译：[@zevorn](https://github.com/zevorn)

diff --git a/docs/news/2025/rust-in-qemu-update-2025-07-16.md b/docs/news/2025/rust-in-qemu-update-2025-07-16.md
@@ -1,6 +1,6 @@
 # 2025 年 7 月 QEMU 中的 Rust 更新
 
-!!! note "主要作者"
+!!! note "主要贡献者"
 
     - 原文链接：[Rust in QEMU update, July 2025](https://lore.kernel.org/qemu-rust/[email protected]/)
     - 翻译：[@zevorn](https://github.com/zevorn)

diff --git a/docs/news/2025/rust-in-qemu-update-2025-10-15.md b/docs/news/2025/rust-in-qemu-update-2025-10-15.md
@@ -1,6 +1,6 @@
 # 2025 年 10 月 QEMU 中的 Rust 更新
 
-!!! note "主要作者"
+!!! note "主要贡献者"
 
     - 原文链接：[Rust in QEMU update, October 2025](https://lore.kernel.org/qemu-rust/[email protected]/)
     - 翻译：[@zevorn](https://github.com/zevorn)

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -82,7 +82,11 @@ extra_css:
 
 nav:
   - 主页: index.md
-  - 文档: articles/index.md
+  - 文档:
+    - 零、基础入门与环境搭建:
+      - 01 Rust for QEMU 概述: articles/ch0/01-rust-for-qemu-introduction.md
+      - 02 开发环境搭建与调试: articles/ch0/02-compile-and-debug.md
+      - 03 从零建模 Rust 设备: articles/ch0/03-simulate-rust-model-from-zero.md
   - 博客: blogs/index.md
   - 新闻:
     - 2025: