doc: rustsbi SBI DBCN, CPPC, RFNC extension descriptions

Add notes for first two manual chapters.

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

docs/src/02_libraries/01_rustsbi.md

@@ -1,6 +1,6 @@
 # `rustsbi` 核心抽象库
 
-核心抽象库 `rustsbi` 提供封装 SBI 扩展的特型（trait）、生成宏和有关的辅助结构体、常量。我们首先介绍系统软件开发者如何引入 `rustsbi` 库；其次，我们介绍所有的 `rustsbi` 代码成员。
+核心抽象库 `rustsbi` 提供封装 SBI 扩展的特型（trait）、生成宏和有关的辅助结构体、常量。我们首先介绍系统软件开发者如何引入 `rustsbi` 库；其次，我们介绍所有 `rustsbi` 导出结构的使用指南。
 
 ## 引入 `rustsbi` 库作为依赖包
 
@@ -57,10 +57,619 @@ cargo add rustsbi@0.3.2
 
 不同 RustSBI 版本的特性不同，应参考对应版本的 RustSBI 手册以获取这方面的帮助。
 
-## 代码成员
+## SBI 扩展特型组合
 
-### 特型（trait）组合
+`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` | 写入过程中发生了未指定的错误 |
+
+### 远程栅栏扩展
+
+远程栅栏扩展允许系统软件基于缓存同步等需求，指示其它核执行特定的同步指令。
+
+可以执行的同步指令包括 `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 { ... }
+}
+```
+
+#### 远程执行 `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`（对应指令中的 `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`（对应指令中的 `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` | 远程栅栏发生了未指定的错误 |
+
+### 多核管理扩展
+
+### 核间中断扩展
+
+### 嵌套虚拟化加速扩展
+
+### 性能监测扩展
+
+### 系统重置扩展
+
+### 丢失时间扩展
+
+### 系统挂起扩展
+
+### 时钟扩展
+
+## `EnvInfo` 特型
+
+## 结构体
+
+## 辅助常量
+
+## 宏 `#[derive(RustSBI)]`

docs/src/chapter_01_what_is_rustsbi.md

@@ -10,6 +10,8 @@ RustSBI 目前支持 RISC-V SBI 2.0 正式版，并已被 RISC-V 基金会收录
 
 在 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）运行环境。
@@ -22,6 +24,8 @@ RustSBI 项目使用可靠、安全的 Rust 语言。RustSBI 项目在发布前
 
 需要注意的是，即便 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 项目由以下模块构成。

docs/src/chapter_02_libraries.md

@@ -2,6 +2,8 @@
 
 本章将详细介绍 RustSBI 核心库的架构设计与功能模块。
 
+> RustSBI 核心库通常用于开发 SBI 生态的系统软件。若需要寻找 RustSBI 提供的 SBI 固件以供下载、安装到真实硬件主板或模拟器，请参阅第三章 RustSBI Prototyper 项目。
+
 RustSBI 核心库采用分层设计理念，将核心功能与机器态实现解耦，通过多个功能模块化的 Rust 包（crate）为 RISC-V SBI 生态提供支持。其模块化架构适用于内核开发、安全固件设计、虚拟化方案及模拟器等不同场景，并不仅限于机器态 RISC-V 固件。它主要包含以下核心组件：
 
 1. [`rustsbi` SBI 服务抽象层](02_libraries/01_rustsbi.md)