doc: add framework of the RustSBI Manual (#128)

* doc: add contents of the RustSBI Manual

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

* doc: add more chapters to the manual

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

* doc: add Xiangshan NEMU and Allwinner Nezha chapters

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

* doc: add chapter for OpenSBI users in the manual

Signed-off-by: guttatus <xingzhiang2020@gmail.com>

* doc: add chapter 01 'What is RustSBI'

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

* doc: add chapter 02 'RustSBI Libraries'

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

* doc: add section 'Use `rustsbi` as a Dependency Crate'

Add buildroot section for the ecosystem chapter.

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

* doc: rustsbi SBI DBCN, CPPC, RFNC extension descriptions

Add notes for first two manual chapters.

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

* doc: rustsbi SBI HSM implementation documents

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

---------

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>
Signed-off-by: guttatus <xingzhiang2020@gmail.com>
Co-authored-by: guttatus <xingzhiang2020@gmail.com>

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["The RustSBI Community"]
+language = "zh"
+multilingual = false
+src = "src"
+title = "The RustSBI Manual"

docs/src/02_libraries/01_rustsbi.md

@@ -0,0 +1,814 @@
+# `rustsbi` 核心抽象库
+
+核心抽象库 `rustsbi` 提供封装 SBI 扩展的特型（trait）、生成宏和有关的辅助结构体、常量。我们首先介绍系统软件开发者如何引入 `rustsbi` 库；其次，我们介绍所有 `rustsbi` 导出结构的使用指南。
+
+## 引入 `rustsbi` 库作为依赖包
+
+为了在使用 Cargo 的 Rust 项目中引入 `rustsbi` 库，应当将 `rustsbi` 添加到对应 `Cargo.toml` 文件的 `[dependencies]` 章节中。可以使用命令行或者手动修改文件的形式添加依赖库。同时，需要根据项目的特点选择需要的 Cargo 特性（features）。
+
+开发 RISC-V 机器态裸机固件时，需要增加 `machine` 特性，以引入裸机下的 RISC-V 环境寄存器识别操作。需要运行以下指令。
+
+```bash
+cargo add rustsbi --features machine
+```
+```toml
+# 或者，在Cargo.toml中添加以下内容（下文不再赘述）
+[dependencies]
+rustsbi = { version = "0.4.0", features = ["machine"] }
+```
+
+> 机器态裸机固件将识别的 RISC-V 环境寄存器例如 `mvendorid` 和 `mimpid`，因此只能在 RISC-V 目标下编译。
+>
+> 编译完成后，目标项目应当在机器态运行，以获得直接访问这些寄存器的权限。其它特权态的软件需获取环境寄存器内容时，应当调用 SBI 接口，而不是直接读取环境寄存器。
+
+开发虚拟化软件时，有时需要转发使用宿主机环境本身具有的 SBI 接口，此时我们增加 `forward` 特性。
+
+```bash
+cargo add rustsbi --features forward
+```
+```toml
+[dependencies]
+rustsbi = { version = "0.4.0", features = ["forward"] }
+```
+
+> 虚拟化软件运行于 RISC-V 的 HS 态。无论是 Type-1 还是 Type-2 虚拟化软件，都需要为其中运行于 VS 态的客户机系统提供 SBI 接口。然而，HS 态宿主机系统也是运行在外部提供的 SBI 接口之上；因此可能存在 SBI 转发操作。
+>
+> 当 `forward` 特性开启时，`rustsbi` 库直接调用 HS 态所处的 SBI 环境，它将使用仅支持 RISC-V 架构的 `sbi-rt` 包，因此此选项只能在 RISC-V 编译目标下编译。
+
+开发模拟器时，使用宿主 SBI 环境的需求不常见。因此，我们不增加任何特性地引入 `rustsbi` 。
+
+```bash
+cargo add rustsbi
+```
+```toml
+[dependencies]
+rustsbi = "0.4.0"
+```
+
+> 模拟器通常会提供自己的 `vendorid` 和 `impid` 等环境寄存器，以表示模拟器环境的产品标识符和版本号。不增加任何特性的 `rustsbi` 包可以在任何支持的平台下编译，不仅限于 RISC-V。
+>
+> `rustsbi` 包默认情况下不包含任何特性，即 default features 为空，不开启使用 RISC-V 汇编语言的代码特性，以适应软件测试的需求。
+
+最新的 RustSBI 版本号是 0.4.0。使用以上的命令或配置，可以依赖于最新的 RustSBI 0.4.0 版本。然而，如果需要使用其它的 RustSBI 版本，应当在 `cargo add` 命令中增加依赖包的版本号。例如：
+
+```bash
+cargo add rustsbi@0.3.2
+```
+
+不同 RustSBI 版本的特性不同，应参考对应版本的 RustSBI 手册以获取这方面的帮助。
+
+## SBI 扩展特型组合
+
+`rustsbi` 包提供代表 SBI 扩展的特型（trait），而特型的实现对应着完整 SBI 扩展的实现。这种抽象方法统一了 RustSBI 生态对 SBI 扩展和实现的描述方式，它与平台无关，扩展了 RustSBI 的应用场景。
+
+RustSBI 目前支持 RISC-V SBI 2.0 版本，具有以下扩展：DBCN（Console）、CPPC、RFNC（Fence）、HSM、IPI、NACL、PMU、SRST（Reset）、STA、SUSP和TIME（Timer）。
+
+### DBCN（Console）调试控制台扩展
+
+调试控制台扩展在 RISC-V SBI 中用于提供一个简单的文本输入、输出控制台，在 S 态操作系统驱动启动之前，临时充当早期控制台的作用，以辅助系统软件开发者的调试工作。
+
+根据 RISC-V SBI 规范标准，建议使用 UTF-8 作为控制台扩展的操作字符集。
+
+> 操作系统的驱动子系统启动后，不应再使用 SBI 调试控制台扩展。因此，SBI DBCN 扩展以兼容性为主要设计方向，不主要考虑高性能日志需求。
+> 具有高性能日志需求的系统软件应当根据驱动子系统实现使用中断、DMA 等的高性能异步控制台，而不是使用 SBI DBCN 扩展。
+
+> SBI DBCN 的用户无需添加硬件纠错位；若有必要，SBI 扩展的实现会自动处理硬件纠错逻辑。
+
+本扩展的特型描述如下。
+
+```rust
+pub trait Console {
+    // Required methods
+    fn write(&self, bytes: Physical<&[u8]>) -> SbiRet;
+    fn read(&self, bytes: Physical<&mut [u8]>) -> SbiRet;
+    fn write_byte(&self, byte: u8) -> SbiRet;
+}
+```
+
+控制台扩展具有以下的函数。
+
+#### 写字节串
+
+```rust
+fn write(&self, bytes: Physical<&[u8]>) -> SbiRet;
+```
+
+将字节串写入调试控制台。
+
+写字节串操作是异步的。若调试控制台无法接受字节串的全部内容，它将可能仅写入部分的字节串，乃至不写入任何内容。
+函数将返回实际写入调试控制台的字节串长度。
+
+函数传入 1 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `bytes` | 输入字节串的物理地址段。它包括物理基地址的高、低部分，以及字节串的长度 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 写入成功，返回实际写入的字节串长度 |
+| `SbiRet::invalid_param` | `bytes` 参数不满足物理地址段的要求，详见：物理地址段 |
+| `SbiRet::denied` | 禁止写入调试控制台 |
+| `SbiRet::failed` | 发生了 I/O 操作错误 |
+
+#### 读字节串
+
+```rust
+fn read(&self, bytes: Physical<&[u8]>) -> SbiRet;
+```
+
+从调试控制台读取字节串。
+
+读字节串操作是异步的。如果调试控制台没有字节可供读取，它将不读取任何内容。
+函数将返回从调试控制台实际读取的字节串长度。
+
+函数传入 1 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `bytes` | 读取缓冲区的物理地址段。它包括物理基地址的高、低部分，以及字节串的长度 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 读取成功，返回实际读取的字节串长度 |
+| `SbiRet::invalid_param` | `bytes` 参数不满足物理地址段的要求，详见：物理地址段 |
+| `SbiRet::denied` | 禁止从调试控制台读取 |
+| `SbiRet::failed` | 发生了 I/O 操作错误 |
+
+#### 写单个字节
+
+```rust
+fn write_byte(&self, byte: u8) -> SbiRet;
+```
+
+将单个字节写入调试控制台。
+
+单个字节写入是同步操作。若调试控制台无法写入，函数将阻塞，直到控制台能够写入单个字节。
+或者，当 I/O 操作错误，返回 `SbiRet::failed` 也是允许的。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+> 写单个字节的操作无需构建物理地址段缓冲区，有助于支持为教育、实验而设计的简单的系统软件。
+> 具有基本性能要求的工业级系统软件，通常将使用能够写字节串的 `write` 函数而不是此函数。
+
+函数传入 1 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `byte` | 需要写入调试控制台的单个字节 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 读取成功，返回 0 |
+| `SbiRet::denied` | 禁止从调试控制台读取 |
+| `SbiRet::failed` | 发生了 I/O 操作错误 |
+
+### CPPC 扩展
+
+SBI CPPC 扩展应用于实现 ACPI 的系统固件。允许通过 SBI 调用访问系统软件环境中的 CPPC 寄存器。
+
+> ACPI 代表“高级配置和电源管理接口”（Advanced Configuration and Power Management Interface），而 CPPC 代表“协作处理器性能控制”（Collaborative Processor Performance Control）。
+>
+> 对不使用 ACPI 的系统环境，固件可不实现此扩展。
+
+CPPC 寄存器定义于 ACPI 标准规范中。每个 CPPC 寄存器都具有 32 位的寄存器编号；寄存器的宽度可能是 32 位或 64 位。许多 CPPC 寄存器是可读写的，也有一些 CPPC 寄存器是只读的。
+
+> CPPC 规范保留定义只写权限的可能性，但目前还没有 CPPC 寄存器被定义为只写的。
+
+一些 CPPC 寄存器编号是保留的。探测、读取和写入保留的 CPPC 寄存器将返回错误。
+
+本扩展的特型描述如下。
+
+```rust
+pub trait Cppc {
+    // Required methods
+    fn probe(&self, reg_id: u32) -> SbiRet;
+    fn read(&self, reg_id: u32) -> SbiRet;
+    fn read_hi(&self, reg_id: u32) -> SbiRet;
+    fn write(&self, reg_id: u32, val: u64) -> SbiRet;
+}
+```
+
+CPPC 扩展具有以下的函数。
+
+#### 探测 CPPC 寄存器
+
+```rust
+fn probe(&self, reg_id: u32) -> SbiRet;
+```
+
+探测对应的 CPPC 寄存器是否已经被当前平台实现。
+
+如果此寄存器已被实现，返回它的宽度。若未被实现，返回 0。
+
+> CPPC 寄存器的位宽度可能是 32 或者 64；因此，寄存器已被实现时，函数将以 32 或 64 作为返回值。
+
+函数传入 1 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `reg_id` | 需要探测的 CPPC 寄存器编号 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 探测成功，返回宽度或者 0 |
+| `SbiRet::invalid_param` | 该寄存器是保留的 CPPC 寄存器 |
+| `SbiRet::failed` | 探测过程中发生了未指定的错误 |
+
+#### 读取 CPPC 寄存器
+
+```rust
+fn read(&self, reg_id: u32) -> SbiRet;
+```
+
+读取 CPPC 寄存器的值。
+
+若特权态（S 态）的位宽为 32，则仅返回目标寄存器值的低 32 位。
+
+> 在 RV32 平台下，应当与 `read_hi` 函数组合，以完整读取 64 位 CPPC 寄存器的内容。
+
+> 当 CPPC 寄存器未被当前平台实现时，将返回错误。若系统软件不确定平台是否实现了此寄存器，请先使用 `probe` 函数。
+
+函数传入 1 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `reg_id` | 需要读取的 CPPC 寄存器编号 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 读取成功，返回目标寄存器的值 |
+| `SbiRet::invalid_param` | 该寄存器是保留的 CPPC 寄存器 |
+| `SbiRet::not_supported` | 该寄存器未被当前平台实现 |
+| `SbiRet::denied` | CPPC 寄存器是只写的，禁止读取 |
+| `SbiRet::failed` | 读取过程中发生了未指定的错误 |
+
+#### 读取 CPPC 寄存器的高 32 位（仅限RV32）
+
+```rust
+fn read_hi(&self, reg_id: u32) -> SbiRet;
+```
+
+读取 CPPC 寄存器值的高 32 位。
+
+若特权态（S 态）的位宽大于 32（如：64 位），则返回 0。
+
+> 在 RV64 平台下，仅使用 `read` 函数即可完整读取 64 位寄存器的内容，无需配合使用 `read_hi` 函数。
+
+函数传入 1 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `reg_id` | 需要读取的 CPPC 寄存器编号 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 读取成功，返回目标寄存器的值 |
+| `SbiRet::invalid_param` | 该寄存器是保留的 CPPC 寄存器 |
+| `SbiRet::not_supported` | 该寄存器未被当前平台实现 |
+| `SbiRet::denied` | CPPC 寄存器是只写的，禁止读取 |
+| `SbiRet::failed` | 读取过程中发生了未指定的错误 |
+
+#### 写 CPPC 寄存器
+
+```rust
+fn write(&self, reg_id: u32, val: u64) -> SbiRet;
+```
+
+将新的值写入 CPPC 寄存器。
+
+> 当 CPPC 寄存器未被当前平台实现时，将返回错误。若系统软件不确定平台是否实现了此寄存器，请先使用 `probe` 函数。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+函数传入 2 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `reg_id` | 需要写入的 CPPC 寄存器编号 |
+| `val` | 新的 CPPC 寄存器值 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 写入成功，返回 0 |
+| `SbiRet::invalid_param` | 该寄存器是保留的 CPPC 寄存器 |
+| `SbiRet::not_supported` | 该寄存器未被当前平台实现 |
+| `SbiRet::denied` | CPPC 寄存器是只读的，禁止写入 |
+| `SbiRet::failed` | 写入过程中发生了未指定的错误 |
+
+### RFNC 远程栅栏扩展
+
+远程栅栏扩展允许系统软件基于缓存同步等需求，指示其它核执行特定的同步指令。
+
+可以执行的同步指令包括 `FENCE.I`、`SFENCE.VMA`。存在虚拟化 H 扩展的前提下，允许执行 `HFENCE.GVMA` 和 `HFENCE.VVMA` 同步指令。
+
+同步指令可能由基地址、区间长度约束刷新范围。
+
+> 具体来说，当 `start_addr` 和 `size` 均为 0，或 `size` 等于 `usize::MAX` 时，表示刷新完整的 TLB 快表缓存。
+
+> 开发 SBI 固件实现时，若 `size` 规定的刷新区间过长，需要执行过多条带地址参数的刷新指令时，固件实现可以转而仅执行一条不带地址参数的完整刷新栅栏指令，以减少刷新指令的执行个数。
+
+在部分远程栅栏操作中，`asid` 和 `vmid` 参数可用于指定需刷新的地址空间编号或虚拟机编号。
+
+> 注意 `asid` 为零和不指定 `asid` 是不同的。以 `SFENCE.VMA` 为例，执行 `remote_sfence_vma` 表示不指定 `asid`，而刷新所有地址空间的快表缓存；而 `remote_sfence_vma_asid` 将以 `asid` 参数指定要刷新的地址空间。前者相当于 `sfence.vma vaddr, x0`；后者相当于 `sfence.vma vaddr, asid`，其中 `asid` 不等于 `x0`。
+
+运用 `HartMask` 结构，系统软件可选择一次性刷新多个处理器核。
+
+> `HartMask` 结构用于 `hart_mask` 参数，可为远程栅栏函数选择一个或多个处理器核。它的定义详见下文。
+
+本扩展的特型描述如下。
+
+```rust
+pub trait Fence {
+    // Required methods
+    fn remote_fence_i(&self, hart_mask: HartMask) -> SbiRet;
+    fn remote_sfence_vma(
+        &self,
+        hart_mask: HartMask,
+        start_addr: usize,
+        size: usize,
+    ) -> SbiRet;
+    fn remote_sfence_vma_asid(
+        &self,
+        hart_mask: HartMask,
+        start_addr: usize,
+        size: usize,
+        asid: usize,
+    ) -> SbiRet;
+
+    // Provided methods
+    fn remote_hfence_gvma_vmid(
+        &self,
+        hart_mask: HartMask,
+        start_addr: usize,
+        size: usize,
+        vmid: usize,
+    ) -> SbiRet { ... }
+    fn remote_hfence_gvma(
+        &self,
+        hart_mask: HartMask,
+        start_addr: usize,
+        size: usize,
+    ) -> SbiRet { ... }
+    fn remote_hfence_vvma_asid(
+        &self,
+        hart_mask: HartMask,
+        start_addr: usize,
+        size: usize,
+        asid: usize,
+    ) -> SbiRet { ... }
+    fn remote_hfence_vvma(
+        &self,
+        hart_mask: HartMask,
+        start_addr: usize,
+        size: usize,
+    ) -> SbiRet { ... }
+}
+```
+
+RFNC 扩展具有以下的函数。
+
+#### 远程执行 `FENCE.I` 指令
+
+```rust
+fn remote_fence_i(&self, hart_mask: HartMask) -> SbiRet;
+```
+
+在对应的远程核上执行 `FENCE.I` 指令。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+函数传入 1 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hart_mask` | 需要选中的处理器核 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 远程执行发送成功，返回 0 |
+| `SbiRet::invalid_param` | 至少有一个被 `hart_mask` 选中的处理器核是 S 态中不可使用的 |
+| `SbiRet::failed` | 远程栅栏发生了未指定的错误 |
+
+#### 远程执行 `SFENCE.VMA` 指令
+
+```rust
+fn remote_sfence_vma(
+    &self,
+    hart_mask: HartMask,
+    start_addr: usize,
+    size: usize,
+) -> SbiRet;
+```
+
+在对应的远程核上执行 `SFENCE.VMA` 指令，以刷新所有的地址空间中 `start_addr` 和 `size` 规定的虚拟地址段。
+
+> 相当于在对应的核上执行 `sfence.vma vaddr, x0` 或 `sfence.vma x0, x0` 指令。
+>
+> 当 `start_addr` 和 `size` 均为 0，或 `size` 等于 `usize::MAX` 时，表示刷新整个地址空间，即执行 `sfence.vma x0, x0` 指令；否则，表示刷新部分地址空间，即执行多个 `sfence.vma vaddr, x0` 指令。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+函数传入 3 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hart_mask` | 需要选中的处理器核 |
+| `start_addr` | 虚拟地址段的起始地址 |
+| `size` | 虚拟地址段的长度。为 `usize::MAX`，或与 `start_addr` 均为 0 时，表示整个地址空间 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 远程执行发送成功，返回 0 |
+| `SbiRet::invalid_address` | `start_addr` 或 `size` 不合法 |
+| `SbiRet::invalid_param` | 至少有一个被 `hart_mask` 选中的处理器核是 S 态中不可使用的 |
+| `SbiRet::failed` | 远程栅栏发生了未指定的错误 |
+
+#### 指定地址空间，远程执行 `SFENCE.VMA` 指令
+
+```rust
+fn remote_sfence_vma_asid(
+    &self,
+    hart_mask: HartMask,
+    start_addr: usize,
+    size: usize,
+    asid: usize,
+) -> SbiRet;
+```
+
+在对应的远程核上执行 `SFENCE.VMA` 指令，以刷新 `asid` 规定的地址空间中，`start_addr` 和 `size` 规定的虚拟地址段。
+
+> 相当于在对应的核上执行 `sfence.vma x0, asid` 或 `sfence.vma vaddr, asid` 指令。
+
+> 当 `start_addr` 和 `size` 均为 0，或 `size` 等于 `usize::MAX` 时，表示刷新整个地址空间，执行 `sfence.vma x0, asid` 指令。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+函数传入 4 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hart_mask` | 需要选中的处理器核 |
+| `start_addr` | 虚拟地址段的起始地址 |
+| `size` | 虚拟地址段的长度。为 `usize::MAX`，或与 `start_addr` 均为 0 时，表示整个地址空间 |
+| `asid` | 规定刷新操作生效的地址空间 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 远程执行发送成功，返回 0 |
+| `SbiRet::invalid_address` | `start_addr` 或 `size` 不合法 |
+| `SbiRet::invalid_param` | 至少有一个被 `hart_mask` 选中的处理器核是 S 态中不可使用的 |
+| `SbiRet::failed` | 远程栅栏发生了未指定的错误 |
+
+#### 指定虚拟机编号，远程执行 `HFENCE.GVMA` 指令
+
+```rust
+fn remote_hfence_gvma_vmid(
+    &self,
+    hart_mask: HartMask,
+    start_addr: usize,
+    size: usize,
+    vmid: usize,
+) -> SbiRet { ... }
+```
+
+在对应的远程核上执行 `HFENCE.GVMA` 指令，以刷新 `vmid` 规定的虚拟机编号中，`start_addr` 和 `size` 规定的客户机物理地址段。
+
+> 相当于在对应的核上执行 `hfence.gvma x0, vmid` 或 `hfence.gvma gaddr, vmid` 指令。
+>
+> 当 `start_addr` 和 `size` 均为 0，或 `size` 等于 `usize::MAX` 时，表示刷新整个地址空间，执行 `hfence.gvma x0, vmid` 指令。
+
+`start_addr` 应为实际物理地址向右移动 2 位。
+
+> 代表客户机起始物理地址时，`start_addr`（对应指令中的 `gaddr`）应为实际物理地址向右移动 2 位，因为 RISC-V 在开启虚拟内存的情况下，允许物理地址位数超过虚拟地址位数 2 位。因此，远程执行的刷新指令必须要求实际物理地址以 4 字节对齐。
+
+函数只有在所有目标核都支持虚拟化 H 扩展时生效。
+
+> 若对应的远程核至少有一个不支持虚拟化 H 扩展，实现应当返回 `SbiRet::not_supported` 错误。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+函数传入 4 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hart_mask` | 需要选中的处理器核 |
+| `start_addr` | 向右移动 2 位后的物理地址段的起始地址 |
+| `size` | 物理地址段的长度，不需要向右移动 2 位。为 `usize::MAX`，或与 `start_addr` 均为 0 时，表示整个地址空间 |
+| `vmid` | 规定刷新操作生效的虚拟机编号 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 远程执行发送成功，返回 0 |
+| `SbiRet::not_supported` | 至少有一个被 `hart_mask` 选中的处理器核不支持虚拟化 H 扩展 |
+| `SbiRet::invalid_address` | `start_addr` 或 `size` 不合法 |
+| `SbiRet::invalid_param` | 至少有一个被 `hart_mask` 选中的处理器核是 S 态中不可使用的 |
+| `SbiRet::failed` | 远程栅栏发生了未指定的错误 |
+
+#### 远程执行 `HFENCE.GVMA` 指令
+
+```rust
+fn remote_hfence_gvma(
+    &self,
+    hart_mask: HartMask,
+    start_addr: usize,
+    size: usize,
+) -> SbiRet { ... }
+```
+
+在对应的远程核上执行 `HFENCE.GVMA` 指令，以刷新所有的虚拟机编号中 `start_addr` 和 `size` 规定的客户机物理地址段。
+
+> 相当于在对应的核上执行 `hfence.gvma x0, x0` 或 `hfence.gvma gaddr, x0` 指令。
+>
+> 当 `start_addr` 和 `size` 均为 0，或 `size` 等于 `usize::MAX` 时，表示刷新整个地址空间，执行 `hfence.gvma x0, x0` 指令。
+
+`start_addr` 应为实际物理地址向右移动 2 位。
+
+> 代表客户机起始物理地址时，`start_addr`（对应指令中的 `gaddr`）应为实际物理地址向右移动 2 位，因为 RISC-V 在开启虚拟内存的情况下，允许物理地址位数超过虚拟地址位数 2 位。因此，远程执行的刷新指令必须要求实际物理地址以 4 字节对齐。
+
+函数只有在所有目标核都支持虚拟化 H 扩展时生效。
+
+> 若对应的远程核至少有一个不支持虚拟化 H 扩展，实现应当返回 `SbiRet::not_supported` 错误。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+函数传入 3 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hart_mask` | 需要选中的处理器核 |
+| `start_addr` | 向右移动 2 位后的物理地址段的起始地址 |
+| `size` | 物理地址段的长度，不需要向右移动 2 位。为 `usize::MAX`，或与 `start_addr` 均为 0 时，表示整个地址空间 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 远程执行发送成功，返回 0 |
+| `SbiRet::not_supported` | 至少有一个被 `hart_mask` 选中的处理器核不支持虚拟化 H 扩展 |
+| `SbiRet::invalid_address` | `start_addr` 或 `size` 不合法 |
+| `SbiRet::invalid_param` | 至少有一个被 `hart_mask` 选中的处理器核是 S 态中不可使用的 |
+| `SbiRet::failed` | 远程栅栏发生了未指定的错误 |
+
+#### 指定地址空间，远程执行 `HFENCE.VVMA` 指令
+
+```rust
+fn remote_hfence_vvma_asid(
+    &self,
+    hart_mask: HartMask,
+    start_addr: usize,
+    size: usize,
+    asid: usize,
+) -> SbiRet { ... }
+```
+
+在对应的远程核上执行 `HFENCE.VVMA` 指令，以刷新当前虚拟机内 `asid` 规定的地址空间中，`start_addr` 和 `size` 规定的虚拟地址段。
+
+> 相当于在对应的核上执行 `hfence.vvma x0, asid` 或 `hfence.vvma vaddr, asid` 指令。当前虚拟机编号可由 `hgatp.VMID` CSR 寄存器位域获得。
+>
+> 当 `start_addr` 和 `size` 均为 0，或 `size` 等于 `usize::MAX` 时，表示刷新整个地址空间，执行 `hfence.vvma x0, asid` 指令。
+
+函数只有在所有目标核都支持虚拟化 H 扩展时生效。
+
+> 若对应的远程核至少有一个不支持虚拟化 H 扩展，实现应当返回 `SbiRet::not_supported` 错误。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+函数传入 4 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hart_mask` | 需要选中的处理器核 |
+| `start_addr` | 虚拟地址段的起始地址 |
+| `size` | 虚拟地址段的长度。为 `usize::MAX`，或与 `start_addr` 均为 0 时，表示整个地址空间 |
+| `asid` | 规定刷新操作生效的地址空间 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 远程执行发送成功，返回 0 |
+| `SbiRet::not_supported` | 至少有一个被 `hart_mask` 选中的处理器核不支持虚拟化 H 扩展 |
+| `SbiRet::invalid_address` | `start_addr` 或 `size` 不合法 |
+| `SbiRet::invalid_param` | 至少有一个被 `hart_mask` 选中的处理器核是 S 态中不可使用的 |
+| `SbiRet::failed` | 远程栅栏发生了未指定的错误 |
+
+#### 远程执行 `HFENCE.VVMA` 指令
+
+```rust
+fn remote_hfence_vvma(
+    &self,
+    hart_mask: HartMask,
+    start_addr: usize,
+    size: usize,
+) -> SbiRet { ... }
+```
+
+在对应的远程核上执行 `HFENCE.VVMA` 指令，以刷新当前虚拟机内所有地址空间中，`start_addr` 和 `size` 规定的虚拟地址段。
+
+> 相当于在对应的核上执行 `hfence.vvma x0, x0` 或 `hfence.vvma vaddr, x0` 指令。当前虚拟机编号可由 `hgatp.VMID` CSR 寄存器位域获得。
+>
+> 当 `start_addr` 和 `size` 均为 0，或 `size` 等于 `usize::MAX` 时，表示刷新整个地址空间，执行 `hfence.vvma x0, x0` 指令。
+
+函数只有在所有目标核都支持虚拟化 H 扩展时生效。
+
+> 若对应的远程核至少有一个不支持虚拟化 H 扩展，实现应当返回 `SbiRet::not_supported` 错误。
+
+本函数不具有返回值，因而 `SbiRet::success` 永远返回 0。
+
+函数传入 3 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hart_mask` | 需要选中的处理器核 |
+| `start_addr` | 虚拟地址段的起始地址 |
+| `size` | 虚拟地址段的长度。为 `usize::MAX`，或与 `start_addr` 均为 0 时，表示整个地址空间 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 远程执行发送成功，返回 0 |
+| `SbiRet::not_supported` | 至少有一个被 `hart_mask` 选中的处理器核不支持虚拟化 H 扩展 |
+| `SbiRet::invalid_address` | `start_addr` 或 `size` 不合法 |
+| `SbiRet::invalid_param` | 至少有一个被 `hart_mask` 选中的处理器核是 S 态中不可使用的 |
+| `SbiRet::failed` | 远程栅栏发生了未指定的错误 |
+
+### HSM 多核管理扩展
+
+多核管理扩展允许特权态（S 态）系统软件改变处理器核的运行状态。
+
+本扩展的特型描述如下。
+
+```rust
+pub trait Hsm {
+    // Required methods
+    fn hart_start(
+        &self,
+        hartid: usize,
+        start_addr: usize,
+        opaque: usize,
+    ) -> SbiRet;
+    fn hart_stop(&self) -> SbiRet;
+    fn hart_get_status(&self, hartid: usize) -> SbiRet;
+
+    // Provided method
+    fn hart_suspend(
+        &self,
+        suspend_type: u32,
+        resume_addr: usize,
+        opaque: usize,
+    ) -> SbiRet { ... }
+}
+```
+
+HSM 扩展具有以下的函数。
+
+#### 启动处理器核
+
+```rust
+fn hart_start(
+    &self,
+    hartid: usize,
+    start_addr: usize,
+    opaque: usize,
+) -> SbiRet;
+```
+
+启动对应处理器核到特权态（S 态）。
+
+启动处理器核到特权态后，处理器核的初始寄存器内容如下。
+
+| 寄存器 | 值 |
+|:------|:----|
+| `satp` | 0 |
+| `sstatus.SIE` | 0 |
+| `a0` | `hartid` |
+| `a1` | `opaque` 参数内容 |
+
+> 使用 HSM 扩展启动处理器核时，寄存器内容和通常的 SBI 启动流程一致。
+
+处理器核启动操作是异步的。只要 SBI 实现确保返回代码正确，启动处理器核函数可以在对应启动操作开始执行之前返回。
+
+若 SBI 实现是机器态（M 态）运行的 SBI 固件，则控制流转移到特权态（S 态）之前，它必须配置支持的任何物理内存保护机制（例如，PMP 定义的保护机制）和其它机器态（M 态）模式的状态。
+
+目标核必须具有 `start_addr` 地址指令的执行权限，否则返回错误。
+
+> 当物理内存保护机制（PMP 机制）或虚拟化 H 扩展的全局阶段（G 阶段）禁止此地址的执行操作时，`start_addr` 地址指令不具有执行权限，本函数应当返回 `SbiRet::invalid_address` 错误。
+
+函数传入 3 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hartid` | 需要启动的处理器核编号 |
+| `start_addr` | 处理器核启动时程序指针指向的物理地址 |
+| `opaque` | 处理器核启动时，`a1` 寄存器包含的值 |
+
+> 函数的 `start_addr` 参数表示物理地址，但是并不像通常的 SBI 扩展那样将物理地址分为高、低两部分。因为此时 `satp` 寄存器的内容（0）意味着内存管理单元（MMU）的虚拟内存功能一定被关闭，此时物理地址与虚拟地址的位宽相同。
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 启动成功，对应核心将从 `start_addr` 开始运行 |
+| `SbiRet::invalid_address` | `start_addr` 无效，因为：它不是合法的物理地址，或物理内存保护机制（PMP 机制）、虚拟化 H 扩展的全局阶段（G 阶段）禁止此地址的执行操作 |
+| `SbiRet::invalid_param` | `hartid` 无效，它不能启动到特权态（S 态） |
+| `SbiRet::already_available` | `hartid` 对应的核已经启动 |
+| `SbiRet::failed` | 启动过程中发生了未指定的错误 |
+
+#### 停止处理器核
+
+```rust
+fn hart_stop(&self) -> SbiRet;
+```
+
+停止当前的处理器核。
+
+> 处理器核停止后，其所有权交还到 SBI 实现。
+
+停止处理器核函数执行成功后，函数不应当返回。
+
+必须在特权态（S 态）中断关闭的情况下停止当前处理器核。
+
+> 出于此 RISC-V SBI 规范标准的约定，SBI 实现不检查特权态中断是否已经关闭。
+
+本函数没有传入参数。
+
+函数可能返回以下错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::failed` | 停止过程中发生了未指定的错误 |
+
+> 停止处理器核函数是特殊的，它不会返回 `SbiRet::success`。
+
+#### 获取处理器核的运行状态
+
+```rust
+fn hart_get_status(&self, hartid: usize) -> SbiRet;
+```
+
+返回 `hartid` 处理器核的运行状态。
+
+> 由于任何并发的 `hart_start`、`hart_stop` 或 `hart_suspend` 操作，处理器核的运行状态可能随时切换。因此，函数的返回值无法代表实时的处理器核的运行状态。
+
+> SBI 实现中，应尽可能返回最新的处理器核运行信息，以减少系统软件中异步原语的调用次数。
+
+函数传入 1 个参数：
+
+| 参数 | 说明 |
+|:----|:-----|
+| `hartid` | 需要获取状态的处理器核编号 |
+
+函数可能返回以下内容或错误：
+
+| 返回值 | 说明 |
+|:----|:-----|
+| `SbiRet::success` | 获取成功，返回对应处理器核的运行状态 |
+| `SbiRet::invalid_param` | `hartid` 无效 |
+
+#### 暂停处理器核
+
+### IPI 核间中断扩展
+
+### NACL 嵌套虚拟化加速扩展
+
+### PMU 性能监测扩展
+
+### SRST（Reset）系统重置扩展
+
+### STA 丢失时间扩展
+
+### SUSP 系统挂起扩展
+
+### TIME（Timer）时钟扩展
+
+## `EnvInfo` 特型
+
+## 结构体
+
+## 辅助常量
+
+## 宏 `#[derive(RustSBI)]`

docs/src/02_libraries/02_sbi_rt.md

@@ -0,0 +1 @@
+# sbi-rt 特权态运行环境

docs/src/02_libraries/03_sbi_spec.md

@@ -0,0 +1 @@
+# sbi-spec 常量与常数库

docs/src/02_libraries/04_sbi_testing.md

@@ -0,0 +1 @@
+# sbi-testing 测试环境库

docs/src/03_prototyper/01_introduction.md

@@ -0,0 +1 @@
+# 简介、应用场景与生态软件适配

docs/src/03_prototyper/02_configuration.md

@@ -0,0 +1 @@
+# 编译与配置

docs/src/03_prototyper/03_debugging.md

@@ -0,0 +1 @@
+# 调试 RustSBI Prototyper

docs/src/03_prototyper/04_for_opensbi_user.md

@@ -0,0 +1 @@
+# 给OpenSBI用户的RustSBI Prototyper教程

docs/src/04_hal/allwinner.md

@@ -0,0 +1 @@
+# allwinner-hal 全志芯片支持包

docs/src/04_hal/bouffalo.md

@@ -0,0 +1 @@
+# bouffalo-hal 博流芯片支持包

docs/src/04_hal/hpmicro.md

@@ -0,0 +1 @@
+# hpmicro-hal 先楫芯片支持包

docs/src/04_hal/kendryte.md

@@ -0,0 +1 @@
+# kendryte-hal 勘智芯片支持包

docs/src/04_hal/others.md

@@ -0,0 +1 @@
+# 其它 RustSBI 贡献的支持包

docs/src/04_hal/sophgo.md

@@ -0,0 +1 @@
+# sophgo-hal 算能芯片支持包

docs/src/05_platform/allwinner_nezha.md

@@ -0,0 +1 @@
+# Allwinner Nezha D1-H 平台

docs/src/05_platform/milkv_duo.md

@@ -0,0 +1 @@
+# Milk-V Duo 开发板

docs/src/05_platform/qemu_virt.md

@@ -0,0 +1 @@
+# QEMU virt 模拟器平台

docs/src/05_platform/sipeed_m1s_dock.md

@@ -0,0 +1 @@
+# Sipeed M1s Dock 开发板

docs/src/05_platform/xiangshan_nemu.md

@@ -0,0 +1 @@
+# 香山 NEMU 模拟器平台

docs/src/06_os/arceos.md

@@ -0,0 +1 @@
+# ArceOS 操作系统

docs/src/06_os/arch_linux.md

@@ -0,0 +1 @@
+# Arch Linux 操作系统

docs/src/06_os/asterinas.md

@@ -0,0 +1 @@
+# Asterinas 操作系统

docs/src/06_os/dragonos.md

@@ -0,0 +1 @@
+# DragonOS 操作系统

docs/src/06_os/fedora.md

@@ -0,0 +1 @@
+# Fedora 操作系统

docs/src/06_os/freebsd.md

@@ -0,0 +1 @@
+# FreeBSD 操作系统

docs/src/06_os/linux_kernel.md

@@ -0,0 +1 @@
+# Linux 内核（不基于发行版）

docs/src/06_os/openeuler.md

@@ -0,0 +1 @@
+# openEuler 操作系统

docs/src/06_os/openwrt.md

@@ -0,0 +1 @@
+# OpenWrt 操作系统

docs/src/06_os/polyos.md

@@ -0,0 +1 @@
+# PolyOS 操作系统

docs/src/06_os/rcore.md

@@ -0,0 +1 @@
+# rCore 操作系统

docs/src/06_os/rustsbi_test_kernel.md

@@ -0,0 +1 @@
+# RustSBI 测试用内核

docs/src/06_os/ubuntu.md

@@ -0,0 +1 @@
+# Ubuntu 操作系统

docs/src/07_development/emulator.md

@@ -0,0 +1 @@
+# 提供 SBI 服务的指令集模拟器

docs/src/07_development/new-platform-prototyper.md

@@ -0,0 +1 @@
+# 为 Prototyper 适配新的裸机平台

docs/src/07_development/sbi-kernel.md

@@ -0,0 +1 @@
+# 开发基于 SBI 的系统内核

docs/src/07_development/vmm.md

@@ -0,0 +1 @@
+# RISC-V H 扩展虚拟化宿主系统

docs/src/08_incubating/arceboot.md

@@ -0,0 +1 @@
+# ArceBoot 特权态引导程序

docs/src/08_incubating/rustsbi_agent.md

@@ -0,0 +1 @@
+# RustSBI Agent 大模型问答智能体

docs/src/09_ecosystem/buildroot.md

@@ -0,0 +1 @@
+# Buildroot RustSBI 解决方案

docs/src/09_ecosystem/oreboot.md

@@ -0,0 +1 @@
+# Oreboot LinuxBoot 引导解决方案

docs/src/09_ecosystem/zsbl.md

@@ -0,0 +1 @@
+# 零阶段引导程序

docs/src/10_oss_guide/01_usage.md

@@ -0,0 +1 @@
+# 代码获取与构建

docs/src/10_oss_guide/02_contribution.md

@@ -0,0 +1 @@
+# 贡献流程规范

docs/src/10_oss_guide/03_development.md

@@ -0,0 +1 @@
+# 开发规范

docs/src/10_oss_guide/04_community.md

@@ -0,0 +1 @@
+# 社区资源

docs/src/SUMMARY.md

@@ -0,0 +1,61 @@
+# Summary
+
+- [什么是 RustSBI？](./chapter_01_what_is_rustsbi.md)
+- [RustSBI 核心库](./chapter_02_libraries.md)
+    - [`rustsbi` 核心抽象库](./02_libraries/01_rustsbi.md)
+    - [`sbi-rt` 特权态运行环境](./02_libraries/02_sbi_rt.md)
+    - [`sbi-spec` 常量与常数库](./02_libraries/03_sbi_spec.md)
+    - [`sbi-testing` 测试环境库](./02_libraries/04_sbi_testing.md)
+- [RustSBI Prototyper](./chapter_03_prototyper.md)
+    - [简介、应用场景与生态软件适配](./03_prototyper/01_introduction.md)
+    - [编译与配置](./03_prototyper/02_configuration.md)
+    - [调试 RustSBI Prototyper](./03_prototyper/03_debugging.md)
+    - [给 OpenSBI 用户的 RustSBI Prototyper 教程](./03_prototyper/04_for_opensbi_user.md)
+- [RustSBI 维护的裸机支持包](./chapter_04_hal.md)
+    - [`allwinner-hal` 全志芯片支持包](./04_hal/allwinner.md)
+    - [`bouffalo-hal` 博流芯片支持包](./04_hal/bouffalo.md)
+    - [`hpmicro-hal` 先楫芯片支持包](./04_hal/hpmicro.md)
+    - [`kendryte-hal` 勘智芯片支持包](./04_hal/kendryte.md)
+    - [`sophgo-hal` 算能芯片支持包](./04_hal/sophgo.md)
+    - [其它 RustSBI 贡献的支持包](./04_hal/others.md)
+- [平台用户指南](./chapter_05_platform.md)
+    - [QEMU virt 模拟器平台](./05_platform/qemu_virt.md)
+    - [香山 NEMU 模拟器平台](./05_platform/xiangshan_nemu.md)
+    - [Sipeed M1s Dock 开发板](./05_platform/sipeed_m1s_dock.md)
+    - [Allwinner Nezha D1-H 平台](./05_platform/allwinner_nezha.md)
+    - [Milk-V Duo 开发板](./05_platform/milkv_duo.md)
+- [系统内核与发行版用户指南](./chapter_06_os.md)
+    - [Linux 内核（不基于发行版）](./06_os/linux_kernel.md)
+    - [Arch Linux 操作系统](./06_os/arch_linux.md)
+    - [Fedora 操作系统](./06_os/fedora.md)
+    - [FreeBSD 操作系统](./06_os/freebsd.md)
+    - [openEuler 操作系统](./06_os/openeuler.md)
+    - [OpenWrt 操作系统](./06_os/openwrt.md)
+    - [PolyOS 操作系统](./06_os/polyos.md)
+    - [Ubuntu 操作系统](./06_os/ubuntu.md)
+    - [ArceOS 操作系统](./06_os/arceos.md)
+    - [DragonOS 操作系统](./06_os/dragonos.md)
+    - [Asterinas 操作系统](./06_os/asterinas.md)
+    - [rCore 操作系统](./06_os/rcore.md)
+    - [RustSBI 测试用内核](./06_os/rustsbi_test_kernel.md)
+- [RustSBI 开发实战](./chapter_07_development.md)
+    - [开发基于 SBI 的系统内核](./07_development/sbi-kernel.md)
+    - [RISC-V H 扩展虚拟化宿主系统](./07_development/vmm.md)
+    - [提供 SBI 服务的指令集模拟器](./07_development/emulator.md)
+    - [为 Prototyper 适配新的裸机平台](./07_development/new-platform-prototyper.md)
+- [孵化中的 RustSBI 项目](./chapter_08_incubating.md)
+    - [RustSBI Agent 大模型问答智能体](./08_incubating/rustsbi_agent.md)
+    - [ArceBoot 特权态引导程序](./08_incubating/arceboot.md)
+- [引导生态简介](./chapter_09_ecosystem.md)
+    - [Oreboot LinuxBoot 引导解决方案](./09_ecosystem/oreboot.md)
+    - [Buildroot RustSBI 解决方案](./09_ecosystem/buildroot.md)
+    - [零阶段引导程序](./09_ecosystem/zsbl.md)
+- [开放源代码指南](./chapter_10_oss_guide.md)
+    - [代码获取与构建](./10_oss_guide/01_usage.md)
+    - [贡献流程规范](./10_oss_guide/02_contribution.md)
+    - [开发规范](./10_oss_guide/03_development.md)
+    - [社区资源](./10_oss_guide/04_community.md)
+- [参考文献](./references.md)
+- [附录](./appendix.md)
+    - [常见故障与错误码速查表](./appendix/error_code.md)
+    - [010 Editor Scripts 固件格式分析工具](./appendix/010_editor_scripts.md)

docs/src/appendix.md

@@ -0,0 +1 @@
+# 附录

docs/src/appendix/010_editor_scripts.md

@@ -0,0 +1 @@
+# 010 Editor Scripts 固件格式分析工具

docs/src/appendix/error_code.md

@@ -0,0 +1 @@
+# 常见故障与错误码速查表

docs/src/chapter_01_what_is_rustsbi.md

@@ -0,0 +1,42 @@
+# 什么是 RustSBI？
+
+![logo](https://avatars.githubusercontent.com/u/85245528?s=400)
+
+感谢您选择 RustSBI！RustSBI 是一款综合的安全引导解决方案。RustSBI 主要由 Rust 语言编写，适用于 RISC-V 的 Supervisor Binary Interface（SBI）架构，是遵守 MIT 或 Mulan-PSL v2 双协议发布的开源软件。RustSBI 在有效提升 RISC-V SBI 接口软件开发效率的同时，提供可供下载的二进制固件包和多种生态软件整合方案，并包含大模型 Agent 应用模块，便于用户使用和二次开发。
+
+RustSBI 目前支持 RISC-V SBI 2.0 正式版，并已被 RISC-V 基金会收录为官方推荐的 RISC-V SBI 实现之一，它的实现编号为 4。
+
+## RISC-V SBI 与 RustSBI
+
+在 RISC-V 架构中，特权级分为用户态（U-Mode）、内核态（S-Mode）和机器态（M-Mode）。其中，内核态运行的环境应当具有 SBI 接口，以支持内核启动和运行的必需基础功能；这一环境在裸机上通常由机器态（M-Mode）提供，通常称作 SBI 固件。在裸机平台上，SBI 固件具有引导、调试和可信环境的功能，可通过通用和专有 SBI 接口等多种形式实现，以支持内核态系统软件的正常运行。
+
+> 出于 M/S 态边界是 RISC-V 安全架构的重要组成部分，“SBI 固件”起到的作用包括系统基础功能、安全性功能和调试功能等，并非“特权级切换”这样简单。鉴于此，考虑到 RISC-V 生态的一致性，SBI 固件是不可或缺的。若忽略 SBI 固件而直接在 M 态上开发系统，会遇到大量与已有生态不符的兼容性问题，因此不建议 M/S/U 模型的裸机硬件不安装 SBI 固件而直接使用。
+
+考虑到虚拟化环境时，虚拟化宿主态（HS-Mode）环境也可提供 SBI 接口，用于取代机器态，支持位于其中的虚拟机系统正常运行。此时，内核运行于虚拟内核态（VS-Mode），运用虚拟化软件提供的 SBI 接口等功能运行于虚拟化平台。
+
+模拟器使得内核的开发、验证工作不受宿主平台的限制。与裸机硬件相同，RISC-V 模拟器仍然需要为运行于其中的系统软件提供 SBI 接口等支持功能。RISC-V 模拟器运行于各个宿主平台，有的提供机器态（M-Mode）模拟运行环境，也有的提供内核态（S-Mode）运行环境。
+
+RustSBI 项目可同时适用于裸机固件、虚拟化环境和模拟器的开发工作。RustSBI Prototyper 是 RustSBI 提供的裸机固件实现，以动态固件等多种形式提供裸机 SBI 固件的实现方案，可与不同的引导生态软件配合使用。当开发虚拟化环境和模拟器时，RustSBI 提供了不同风格的依赖库，并展示从实际需求出发的样例程序，以简化 SBI 接口代码的开发工作。
+
+## 使用 Rust 语言开发
+
+RustSBI 项目使用可靠、安全的 Rust 语言。RustSBI 项目在发布前经过多项软件测试，包括单元测试、集成测试，并具有专用的测试用内核框架。视应用场景而定，RustSBI 提供从裸机固件到依赖库的多种实现方案，具有一定的可扩展性，每个库都具有详细的 Rust 文档和测试用例，供用户和开发者自由选择和参考。
+
+需要注意的是，即便 RustSBI 的各个方案都以 Rust 语言实现，并非意味着 RustSBI 仅能引导和支持 Rust 语言的操作系统。RustSBI 可支持包括 C 语言在内的多种高级语言操作系统，只要它遵守 RISC-V SBI 规范标准。其它编程语言的软件也可启动 RustSBI 的功能模块，如裸机固件和测试用内核等，因为它们的开发过程都严格遵守 RISC-V SBI 规范标准和相关行业标准。
+
+> 除了 RustSBI 之外，支持 SBI 标准规范的常见裸机固件还有：OpenSBI、BBL 和 Coreboot/Oreboot 等；虚拟化软件有 Hypercraft 等。符合 SBI 规范的操作系统内核多达十余种，包括 Linux 内核、ArceOS、Asterinas 和 DragonOS 等。它们都可以用 C 和 Rust 等系统级编程语言编写。
+
+## 项目组成
+
+RustSBI 项目由以下模块构成。
+
+- 根基础服务与技术标准模块：由 RustSBI 标准结构、算法和操作系统支持包组成；
+- 裸机固件支持包模块：由 RustSBI Prototyper 裸机引导程序固件项目组成；
+- 平台支持模块：由各芯片系列的裸机硬件抽象层（HAL）支持包组成，与 Rust 生态共享支持模块；
+- 大模型应用：由 RustSBI Agent 问答智能体等项目组成。
+
+在第二章中，我们将详细介绍 RustSBI 的核心库，它具有核心抽象、函数和常量支持等多个功能，便于开发模拟器和虚拟化平台。第三章将主要介绍 RustSBI Prototyper 裸机引导程序，它可在裸机平台运行，支持运行于真实硬件和模拟器的裸机操作系统。第四章介绍平台支持模块，它构成组件化的驱动程序，同时运用于 RustSBI 和 Rust 系统软件生态，具有相关的支持程序。
+
+在产品介绍之后，各平台、系统支持将于第五章、第六章介绍。第七章将详细阐述如何运用 RustSBI 开发系统软件开发者所需的软件包模块；第八章介绍 RustSBI 孵化中的子项目群，如 RustSBI Agent 等大模型应用和 ArceBoot 引导程序。第九章介绍如何将 RustSBI 与生态中的各个引导软件联动使用，例如与 Oreboot 或 Buildroot 联合使用；第十章介绍 RustSBI 开源社区生态和贡献方法。
+
+让我们开始吧！

docs/src/chapter_02_libraries.md

@@ -0,0 +1,25 @@
+# RustSBI 核心库
+
+本章将详细介绍 RustSBI 核心库的架构设计与功能模块。
+
+> RustSBI 核心库通常用于开发 SBI 生态的系统软件。若需要寻找 RustSBI 提供的 SBI 固件以供下载、安装到真实硬件主板或模拟器，请参阅第三章 RustSBI Prototyper 项目。
+
+RustSBI 核心库采用分层设计理念，将核心功能与机器态实现解耦，通过多个功能模块化的 Rust 包（crate）为 RISC-V SBI 生态提供支持。其模块化架构适用于内核开发、安全固件设计、虚拟化方案及模拟器等不同场景，并不仅限于机器态 RISC-V 固件。它主要包含以下核心组件：
+
+1. [`rustsbi` SBI 服务抽象层](02_libraries/01_rustsbi.md)
+
+    该包通过特型（trait）机制抽象 SBI 扩展功能，并提供宏编程支持。开发者在构建裸机固件时，只需为平台结构体实现相应的 SBI 扩展 trait，再通过 `#[derive(RustSBI)]` 宏即可自动生成从异常处理到 SBI 调用的分发逻辑，显著降低 SBI 底层开发的复杂程度。针对虚拟化场景，支持为虚拟机单独实现扩展或通过 `Forward` 机制透传宿主机扩展。对于非 RISC-V 架构的模拟器，可利用宿主平台特性跨架构地提供 SBI 运行环境。
+
+2. `sbi-rt` 内核态最小运行环境
+
+    为操作系统内核、虚拟化监控程序等特权级软件提供符合人体工程学的 SBI 接口封装。通过类型安全的 Rust 函数替代易出错的裸常量操作和内联汇编。通过 `sbi-rt` ，开发者可直接调用标准化的 SBI 服务接口。该模块有效提升系统软件开发效率，同时保障代码的可靠性与可维护性。
+
+3. `sbi-spec` 规范基础设施
+
+    作为 RustSBI 生态的基石，提供完整的 SBI 规范常量体系（EID/FID）、标准数据结构定义及严格的静态类型校验。通过编译期检查机制预防常量误用和数据结构错位，确保实现与 RISC-V 国际标准的严格一致性。
+
+4. `sbi-testing` 自动化测试框架
+
+    专为裸机环境设计的 SBI 合规性测试解决方案。该框架预置标准化测试流程，支持快速构建符合 SBI 规范的测试内核，通过自动化测试用例执行生成合规性报告，显著降低测试套件的重复开发成本。
+
+需要特别说明的是，RustSBI 核心库聚焦于跨平台抽象层和开发工具链，不包含具体硬件平台的机器态实现。如需获取可直接部署的 RISC-V SBI 固件，请参阅第三章提供的硬件适配方案。

docs/src/chapter_03_prototyper.md

@@ -0,0 +1 @@
+# RustSBI Prototyper

docs/src/chapter_04_hal.md

@@ -0,0 +1 @@
+# RustSBI 维护的裸机支持包

docs/src/chapter_05_platform.md

@@ -0,0 +1 @@
+# 平台用户指南

docs/src/chapter_06_os.md

@@ -0,0 +1 @@
+# 系统内核与发行版用户指南

docs/src/chapter_07_development.md

@@ -0,0 +1 @@
+# RustSBI 开发实战

docs/src/chapter_08_incubating.md

@@ -0,0 +1 @@
+# 孵化中的 RustSBI 项目

docs/src/chapter_09_ecosystem.md

@@ -0,0 +1 @@
+# 引导生态简介

docs/src/chapter_10_oss_guide.md

@@ -0,0 +1 @@
+# 开放源代码指南

docs/src/references.md

@@ -0,0 +1 @@
+# 参考文献