doc: improve documents of ipi, hsm and library root modules

Signed-off-by: luojia65 <[email protected]>

CHANGELOG.md

@@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Change to asynchronous lock structure trait style
 - Function `num_counters` returns `usize` and its SBI call must return `SBI_SUCCESS`
 - Use amo mutex for legacy stdio handler; remove dependency on `lazy_static` and `spin`
+- Improve documents to adapt to v1.0-rc2 specification
 
 ### Fixed
 - Test kernel console now will lock before `println` line is finished

src/ecall/rfence.rs

@@ -41,7 +41,7 @@ pub fn handle_ecall_rfence(
 // If None = max_hart_id(), that means IPI extension is not supported.
 // In RustSBI, RFENCE support requires an IPI support is implemented.
 // If platform does not provide IPI support, RustSBI will disable RFENCE
-// interface access from supervisor level.
+// interface access from SBI environment caller.
 
 #[inline]
 fn remote_fence_i(hart_mask: usize, hart_mask_base: usize) -> SbiRet {

src/hsm.rs

@@ -45,7 +45,7 @@ use crate::ecall::SbiRet;
 pub trait Hsm: Send {
     /// Request the SBI implementation to start executing the given hart at specified address in supervisor-mode.
     ///
-    /// This call is asynchronous — more specifically, the `sbi_hart_start()` may return before target hart
+    /// This call is asynchronous - more specifically, the `sbi_hart_start()` may return before target hart
     /// starts executing as long as the SBI implemenation is capable of ensuring the return code is accurate.
     ///
     /// It is recommended that if the SBI implementation is a platform runtime firmware executing in machine-mode (M-mode)
@@ -59,7 +59,7 @@ pub trait Hsm: Send {
     ///
     /// # Behavior
     ///
-    /// The target hart jumps to supervisor-mode at address specified by `start_addr` with following values in specific registers.
+    /// The target hart jumps to supervisor mode at address specified by `start_addr` with following values in specific registers.
     ///
     /// | Register Name | Register Value
     /// |:--------------|:--------------
@@ -163,7 +163,7 @@ pub trait Hsm: Send {
     /// | 0x80000000              | Default non-retentive suspend
     /// | 0x80000001 - 0x8FFFFFFF | _Reserved for future use_
     /// | 0x90000000 - 0xFFFFFFFF | Platform specific non-retentive suspend
-    /// | > 0xFFFFFFFF            | _Reserved (and non-existent on RV32)_
+    /// | > 0xFFFFFFFF            | _Reserved_
     ///
     /// The `resume_addr` parameter points to a runtime-specified physical address,
     /// where the hart can resume execution in supervisor-mode after a non-retentive

src/ipi.rs

@@ -9,7 +9,7 @@ pub trait Ipi: Send {
     fn max_hart_id(&self) -> usize;
     /// Send an inter-processor interrupt to all the harts defined in `hart_mask`.
     ///
-    /// Interprocessor interrupts manifest at the receiving harts as the supervisor software interrupts.
+    /// Inter-processor interrupts manifest at the receiving harts as the supervisor software interrupts.
     ///
     /// # Return value
     ///

src/lib.rs

@@ -98,25 +98,42 @@
 //! }
 //! ```
 //!
-//! # Where can I get RustSBI binary file for XX platform?
+//! # Non-features
 //!
-//! RustSBI is designed to be a library, thus will not provide any binary files to specific platforms.
-//! Instead, chip or board manufacturers should provide their own SBI implementation project using RustSBI as a dependency.
+//! RustSBI is designed to strictly adapt to the RISC-V Supervisor Binary Interface specification.
+//! Other features useful in developing kernels and hypervisors maybe included in other Rust
+//! ecosystem crates other than this package.
 //!
-//! The reason RustSBI group will not provide actual binary implementation is that,
-//! SBI feature demands are different among users, one feature would be useful for this user,
-//! but it will be considered not useful and takes up lots of flash room for other users.
+//! ## Hardware discovery and feature detection
+//!
+//! According to the RISC-V SBI specification, SBI does not specify any method for hardware discovery.
+//! The supervisor software must rely on the other industry standard hardware
+//! discovery methods (i.e. Device Tree or ACPI) for that.
+//!
+//! To detect any feature under bare metal or under supervisor level, developers may depend on
+//! any hardware discovery methods, or use try-execute-trap method to detect any instructions or
+//! CSRs. If SBI is implemented in user level emulators, it may requires to depend on operating
+//! system calls or use the signal trap method to detect any RISC-V core features.
+//!
+//! ## Where can I get RustSBI binary file for XX platform?
+//!
+//! RustSBI is designed to be a library instead of providing any binary files to specific platforms.
+//! Chip or board manufacturers should provide their own SBI implementation project using RustSBI as a dependency.
 //!
 //! The RustSBI team provides reference implementation for several platforms, but they are for evaluation
-//! and should not be used in production.
-//! RustSBI itself cannot decide for all arbitrary users, so developers are encouraged to write their own
-//! SBI implementation, other than use reference implementation directly when in production.
+//! only and should not be used in production.
+//! RustSBI itself cannot decide for all arbitrary users, so developers are encouraged to use RustSBI
+//! as a Rust crate dependency to support their own SBI implementation,
+//! other than use reference implementation directly when in production.
+//! SBI feature demands are different among users, one feature would be useful for this user,
+//! but it will be considered not useful and takes up lots of flash room for other users.
 //!
-//! Also, RustSBI is not designed to include all platforms available in official repository.
+//! RustSBI is not designed to include all platforms available in official repository.
 //! For an actual platform users may consult board or SoC manufacturer other than RustSBI repository itself.
 //!
 //! The reason to that is that if some repository includes all platforms it support,
-//! there could be lots of non technical reasons that will bar developers from merging into main or upstream branches.
+//! there could be lots of non technical reasons that will bar one or a certain group of developers
+//! from merging their code into main or upstream branches.
 //! For example, if a draft version of actual platform is produced, it will mean to write for one draft version as well
 //! as long as this software is under maintenance. As software developer may not want to write for it,
 //! it's better to include minimal feature in core repository, and leave other features for downstream developers.

src/rfence.rs

@@ -20,7 +20,7 @@ pub trait Rfence: Send {
     /// Returns `SBI_SUCCESS` when remote fence was sent to all the targeted harts successfully.
     fn remote_fence_i(&self, hart_mask: HartMask) -> SbiRet;
     /// Instructs the remote harts to execute one or more `SFENCE.VMA` instructions,
-    /// covering the range of virtual addresses between start and size.
+    /// covering the range of virtual addresses between `start_addr` and `size`.
     ///
     /// # Return value
     ///
@@ -32,7 +32,8 @@ pub trait Rfence: Send {
     /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
     fn remote_sfence_vma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet;
     /// Instruct the remote harts to execute one or more `SFENCE.VMA` instructions,
-    /// covering the range of virtual addresses between start and size. This covers only the given `ASID`.
+    /// covering the range of virtual addresses between `start_addr` and `size`.
+    /// This covers only the given address space by `asid`.
     ///
     /// # Return value
     ///
@@ -50,7 +51,8 @@ pub trait Rfence: Send {
         asid: usize,
     ) -> SbiRet;
     /// Instruct the remote harts to execute one or more `HFENCE.GVMA` instructions,
-    /// covering the range of guest physical addresses between start and size only for the given `VMID`.
+    /// covering the range of guest physical addresses between `start_addr` and `size`
+    /// only for the given virtual machine by `vmid`.
     ///
     /// This function call is only valid for harts implementing hypervisor extension.
     ///
@@ -74,7 +76,8 @@ pub trait Rfence: Send {
         SbiRet::not_supported()
     }
     /// Instruct the remote harts to execute one or more `HFENCE.GVMA` instructions,
-    /// covering the range of guest physical addresses between start and size for all the guests.
+    /// covering the range of guest physical addresses between `start_addr` and `size`
+    /// for all the guests.
     ///
     /// This function call is only valid for harts implementing hypervisor extension.
     ///
@@ -85,16 +88,17 @@ pub trait Rfence: Send {
     /// | Return code               | Description
     /// |:--------------------------|:----------------------------------------------
     /// | SBI_SUCCESS               | Remote fence was sent to all the targeted harts successfully.
-    /// | SBI_ERR_NOT_SUPPORTED     | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
+    /// | SBI_ERR_NOT_SUPPORTED     | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
     /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
     fn remote_hfence_gvma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet {
         drop((hart_mask, start_addr, size));
         SbiRet::not_supported()
     }
     /// Instruct the remote harts to execute one or more `HFENCE.VVMA` instructions,
-    /// covering the range of guest virtual addresses between start and size for the given `ASID` and current `VMID` (in `hgatp` CSR)
+    /// covering the range of guest virtual addresses between `start_addr` and `size` for the given
+    /// address space by `asid` and current virtual machine (by `vmid` in `hgatp` CSR)
     /// of calling hart.
-    ///  
+    ///
     /// This function call is only valid for harts implementing hypervisor extension.
     ///
     /// # Return value
@@ -104,7 +108,7 @@ pub trait Rfence: Send {
     /// | Return code               | Description
     /// |:--------------------------|:----------------------------------------------
     /// | SBI_SUCCESS               | Remote fence was sent to all the targeted harts successfully.
-    /// | SBI_ERR_NOT_SUPPORTED     | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
+    /// | SBI_ERR_NOT_SUPPORTED     | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
     /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
     fn remote_hfence_vvma_asid(
         &self,
@@ -117,8 +121,8 @@ pub trait Rfence: Send {
         SbiRet::not_supported()
     }
     /// Instruct the remote harts to execute one or more `HFENCE.VVMA` instructions,
-    /// covering the range of guest virtual addresses between start and size for current `VMID` (in `hgatp` CSR)
-    /// of calling hart.
+    /// covering the range of guest virtual addresses between `start_addr` and `size`
+    /// for current virtual machine (by `vmid` in `hgatp` CSR) of calling hart.
     ///
     /// This function call is only valid for harts implementing hypervisor extension.
     ///