lib: document amendments, grammar fixes

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

src/console.rs

@@ -5,12 +5,12 @@ use spec::binary::{Physical, SbiRet};
 /// The debug console extension defines a generic mechanism for debugging
 /// and boot-time early prints from supervisor-mode software.
 ///
-/// Kernel developers should switch to driver based console implementation
+/// Kernel developers should switch to driver-based console implementation
 /// instead of using this extension to prevent possible race conditions between
 /// the firmware and the kernel when drivers are ready.
 ///
 /// If the underlying physical console has extra bits for error checking
-/// (or correction) then these extra bits should be handled by the SBI
+/// (or correction), then these extra bits should be handled by the SBI
 /// implementation.
 ///
 /// *NOTE:* It is recommended that bytes sent/received using the debug
@@ -25,7 +25,7 @@ pub trait Console {
     ///
     /// # Non-blocking function
     ///
-    /// This is a non-blocking SBI call and it may do partial/no writes if
+    /// This is a non-blocking SBI call, and it may do partial/no writes if
     /// the debug console is not able to accept more bytes.
     ///
     /// # Return value
@@ -50,7 +50,7 @@ pub trait Console {
     ///
     /// # Non-blocking function
     ///
-    /// This is a non-blocking SBI call and it will not write anything
+    /// This is a non-blocking SBI call, and it will not write anything
     /// into the output memory if there are no bytes to be read in the
     /// debug console.
     ///
@@ -70,7 +70,7 @@ pub trait Console {
     ///
     /// # Blocking function
     ///
-    /// This is a blocking SBI call and it will only return after writing
+    /// This is a blocking SBI call, and it will only return after writing
     /// the specified byte to the debug console. It will also return, with
     /// `SbiRet::failed()`, if there are I/O errors.
     /// # Return value

src/forward.rs

@@ -7,7 +7,7 @@ use sbi_spec::{
 /// Forwards SBI calls onto current supervisor environment.
 ///
 /// If crate feature `forward` is enabled, this structure implements all RustSBI extensions
-/// by forwarding the calls into current supervisor environment. This is done by `sbi-rt`
+/// by forwarding the calls into the current supervisor environment. This is done by `sbi-rt`
 /// crate; thus `Forward` is only available when it's running in RISC-V SBI environments.
 ///
 /// `Forward` implements all RustSBI traits, but is only effective if `#[cfg(feature = "forward")]`

src/hsm.rs

@@ -13,13 +13,13 @@ use sbi_spec::binary::SbiRet;
 /// |:---------|:-----------|:------------
 /// | 0 | `STARTED` | The hart is physically powered-up and executing normally.
 /// | 1 | `STOPPED` | The hart is not executing in supervisor-mode or any lower privilege mode. It is probably powered-down by the SBI implementation if the underlying platform has a mechanism to physically power-down harts.
-/// | 2 | `START_PENDING` | 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.
+/// | 2 | `START_PENDING` | 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.
 /// | 3 | `STOP_PENDING` | 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.
-/// | 4 | `SUSPENDED` | This hart is in a platform specific suspend (or low power) state.
+/// | 4 | `SUSPENDED` | This hart is in a platform-specific suspend (or low power) state.
 /// | 5 | `SUSPEND_PENDING` | The hart has requestd 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.
 /// | 6 | `RESUME_PENDING` | 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 working to get the hart in the **STARTED** state.
 ///
-/// At any point in time, a hart should be in one of the above mentioned hart states.
+/// At any point in time, a hart should be in one of the above-mentioned hart states.
 ///
 /// # Topology hart groups
 ///
@@ -55,7 +55,7 @@ pub trait Hsm {
     ///
     /// - The `hartid` parameter specifies the target hart which is to be started.
     /// - The `start_addr` parameter points to a runtime-specified physical address, where the hart can start executing in supervisor-mode.
-    /// - The `opaque` parameter is a `usize` value which will be set in the `a1` register when the hart starts executing at `start_addr`.
+    /// - The `opaque` parameter is a `usize` value that will be set in the `a1` register when the hart starts executing at `start_addr`.
     ///
     /// *NOTE:* A single `usize` parameter is sufficient as `start_addr`,
     /// because the hart will start execution in supervisor-mode with the MMU off,
@@ -129,18 +129,18 @@ pub trait Hsm {
     /// specified by the `suspend_type` parameter.
     ///
     /// The hart will automatically come out of suspended state and resume normal execution
-    /// when it recieves an interrupt or platform specific hardware event.
+    /// when it receives an interrupt or platform specific hardware event.
     ///
     /// # Suspend behavior
     ///
-    /// The platform specific suspend states for a hart can be either retentive or non-rententive in nature.
+    /// The platform-specific suspend states for a hart can be either retentive or non-rententive in nature.
     ///
     /// A retentive suspend state will preserve hart register and CSR values for all privilege modes,
     /// whereas a non-retentive suspend state will not preserve hart register and CSR values.
     ///
     /// # Resuming
     ///
-    /// Resuming from a retentive suspend state is straight forward and the supervisor-mode software
+    /// Resuming from a retentive suspend state is straight forward, and the supervisor-mode software
     /// will see SBI suspend call return without any failures.
     ///
     /// Resuming from a non-retentive suspend state is relatively more involved and requires software
@@ -177,7 +177,7 @@ pub trait Hsm {
     /// because the hart will resume execution in supervisor-mode with the MMU off,
     /// hence `resume_addr` must be less than XLEN bits wide.
     ///
-    /// The `opaque` parameter is an XLEN-bit value which will be set in the `a1`
+    /// The `opaque` parameter is an XLEN-bit value that will be set in the `a1`
     /// register when the hart resumes exectution at `resume_addr` after a
     /// non-retentive suspend.
     ///

src/lib.rs

@@ -276,8 +276,8 @@
 //!     core::arch::asm!(
 //!         // 1. Turn off interrupt
 //!         "csrw  mie, zero",
-//!         // 2. Initialize programming langauge runtime
-//!         // only clear bss if hartid is zero
+//!         // 2. Initialize programming language runtime
+//!         // only clear bss if hart ID is zero
 //!         "csrr  t0, mhartid",
 //!         "bnez  t0, 2f",
 //!         // clear bss segment
@@ -321,7 +321,7 @@
 //! }
 //!
 //! /// Rust entry, call in `entry` assembly function
-//! extern "C" fn rust_main(_hartid: usize, opaque: usize) -> Operation {
+//! extern "C" fn rust_main(_hart_id: usize, opaque: usize) -> Operation {
 //!     // .. board initialization process ...
 //!     let board_params = board_init_once();
 //!     // .. print necessary information and rustsbi::LOGO ..
@@ -357,7 +357,7 @@
 //!
 //! Some platforms would provide system memory under different grades in speed and size to reduce product cost.
 //! Those platforms would typically provide two parts of code memory, first one being relatively small, not fast
-//! but instantly available after chip start, while the second one is larger in size but typically requires
+//! but instantly available after chip start, while the second one is larger but typically requires
 //! memory training. The former one would include built-in SRAM memory, and the later would include
 //! external SRAM or DDR memory. On those platforms, a first stage bootloader is typically needed to
 //! train memory for later stages. In such situation, RustSBI implementation should be treated as or concatenated
@@ -405,7 +405,7 @@
 //! struct MySBI {
 //!     // add other fields later ...
 //!     // An environment information must be provided on
-//!     // non bare-metal RustSBI development.
+//!     // non-bare-metal RustSBI development.
 //!     info: MyEnvInfo,
 //! }
 //!
@@ -470,13 +470,13 @@
 //!
 //! ## Emulators using RustSBI
 //!
-//! RustSBI library may be used to write RISC-V emulators. Other than hardware accelereted binary
+//! RustSBI library may be used to write RISC-V emulators. Other than hardware accelerated binary
 //! translation methods, emulators typically do not use host hardware specific features,
 //! thus may build and run on any architecture.
 //! Like hardware RISC-V implementations, software emulated RISC-V environment would still need SBI
 //! implementation to support supervisor environment.
 //!
-//! Writing emulators would follow the similiar process with writing hypervisors, see
+//! Writing emulators would follow the similar process with writing hypervisors, see
 //! [Hypervisors using RustSBI](#hypervisors-using-rustsbi) for details.
 //!
 //! # Download binary file: the Prototyping System vs discrete packages
@@ -494,8 +494,8 @@
 //!
 //! Discrete SBI packages are SBI environment support packages specially designed for one board
 //! or SoC, it will be provided by board vendor or RustSBI ecosystem.
-//! Vendors may find it easy to include fine grained features in each support package, but the
-//! maintenance situation would vary between vendors and it would likely to cost a lot of time
+//! Vendors may find it easy to include fine-grained features in each support package, but the
+//! maintenance situation would vary between vendors, and it would likely to cost a lot of time
 //! to develop from a bare-metal executable. Users may find a boost in performance, energy saving
 //! indexes and feature granularity in discrete packages, but it would depend on whether the
 //! vendor provides it.

src/nacl.rs

@@ -13,7 +13,7 @@ use spec::{
 ///
 /// The SBI nested acceleration extension defines a shared memory based interface
 /// between the SBI implementation (or L0 hypervisor) and the supervisor software
-/// (or L1 hypervisor) which allows both to collaboratively reduce traps taken
+/// (or L1 hypervisor), which allows both to collaboratively reduce traps taken
 /// by the L0 hypervisor for emulating RISC-V H-extension functionality. The
 /// nested acceleration shared memory allows the L1 hypervisor to batch multiple
 /// RISC-V H-extension CSR accesses and HFENCE requests which are then emulated
@@ -46,13 +46,13 @@ pub trait Nacl {
     ///
     /// # Parameters
     ///
-    /// If physical address of `shmem` are not all-ones bitwise, then the `shmem` pointer
+    /// If the physical address of `shmem` is not all-ones bitwise, then the `shmem` pointer
     /// specifies the shared memory physical base address. The physical address of `shmem`
     /// MUST be 4096-byte aligned. The size of the shared memory must be 4096 + (XLEN * 128) bytes.
     /// The SBI implementation MUST zero the shared memory before returning from the SBI
     /// call.
     ///
-    /// If physical address of `shmem` are all-ones bitwise, then the nested acceleration features
+    /// If the physical address of `shmem` is all-ones bitwise, then the nested acceleration features
     /// are disabled.
     ///
     /// The `flags` parameter is reserved for future use and must be zero.
@@ -70,14 +70,14 @@ pub trait Nacl {
     /// Synchronize shared memory CSRs.
     ///
     /// Synchronize CSRs in the nested acceleration shared memory. This is an
-    /// optional function which is only available if the SBI_NACL_FEAT_SYNC_CSR
+    /// optional function that is only available if the SBI_NACL_FEAT_SYNC_CSR
     /// feature is available.
     ///
     /// # Parameters
     ///
     /// The parameter `csr_num` specifies the set of RISC-V H-extension CSRs to be synchronized.
     ///
-    /// If `csr_num` is all-ones bitwise then all RISC-V H-extension CSRs implemented by the SBI
+    /// If `csr_num` is all-ones bitwise, then all RISC-V H-extension CSRs implemented by the SBI
     /// implementation (or L0 hypervisor) are synchronized.
     ///
     /// If `(csr_num & 0x300) == 0x200` and `csr_num < 0x1000` then only a single RISC-V H-extension
@@ -97,14 +97,14 @@ pub trait Nacl {
     /// Synchronize shared memory HFENCEs.
     ///
     /// Synchronize HFENCEs in the nested acceleration shared memory. This is an
-    /// optional function which is only available if the SBI_NACL_FEAT_SYNC_HFENCE
+    /// optional function that is only available if the SBI_NACL_FEAT_SYNC_HFENCE
     /// feature is available.
     ///
     /// # Parameters
     ///
     /// The parameter `entry_index` specifies the set of nested HFENCE entries to be synchronized.
     ///
-    /// If `entry_index` is all-ones bitwise then all nested HFENCE entries are
+    /// If `entry_index` is all-ones bitwise, then all nested HFENCE entries are
     /// synchronized.
     ///
     /// If `entry_index < (3840 / XLEN)` then only a single nested HFENCE entry
@@ -124,16 +124,16 @@ pub trait Nacl {
     /// Synchronize shared memory and emulate SRET.
     ///
     /// Synchronize CSRs and HFENCEs in the nested acceleration shared memory and
-    /// emulate the SRET instruction. This is an optional function which is only
+    /// emulate the SRET instruction. This is an optional function that is only
     /// available if the SBI_NACL_FEAT_SYNC_SRET feature is available.
     ///
     /// This function is used by supervisor software (or L1 hypervisor) to do
-    /// a synchronize SRET request and the SBI implementation (or L0 hypervisor)
+    /// a synchronized SRET request, and the SBI implementation (or L0 hypervisor)
     /// MUST handle it.
     ///
     /// # Return Value
     ///
-    /// This function does not return upon success and the possible error codes returned in
+    /// This function does not return upon success, and the possible error codes returned in
     /// `SbiRet.error` upon failure are shown in the table below:
     ///
     /// | Return code               | Description

src/pmu.rs

@@ -8,12 +8,12 @@ use sbi_spec::binary::SbiRet;
 /// and use the RISC-V hardware performance counters with assistance from the machine-mode (or hypervisor-mode).
 /// These hardware performance counters can only be started, stopped, or configured from machine-mode
 /// using `mcountinhibit` and `mhpmeventX` CSRs.
-/// Due to this, a machine-mode SBI implementation may choose to disallow SBI PMU extension
+/// Due to this, a machine-mode SBI implementation may choose to disallow its SBI PMU extension
 /// if `mcountinhibit` CSR is not implemented by the RISC-V platform.
 ///
 /// A RISC-V platform generally supports monitoring of various hardware events using a limited number
 /// of hardware performance counters which are up to 64 bits wide.
-/// In addition, a SBI implementation can also provide firmware performance counters which can monitor firmware events
+/// In addition, an SBI implementation can also provide firmware performance counters which can monitor firmware events
 /// such as number of misaligned load/store instructions, number of RFENCEs, number of IPIs, etc.
 /// The firmware counters are always 64 bits wide.
 ///
@@ -21,11 +21,11 @@ use sbi_spec::binary::SbiRet;
 ///
 /// 1. An interface for supervisor-mode software to discover and configure per-HART hardware/firmware counters
 /// 2. A typical perf compatible interface for hardware/firmware performance counters and events
-/// 3. Full access to microarchitecture’s raw event encodings
+/// 3. Full access to micro-architecture’s raw event encodings
 ///
 /// To define SBI PMU extension calls, we first define important entities `counter_idx`, `event_idx`, and `event_data`.
 /// The `counter_idx` is a logical number assigned to each hardware/firmware counter.
-/// The `event_idx `represents a hardware (or firmware) event whereas
+/// The `event_idx `represents a hardware (or firmware) event, whereas
 /// the `event_data` is 64 bits wide and represents additional configuration (or parameters) for
 /// a hardware (or firmware) event.
 ///
@@ -41,7 +41,7 @@ pub trait Pmu {
     /// The value is returned in `SbiRet.value`; this call always returns `SbiRet::success()`.
     fn num_counters(&self) -> usize;
     /// Get details about the specified counter such as underlying CSR number, width of the counter,
-    /// type of counter hardware/firmware, etc.
+    /// type of counter (hardware/firmware, etc.).
     ///
     /// The `counter_info` returned by this SBI call is encoded as follows:
     ///
@@ -73,7 +73,7 @@ pub trait Pmu {
     /// whereas the `event_idx` represents the event to be monitored
     /// and `event_data` represents any additional event configuration.
     ///
-    /// The `config_flags` parameter represents additional counter configuration and filter flags.
+    /// The `config_flags` parameter represents additional configuration and filter flags on counters.
     /// The bit definitions of the `config_flags` parameter are shown in the table below:
     ///
     /// | Flag Name                      | Bits         | Description
@@ -93,7 +93,7 @@ pub trait Pmu {
     /// set of counters specified by the `counter_idx_base` and `counter_idx_mask`.
     ///
     /// *NOTE:* The *SBI_PMU_CFG_FLAG_AUTO_START* flag in `config_flags` has no
-    /// impact on the counter value.
+    /// impact on the value of counter.
     ///
     /// *NOTE:* The `config_flags[3:7]` bits are event filtering hints so these
     /// can be ignored or overridden by the SBI implementation for security concerns
@@ -132,8 +132,8 @@ pub trait Pmu {
     /// | `SBI_PMU_START_SET_INIT_VALUE` | `0:0`        | Set the value of counters based on the `initial_value` parameter.
     /// | _RESERVED_                     | `1:(XLEN-1)` | _All non-zero values are reserved for future use._
     ///
-    /// *NOTE*: When `SBI_PMU_START_SET_INIT_VALUE` is not set in `start_flags`, the counter value will
-    /// not be modified and event counting will start from current counter value.
+    /// *NOTE*: When `SBI_PMU_START_SET_INIT_VALUE` is not set in `start_flags`, the value of counter will
+    /// not be modified, and event counting will start from the current value of counter.
     ///
     /// # Return value
     ///
@@ -180,13 +180,13 @@ pub trait Pmu {
     ) -> SbiRet;
     /// Provide the current value of a firmware counter in `SbiRet.value`.
     ///
-    /// On RV32 systems, the `SbiRet.value` will only contain the lower 32 bits of the current
-    /// firmware counter value.
+    /// On RV32 systems, the `SbiRet.value` will only contain the lower 32 bits from the value of
+    /// the firmware counter.
     ///
     /// # Parameters
     ///
     /// This function should be only used to read a firmware counter. It will return an error
-    /// when user provides a hardware counter in `counter_idx` parameter.
+    /// when the user provides a hardware counter in `counter_idx` parameter.
     ///
     /// # Return value
     ///
@@ -197,7 +197,7 @@ pub trait Pmu {
     /// | `SbiRet::success()`       | firmware counter read successfully.
     /// | `SbiRet::invalid_param()` | `counter_idx` points to a hardware counter or an invalid counter.
     fn counter_fw_read(&self, counter_idx: usize) -> SbiRet;
-    /// Provide the upper 32 bits of the current firmware counter value in `SbiRet.value`.
+    /// Provide the upper 32 bits from the current value of firmware counter in `SbiRet.value`.
     ///
     /// This function always returns zero in `SbiRet.value` for RV64 (or higher) systems.
     ///

src/reset.rs

@@ -2,7 +2,7 @@ use sbi_spec::binary::SbiRet;
 
 /// System Reset extension.
 ///
-/// Provides a function that allow the supervisor software to request system-level reboot or shutdown.
+/// Provides a function that allows the supervisor software to request system-level reboot or shutdown.
 ///
 /// The term "system" refers to the world-view of supervisor software and the underlying SBI implementation
 /// could be machine mode firmware or hypervisor.
@@ -16,15 +16,19 @@ pub trait Reset {
     /// # Warm reboot and cold reboot
     ///
     /// When supervisor software is running natively, the SBI implementation is machine mode firmware.
-    /// In this case, shutdown is equivalent to physical power down of the entire system and
-    /// cold reboot is equivalent to physical power cycle of the entire system. Further, warm reboot
-    /// is equivalent to a power cycle of main processor and parts of the system but not the entire system.
+    /// In this case, shutdown is equivalent to physical power down of the entire system, and
+    /// cold reboot is equivalent to a physical power cycle of the entire system.
+    /// Further, warm reboot is equivalent to a power cycle of the main processor and parts of the system
+    /// but not the entire system.
     ///
     /// For example, on a server class system with a BMC (board management controller),
-    /// a warm reboot will not power cycle the BMC whereas a cold reboot will definitely power cycle the BMC.
+    /// a warm reboot will not power cycle the BMC
+    /// whereas a cold reboot will definitely power cycle the BMC.
     ///
-    /// When supervisor software is running inside a virtual machine, the SBI implementation is a hypervisor.
-    /// The shutdown, cold reboot and warm reboot will behave functionally the same as the native case but might
+    /// When supervisor software is running inside a virtual machine,
+    /// the SBI implementation is a hypervisor.
+    /// The shutdown,
+    /// cold reboot and warm reboot will behave functionally the same as the native case but might
     /// not result in any physical power changes.
     ///
     /// # Return value

src/rfence.rs

@@ -10,7 +10,7 @@ pub trait Rfence {
     ///
     /// # Return value
     ///
-    /// Returns `SbiRet::success()` when remote fence was sent to all the targeted harts successfully.
+    /// Returns `SbiRet::success()` when a 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_addr` and `size`.
@@ -21,7 +21,7 @@ pub trait Rfence {
     ///
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
-    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
     /// | `SbiRet::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,
@@ -34,7 +34,7 @@ pub trait Rfence {
     ///
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
-    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
     /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     fn remote_sfence_vma_asid(
         &self,
@@ -47,7 +47,7 @@ pub trait Rfence {
     /// 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.
+    /// This function call is only valid on harts implementing the RISC-V hypervisor extension.
     ///
     /// # Return value
     ///
@@ -55,8 +55,8 @@ pub trait Rfence {
     ///
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
-    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
-    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
+    /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target harts do not support the RISC-V hypervisor extension.
     /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     #[inline]
     fn remote_hfence_gvma_vmid(
@@ -73,7 +73,7 @@ pub trait Rfence {
     /// 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.
+    /// This function call is only valid on harts implementing the RISC-V hypervisor extension.
     ///
     /// # Return value
     ///
@@ -81,8 +81,8 @@ pub trait Rfence {
     ///
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
-    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
-    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
+    /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target harts do not support the RISC-V hypervisor extension..
     /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     #[inline]
     fn remote_hfence_gvma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet {
@@ -94,7 +94,7 @@ pub trait Rfence {
     /// 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.
+    /// This function call is only valid on harts implementing the RISC-V hypervisor extension.
     ///
     /// # Return value
     ///
@@ -102,8 +102,8 @@ pub trait Rfence {
     ///
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
-    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
-    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
+    /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target harts do not support the RISC-V hypervisor extension.
     /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     #[inline]
     fn remote_hfence_vvma_asid(
@@ -120,7 +120,7 @@ pub trait Rfence {
     /// 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.
+    /// This function call is only valid on harts implementing the RISC-V hypervisor extension.
     ///
     /// # Return value
     ///
@@ -128,8 +128,8 @@ pub trait Rfence {
     ///
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
-    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
-    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
+    /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target harts do not support the RISC-V hypervisor extension.
     /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     #[inline]
     fn remote_hfence_vvma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet {

src/susp.rs

@@ -28,9 +28,10 @@ pub trait Susp {
     /// Request the SBI implementation to put the system transitions to a sleep state.
     ///
     /// A return from a `system_suspend()` call implies an error and an error code
-    /// will be in `sbiret.error`. A successful suspend and wake up, results in the
-    /// hart which initiated the suspend, resuming from the `STOPPED` state. To resume,
-    /// the hart will jump to supervisor-mode, at the address specified by `resume_addr`,
+    /// will be in `sbiret.error`.
+    /// A successful suspend and wake up operation results in the
+    /// hart, which initiated to suspend, resuming from the `STOPPED` state.
+    /// To resume, the hart will jump to supervisor-mode, at the address specified by `resume_addr`,
     /// with the specific register values described in the table below.
     ///
     /// | Register Name                                     | Register Value     
@@ -50,19 +51,20 @@ pub trait Susp {
     /// because the hart will resume execution in supervisor-mode with the MMU off,
     /// hence `resume_addr` must be less than XLEN bits wide.
     ///
-    /// The `opaque` parameter is an XLEN-bit value which will be set in the `a1`
-    /// register when the hart resumes exectution at `resume_addr` after a
+    /// The `opaque` parameter is an XLEN-bit value that will be set in the `a1`
+    /// register when the hart resumes execution at `resume_addr` after a
     /// system suspend.
     ///
     /// Besides ensuring all entry criteria for the selected sleep type are met, such
     /// as ensuring other harts are in the `STOPPED` state, the caller must ensure all
     /// power units and domains are in a state compatible with the selected sleep type.
     /// The preparation of the power units, power domains, and wake-up devices used for
-    /// resumption from the system sleep state is platform specific and beyond the
+    /// resumption from the system sleep state is platform-specific and beyond the
     /// scope of this specification.
     ///
     /// When supervisor software is running inside a virtual machine, the SBI
-    /// implementation is provided by a hypervisor. The system suspend will behave
+    /// implementation is provided by a hypervisor.
+    /// The system suspend will behave
     /// functionally the same as the native case, but might not result in any physical
     /// power changes.
     ///
@@ -72,11 +74,15 @@ pub trait Susp {
     ///
     /// | Error code                  | Description  
     /// | --------------------------- | -------------------
-    /// | `SbiRet::success()`         | System has suspended and resumed successfully.
+    /// | `SbiRet::success()`         | System has been suspended and resumed successfully.
     /// | `SbiRet::invalid_param()`   | `sleep_type` is reserved or is platform-specific and unimplemented.
-    /// | `SbiRet::not_supported()`   | `sleep_type` is not reserved and is implemented, but the platform does not support it due to one or more missing dependencies.
-    /// | `SbiRet::invalid_address()` | `resume_addr` is not valid, possibly due to the following reasons: * It is not a valid physical address. * Executable access to the address is prohibited by a physical memory protection mechanism or H-extension G-stage for supervisor mode.
-    /// | `SbiRet::failed()`          | The suspend request failed for unspecified or unknown other reasons.
+    /// | `SbiRet::not_supported()`   | `sleep_type` is not reserved and is implemented,
+    /// but the platform does not support it due to one or more missing dependencies.
+    /// | `SbiRet::invalid_address()` | `resume_addr` is not valid, possibly due to the following reasons:
+    /// * It is not a valid physical address.
+    /// * Executable access to the address is prohibited by a physical memory protection mechanism or H-extension G-stage for supervisor mode.
+    /// | `SbiRet::failed()`
+    /// | The suspend request failed for unspecified or unknown other reasons.
     fn system_suspend(&self, sleep_type: u32, resume_addr: usize, opaque: usize) -> SbiRet;
 }
 

src/timer.rs

@@ -1,6 +1,6 @@
 /// Timer programmer support extension.
 pub trait Timer {
-    /// Programs the clock for next event after `stime_value` time.
+    /// Programs the clock for the next event after `stime_value` time.
     ///
     /// `stime_value` is in absolute time. This function must clear the pending timer interrupt bit as well.
     ///

src/traits.rs

@@ -21,7 +21,7 @@ impl<T: RustSBI> RustSBI for &T {
 pub trait EnvInfo {
     /// Vendor ID for the supervisor environment.
     ///
-    /// Provides JEDEC manufacturer ID of the provider of the core.
+    /// Provides JEDEC manufacturer ID for the provider of the core.
     fn mvendorid(&self) -> usize;
     /// Architecture ID for the supervisor environment.
     ///
@@ -29,7 +29,7 @@ pub trait EnvInfo {
     fn marchid(&self) -> usize;
     /// Implementation ID for the supervisor environment.
     ///
-    /// Provides a unique encoding of the version of the processor implementation.
+    /// Provides a unique encoding for the version of the processor implementation.
     fn mimpid(&self) -> usize;
 }