sbi-spec: document amendments, grammar fixes

Signed-off-by: Zhouqi Jiang <[email protected]>

sbi-spec/src/base.rs

@@ -25,13 +25,13 @@ impl Version {
         Self { raw }
     }
 
-    /// Reads major version of specification.
+    /// Reads the major version of RISC-V SBI specification.
     #[inline]
     pub const fn major(self) -> usize {
         (self.raw >> 24) & ((1 << 7) - 1)
     }
 
-    /// Reads minor version of specification.
+    /// Reads the minor version of RISC-V SBI specification.
     #[inline]
     pub const fn minor(self) -> usize {
         self.raw & ((1 << 24) - 1)
@@ -59,19 +59,19 @@ mod fid {
     ///
     /// Declared in §4.3.
     pub const GET_SBI_IMPL_VERSION: usize = 0x2;
-    /// Function ID to probe information about one SBI extension from current environment.
+    /// Function ID to probe information about one SBI extension from the current environment.
     ///
     /// Declared in §4.4.
     pub const PROBE_EXTENSION: usize = 0x3;
-    /// Function ID to get value of `mvendorid` register in current environment.
+    /// Function ID to get the value of `mvendorid` register in the current environment.
     ///
     /// Declared in §4.5.
     pub const GET_MVENDORID: usize = 0x4;
-    /// Function ID to get value of `marchid` register in current environment.
+    /// Function ID to get the value of `marchid` register in the current environment.
     ///
     /// Declared in §4.6.
     pub const GET_MARCHID: usize = 0x5;
-    /// Function ID to get value of `mimpid` register in current environment.
+    /// Function ID to get the value of `mimpid` register in the current environment.
     ///
     /// Declared in §4.7.
     pub const GET_MIMPID: usize = 0x6;
@@ -81,18 +81,18 @@ mod fid {
 ///
 /// Declared in §4.9.
 pub mod impl_id {
-    /// Berkley Bootloader
+    /// Berkley Bootloader.
     pub const BBL: usize = 0;
-    /// OpenSBI
+    /// OpenSBI.
     pub const OPEN_SBI: usize = 1;
-    /// Xvisor
+    /// Xvisor.
     pub const XVISOR: usize = 2;
-    /// KVM
+    /// KVM.
     pub const KVM: usize = 3;
-    /// RustSBI
+    /// RustSBI.
     pub const RUST_SBI: usize = 4;
-    /// Diosix
+    /// Diosix.
     pub const DIOSIX: usize = 5;
-    /// Coffer
+    /// Coffer.
     pub const COFFER: usize = 6;
 }

sbi-spec/src/hsm.rs

@@ -17,26 +17,26 @@ pub mod hart_state {
     pub const STOPPED: usize = 1;
     /// The hart is pending before being started
     ///
-    /// Some other hart has requested to start (or power-up) the hart from the STOPPED state
+    /// Some other hart has requested to start (or power-up) the hart from the STOPPED state,
     /// and the SBI implementation is still working to get the hart in the STARTED state.
     pub const START_PENDING: usize = 2;
     /// The hart is pending before being stopped.
     ///
-    /// The hart has requested to stop (or power-down) itself from the STARTED state
+    /// The hart has requested to stop (or power-down) itself from the STARTED state,
     /// and the SBI implementation is still working to get the hart in the STOPPED state.
     pub const STOP_PENDING: usize = 3;
-    /// The hart is in a platform specific suspend (or low power) state.
+    /// The hart is in a platform-specific suspend (or low-power) state.
     pub const SUSPENDED: usize = 4;
     /// The hart is pending before being suspended.
     ///
-    /// The hart has requested to put itself in a platform specific low power state
-    /// from the STARTED state and the SBI implementation is still working to get
-    /// the hart in the platform specific SUSPENDED state.
+    /// The hart has requested to put itself in a platform-specific low-power state
+    /// from the STARTED state, and the SBI implementation is still working to get
+    /// the hart in the platform-specific SUSPENDED state.
     pub const SUSPEND_PENDING: usize = 5;
     /// The hart is pending before being resumed.
     ///
     /// An interrupt or platform specific hardware event has caused the hart to resume
-    /// normal execution from the SUSPENDED state and the SBI implementation is still
+    /// normal execution from the SUSPENDED state, and the SBI implementation is still
     /// working to get the hart in the STARTED state.
     pub const RESUME_PENDING: usize = 6;
 }
@@ -63,7 +63,7 @@ mod fid {
     ///
     /// Declared in §9.3.
     pub const HART_GET_STATUS: usize = 2;
-    /// Function ID to put the calling hart into suspend or platform specific lower power states.
+    /// Function ID to put the calling hart into suspend or platform-specific lower power states.
     ///
     /// Declared in §9.4.
     pub const HART_SUSPEND: usize = 3;

sbi-spec/src/lib.rs

@@ -7,13 +7,13 @@
 //! You may find it convenient to use this library in a vast range of packages,
 //! from operating system kernels, hypervisors, to SBI bare metal implementations.
 //! This crate is `no_std` compatible and does not need dynamic memory allocation,
-//! which make it suitable for embedded development.
+//! which makes it suitable for embedded development.
 //!
 //! Although this library is dedicated to RISC-V architecture, it does not limit
-//! which build target the dependents should compile into. For example, you are
-//! developing a RISC-V emulator on platforms other than RISC-V, the emulator
-//! designed on other platforms can still make use of `sbi-spec` structures to
-//! provide necessary features the emulated RISC-V environment would make use of.
+//! which build target the dependents should compile into.
+//! For example, when developing a RISC-V emulator on platforms other than RISC-V,
+//! the emulator designed on other platforms can still make use of `sbi-spec` structures,
+//! to provide the necessary features where the emulated RISC-V environment would make use of.
 #![no_std]
 #![deny(missing_docs, unsafe_code, unstable_features)]
 

sbi-spec/src/nacl.rs

@@ -33,19 +33,19 @@ mod fid {
 ///
 /// Declared in §15.
 pub mod feature_id {
-    /// Feature ID for the synchronize CSR feature.
+    /// Feature ID for the CSR synchronizing feature.
     ///
     /// Declared in §15.1.
     pub const SYNC_CSR: usize = 0;
-    /// Feature ID for the synchronize HFENCE feature.
+    /// Feature ID for the HFENCE synchronizing feature.
     ///
     /// Declared in §15.2.
     pub const SYNC_HFENCE: usize = 1;
-    /// Feature ID for the synchronize SRET feature.
+    /// Feature ID for the SRET synchronizing feature.
     ///
     /// Declared in §15.3.
     pub const SYNC_SRET: usize = 2;
-    /// Feature ID for the autoswap CSR feature.
+    /// Feature ID for the auto-swap CSR feature.
     ///
     /// Declared in §15.4.
     pub const AUTOSWAP_CSR: usize = 3;
@@ -56,12 +56,12 @@ pub mod feature_id {
 /// NACL shared memory includes scratch space and CSR space. Due to the difference
 /// of CSR width, this size varies between different `XLEN` values. `NATIVE`
 /// constant here only matches the integer width for the target this crate is compiled.
-/// If you are writing an SEE with different `XLEN` from host platform, you should
+/// If you are writing an SEE with different `XLEN` from the host platform, you should
 /// choose other correct constant value from `RV32`, `RV64` or `RV128` in module `shmem_size`
 /// instead.
 pub mod shmem_size {
     use core::mem::size_of;
-    /// Size of NACL shared memory on platforms with `XLEN` of same width as the current platform.
+    /// Size of NACL shared memory on platforms with `XLEN` of the same width as the current platform.
     pub const NATIVE: usize = 4096 + 1024 * size_of::<usize>();
 
     /// Size of NACL shared memory on RV32 platforms.

sbi-spec/src/pmu.rs

@@ -30,7 +30,7 @@ mod fid {
     ///
     /// Declared in §11.10.
     pub const COUNTER_FW_READ: usize = 5;
-    /// Function ID to provide the upper 32 bits of the current firmware counter value.
+    /// Function ID to provide the upper 32 bits from the value of the current firmware counter.
     ///
     /// Declared in §11.11.
     pub const COUNTER_FW_READ_HI: usize = 6;
@@ -56,7 +56,7 @@ pub mod event_type {
     ///
     /// Declared in §11.3.
     pub const HARDWARE_RAW: usize = 2;
-    /// Type for for all firmware events.
+    /// Type for all firmware events.
     ///
     /// Declared in §11.4.
     pub const FIRMWARE: usize = 15;
@@ -66,27 +66,27 @@ pub mod event_type {
 ///
 /// Declared in §11.1.
 pub mod hardware_event {
-    /// Unused event because event_idx cannot be zero
+    /// Unused event because event_idx cannot be zero.
     pub const NO_EVENT: usize = 0;
-    /// Event for each CPU cycle
+    /// Event for each CPU cycle.
     pub const CPU_CYCLES: usize = 1;
-    /// Event for each completed instruction
+    /// Event for each completed instruction.
     pub const INSTRUCTIONS: usize = 2;
-    /// Event for cache hit
+    /// Event for cache hit.
     pub const CACHE_REFERENCES: usize = 3;
-    /// Event for cache miss
+    /// Event for cache miss.
     pub const CACHE_MISSES: usize = 4;
-    /// Event for a branch instruction
+    /// Event for a branch instruction.
     pub const BRANCH_INSTRUCTIONS: usize = 5;
-    /// Event for a branch misprediction
+    /// Event for a branch mis-prediction.
     pub const BRANCH_MISSES: usize = 6;
-    /// Event for each BUS cycle
+    /// Event for each BUS cycle.
     pub const BUS_CYCLES: usize = 7;
-    /// Event for a stalled cycle in microarchitecture frontend
+    /// Event for a stalled cycle in micro-architecture frontend.
     pub const STALLED_CYCLES_FRONTEND: usize = 8;
-    /// Event for a stalled cycle in microarchitecture backend
+    /// Event for a stalled cycle in micro-architecture backend.
     pub const STALLED_CYCLES_BACKEND: usize = 9;
-    /// Event for each reference CPU cycle
+    /// Event for each reference CPU cycle.
     pub const REF_CPU_CYCLES: usize = 10;
 }
 

sbi-spec/src/srst.rs

@@ -4,11 +4,11 @@
 pub const EID_SRST: usize = crate::eid_from_str("SRST") as _;
 pub use fid::*;
 
-/// Shutdown as reset type.
+/// Shutdown as a reset type.
 pub const RESET_TYPE_SHUTDOWN: u32 = 0;
-/// Cold Reboot as reset type.
+/// Cold Reboot as a reset type.
 pub const RESET_TYPE_COLD_REBOOT: u32 = 1;
-/// Warm Reboot as reset type.
+/// Warm Reboot as a reset type.
 pub const RESET_TYPE_WARM_REBOOT: u32 = 2;
 
 /// No Reason as reset reason.

sbi-spec/src/time.rs

@@ -6,7 +6,7 @@ pub use fid::*;
 
 /// Declared in §6.2.
 mod fid {
-    /// Function ID to program the clock for next event after an absolute time.
+    /// Function ID to program the clock for the next event after an absolute time.
     ///
     /// Declared in §6.1.
     pub const SET_TIMER: usize = 0;