diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0092b41..f67927d 100644 --- 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 new file mode 100644 index 0000000..a22ad63 --- /dev/null +++ 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/ \ No newline at end of file diff --git a/docs/articles/ch0/02-compile-and-debug.md b/docs/articles/ch0/02-compile-and-debug.md new file mode 100644 index 0000000..e58c659 --- /dev/null +++ b/docs/articles/ch0/02-compile-and-debug.md @@ -0,0 +1 @@ +# 开发环境搭建与调试 \ No newline at end of file diff --git a/docs/articles/ch0/03-simulate-rust-model-from-zero.md b/docs/articles/ch0/03-simulate-rust-model-from-zero.md new file mode 100644 index 0000000..a46a111 --- /dev/null +++ b/docs/articles/ch0/03-simulate-rust-model-from-zero.md @@ -0,0 +1 @@ +# 从零建模 Rust 设备 \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index 9a2c39c..61a4118 100644 --- 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 \ No newline at end of file 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 index 6a38f2b..e08b4ce 100644 --- 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/cc40943e-dec1-4890-a1d9-579350ce296f@pbonzini.local/) - 翻译：[@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 index 6f5571a..7e3a854 100644 --- 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/17ad81c3-98fc-44c2-8f65-f5e2cc07030b@gnu.org/) - 翻译：[@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 index f75ee9c..36cb417 100644 --- 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/d3d1944e-2482-4aa7-b621-596246a08107@gnu.org/) - 翻译：[@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 index 13f886e..0845b11 100644 --- 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/c2342e56-b6d8-4115-8318-d8047a46f1ad@redhat.com/) - 翻译：[@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 index 196eeae..60b42cc 100644 --- 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/20251015112139.1197033-1-pbonzini@redhat.com/) - 翻译：[@zevorn](https://github.com/zevorn) diff --git a/mkdocs.yml b/mkdocs.yml index 0c84129..8aa3ebd 100644 --- 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: