lib: (2/n) grammar fixes

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

macros/src/lib.rs

@@ -57,7 +57,7 @@ pub fn derive_rustsbi(input: TokenStream) -> TokenStream {
         if let Some(_origin) = origin {
             // TODO: provide more detailed proc macro error hinting that previous
             // definition of this extension resides in `origin` once RFC 1566
-            // (Procedural Macro Diagnostics) is stablized.
+            // (Procedural Macro Diagnostics) is stabilized.
             // Link: https://github.com/rust-lang/rust/issues/54140
             let error = syn::Error::new_spanned(
                 field,

sbi-spec/src/binary.rs

@@ -9,7 +9,7 @@ use core::marker::PhantomData;
 /// > This is analogous to returning the C structure `SbiRet`.
 ///
 /// Note: if this structure is used in function return on conventional
-/// Rust code, it would not require to pin memory representation as
+/// Rust code, it would not require pinning memory representation as
 /// extern C. The `repr(C)` is set in case that some users want to use
 /// this structure in FFI code.
 #[derive(Clone, Copy, PartialEq, Eq)]
@@ -126,7 +126,7 @@ impl SbiRet {
             value: 0,
         }
     }
-    /// SBI call failed due to denied.
+    /// SBI call denied.
     ///
     /// As the time this document was written,
     /// there is currently no function in SBI standard that returns this error.
@@ -152,7 +152,7 @@ impl SbiRet {
     }
 
     /// SBI call failed for the target resource is already available,
-    /// e.g. the target hart is already started when caller still request it to start.
+    /// e.g., the target hart is already started when caller still requests it to start.
     #[inline]
     pub const fn already_available() -> Self {
         Self {
@@ -162,7 +162,7 @@ impl SbiRet {
     }
 
     /// SBI call failed for the target resource is already started,
-    /// e.g. target performance counter is started.
+    /// e.g., target performance counter is started.
     #[inline]
     pub const fn already_started() -> Self {
         Self {
@@ -172,7 +172,7 @@ impl SbiRet {
     }
 
     /// SBI call failed for the target resource is already stopped,
-    /// e.g. target performance counter is stopped.
+    /// e.g., target performance counter is stopped.
     #[inline]
     pub const fn already_stopped() -> Self {
         Self {
@@ -398,9 +398,9 @@ impl SbiRet {
     /// # use sbi_spec::binary::{SbiRet, Error};
     /// fn stringify(x: Error) -> String {
     ///     if x == Error::AlreadyStarted {
-    ///         format!("error: already started!")
+    ///         "error: already started!".to_string()
     ///     } else {
-    ///         format!("error: other error!")
+    ///         "error: other error!".to_string()
     ///     }
     /// }
     ///
@@ -768,13 +768,13 @@ impl<P> Physical<P> {
         self.num_bytes
     }
 
-    /// Returns low part base address of physical memory slice.
+    /// Returns low-part base address of physical memory slice.
     #[inline]
     pub const fn phys_addr_lo(&self) -> usize {
         self.phys_addr_lo
     }
 
-    /// Returns high part base address of physical memory slice.
+    /// Returns high-part base address of physical memory slice.
     #[inline]
     pub const fn phys_addr_hi(&self) -> usize {
         self.phys_addr_hi
@@ -783,20 +783,20 @@ impl<P> Physical<P> {
 
 /// Shared memory physical address raw pointer with type annotation.
 ///
-/// This is a structure wrapping a raw pointer to value of type `T` without
-/// pointer metadata. `SharedPtr`s are _thin_; they won't include metadata
+/// This is a structure wrapping a raw pointer to the value of the type `T` without
+/// a pointer metadata. `SharedPtr`'s are _thin_; they won't include metadata
 /// as RISC-V SBI does not provide an approach to pass them via SBI calls,
-/// thus the length of type `T` should be decided independently from raw
+/// thus the length of type `T` should be decided independently of raw
 /// pointer structure.
 ///
-/// `SharedPtr` can be used as a parameter to pass shared memory physical pointer
-/// with given base address in RISC-V SBI calls. For example, a `SharedPtr<[u8; 64]>`
+/// `SharedPtr` can be used as a parameter to pass the shared memory physical pointer
+///  with a given base address in RISC-V SBI calls. For example, a `SharedPtr<[u8; 64]>`
 /// would represent a fixed-size 64 byte array on a RISC-V SBI function argument
 /// type.
 ///
 /// This structure cannot be dereferenced directly with physical addresses,
 /// because on RISC-V systems the physical address space could be larger than the
-/// virtual ones. Hence, this structure describes physical memory range by
+/// virtual ones. Hence, this structure describes the physical memory range by
 /// two `usize` values: the upper `phys_addr_hi` and lower `phys_addr_lo`.
 ///
 /// RISC-V SBI extensions may declare special pointer values for shared memory
@@ -820,7 +820,7 @@ impl<P> Physical<P> {
 /// * The data in the shared memory MUST follow little-endian byte ordering.
 ///
 /// *NOTE:* If the supervisor-mode software accesses the same physical memory
-/// range using a memory type different than the PMA, then a loss of coherence
+/// range using a memory type different from the PMA, then a loss of coherence
 /// or unexpected memory ordering may occur. The invoking software should
 /// follow the rules and sequences defined in the RISC-V Svpbmt specification
 /// to prevent the loss of coherence and memory ordering.
@@ -837,7 +837,7 @@ pub struct SharedPtr<T> {
 }
 
 // FIXME: we should consider strict provenance rules for this pointer-like structure
-// once feature strict_provenance is stablized.
+// once feature strict_provenance is stabled.
 impl<T> SharedPtr<T> {
     /// Create a shared physical memory pointer by physical address.
     #[inline]
@@ -849,13 +849,13 @@ impl<T> SharedPtr<T> {
         }
     }
 
-    /// Returns low part physical address of shared physical memory pointer.
+    /// Returns low-part physical address of the shared physical memory pointer.
     #[inline]
     pub const fn phys_addr_lo(self) -> usize {
         self.phys_addr_lo
     }
 
-    /// Returns high part physical address of shared physical memory pointer.
+    /// Returns high-part physical address of the shared physical memory pointer.
     #[inline]
     pub const fn phys_addr_hi(self) -> usize {
         self.phys_addr_hi

sbi-spec/src/rfnc.rs

@@ -30,7 +30,7 @@ mod fid {
     ///
     /// Declared in §8.6.
     pub const REMOTE_HFENCE_VVMA_ASID: usize = 5;
-    /// Function ID to `HFENCE.VVMA` for all address spaces in current virtual machine on remote harts.
+    /// Function ID to `HFENCE.VVMA` for all address spaces in the current virtual machine on remote harts.
     ///
     /// Declared in §8.7.
     pub const REMOTE_HFENCE_VVMA: usize = 6;

src/console.rs

@@ -25,8 +25,8 @@ pub trait Console {
     ///
     /// # Non-blocking function
     ///
-    /// 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.
+    /// This is a non-blocking SBI call, and it may do partial or no write operations
+    /// if the debug console is not able to accept more bytes.
     ///
     /// # Return value
     ///
@@ -71,11 +71,12 @@ pub trait Console {
     /// # Blocking function
     ///
     /// 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.
+    /// the specified byte to the debug console.
+    /// It will also return with `SbiRet::failed()` if there are I/O errors.
+    ///
     /// # Return value
     ///
-    /// The `SbiRet.value` is set to zero and the possible return error
+    /// The `SbiRet.value` is set to zero, and the possible return error
     /// codes returned in `SbiRet.error` are shown in the table below:
     ///
     /// | Return code               | Description

src/cppc.rs

@@ -4,14 +4,14 @@ use sbi_spec::binary::SbiRet;
 ///
 /// ACPI defines the Collaborative Processor Performance Control (CPPC) mechanism,
 /// which is an abstract and flexible mechanism for the supervisor-mode
-/// power-management software to collaborate with an entity in the platform to
+/// power-management software, to collaborate with an entity in the platform to
 /// manage the performance of the processors.
 ///
 /// The SBI CPPC extension provides an abstraction to access the CPPC registers
 /// through SBI calls. The CPPC registers can be memory locations shared with a
 /// separate platform entity such as a BMC. Even though CPPC is defined in the ACPI
 /// specification, it may be possible to implement a CPPC driver based on
-/// Device Tree.
+/// a Device Tree.
 ///
 /// The table below defines 32-bit identifiers for all CPPC registers
 /// to be used by the SBI CPPC functions. The first half of the 32-bit register
@@ -111,7 +111,7 @@ pub trait Cppc {
     /// | `SbiRet::invalid_param()` | `reg_id` is reserved.       
     /// | `SbiRet::not_supported()` | `reg_id` is not implemented by the platform.  
     /// | `SbiRet::denied()`        | `reg_id` is a read-only register.
-    /// | `SbiRet::failed()`        | The write request failed for unspecified or unknown other reasons.
+    /// | `SbiRet::failed()`        | The write-request failed for unspecified or unknown other reasons.
     fn write(&self, reg_id: u32, val: u64) -> SbiRet;
 }
 

src/hsm.rs

@@ -16,44 +16,44 @@ use sbi_spec::binary::SbiRet;
 /// | 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.
-/// | 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.
+/// | 5 | `SUSPEND_PENDING` | 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.
 /// | 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.
 ///
 /// # Topology hart groups
 ///
-/// A platform can have multiple harts grouped into a hierarchical topology groups (namely cores, clusters, nodes, etc.)
+/// A platform can have multiple harts grouped into hierarchical topology groups (namely cores, clusters, nodes, etc.)
 /// with separate platform specific low-power states for each hierarchical group.
-/// These platform specific low-power states of hierarchial topology groups can be represented as platform specific suspend states of a hart.
-/// A SBI implementation can utilize the suspend states of higher topology groups using one of the following approaches:
+/// These platform-specific low-power states of hierarchical topology groups can be represented as platform-specific suspend states of a hart.
+/// An SBI implementation can utilize the suspend states of higher topology groups using one of the following approaches:
 ///
-/// 1. *Platform-coordinated:* In this approach, when a hart becomes idle the supervisor-mode power-managment software
+/// 1. *Platform-coordinated:* In this approach, when a hart becomes idle, the supervisor-mode power-management software
 ///   will request deepest suspend state for the hart and higher topology groups.
-///   A SBI implementation should choose a suspend state at higher topology group which is:
+///   An SBI implementation should choose a suspend state at a higher topology group which is:
 /// - Not deeper than the specified suspend state
 /// - Wake-up latency is not higher than the wake-up latency of the specified suspend state
-/// 2. *OS-inititated:* In this approach, the supervisor-mode power-managment software will directly request a suspend state
-///   for higher topology group after the last hart in that group becomes idle.
-///   When a hart becomes idle, the supervisor-mode power-managment software will always select suspend state for the hart itself
-///   but it will select a suspend state for a higher topology group only if the hart is the last running hart in the group.
-///   A SBI implementation should:
-/// - Never choose a suspend state for higher topology group different from the specified suspend state
-/// - Always prefer most recent suspend state requested for higher topology group
+/// 2. *OS-initiated:* In this approach, the supervisor-mode power-management software will directly request a suspend state
+///   for a higher topology group after the last hart in that group becomes idle.
+///   When a hart becomes idle, the supervisor-mode power-management software will always select suspend state for the hart itself.
+///   However, it will select a suspend state for a higher topology group only if the hart is the last running hart in the group.
+///   An SBI implementation should:
+/// - Never choose a suspend state for a higher topology group different from the specified suspend state
+/// - Always prefer the most recent suspend state requested for a higher topology group
 ///
 /// Ref: [Section 8, RISC-V Supervisor Binary Interface Specification](https://github.com/riscv-non-isa/riscv-sbi-doc/blob/master/riscv-sbi.adoc#8-hart-state-management-extension-eid-0x48534d-hsm)
 pub trait Hsm {
     /// Request the SBI implementation to start executing the given hart at specified address in supervisor-mode.
     ///
     /// This call is asynchronous - more specifically, the `hart_start()` may return before target hart
-    /// starts executing as long as the SBI implemenation is capable of ensuring the return code is accurate.
+    /// starts executing as long as the SBI implementation 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)
     /// then it MUST configure PMP and other the M-mode state before executing in supervisor-mode.
     ///
     /// # Parameters
     ///
-    /// - The `hartid` parameter specifies the target hart which is to be started.
+    /// - 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 that will be set in the `a1` register when the hart starts executing at `start_addr`.
     ///
@@ -80,7 +80,7 @@ pub trait Hsm {
     /// |:------------------------------|:----------------------------------------------
     /// | `SbiRet::success()`           | Hart was previously in stopped state. It will start executing from `start_addr`.
     /// | `SbiRet::invalid_address()`   | `start_addr` is not valid, possibly due to the following reasons: it is not a valid physical address, or executable access to the address is prohibited by a physical memory protection mechanism or H-extension G-stage for supervisor-mode.
-    /// | `SbiRet::invalid_param()`     | `hartid` is not a valid hartid as corresponding hart cannot started in supervisor mode.
+    /// | `SbiRet::invalid_param()`     | `hartid` is not a valid hartid as corresponding hart cannot be started in supervisor mode.
     /// | `SbiRet::already_available()` | The given hartid is already started.
     /// | `SbiRet::failed()`            | The start request failed for unspecified or unknown other reasons.
     fn hart_start(&self, hartid: usize, start_addr: usize, opaque: usize) -> SbiRet;
@@ -125,15 +125,15 @@ pub trait Hsm {
     /// |:--------------------------|:------------
     /// | `SbiRet::invalid_param()` | The given `hartid` is not valid
     fn hart_get_status(&self, hartid: usize) -> SbiRet;
-    /// Request the SBI implementation to put the calling hart in a platform specfic suspend (or low power) state
-    /// specified by the `suspend_type` parameter.
+    /// Request the SBI implementation to put the calling hart in a platform specific suspend
+    /// (or low-power) state specified by the `suspend_type` parameter.
     ///
     /// The hart will automatically come out of suspended state and resume normal execution
     /// 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-retentive 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.
@@ -143,7 +143,7 @@ pub trait Hsm {
     /// 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
+    /// Resuming from a non-retentive suspend state is relatively more involved, and requires software
     /// to restore various hart registers and CSRs for all privilege modes.
     /// Upon resuming from non-retentive suspend state, the hart will jump to supervisor-mode at address
     /// specified by `resume_addr` with specific registers values described in the table below:
@@ -178,7 +178,7 @@ pub trait Hsm {
     /// hence `resume_addr` must be less than XLEN bits wide.
     ///
     /// 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
+    /// register when the hart resumes execution at `resume_addr` after a
     /// non-retentive suspend.
     ///
     /// # Return value
@@ -187,11 +187,15 @@ pub trait Hsm {
     ///
     /// | Error code                  | Description
     /// |:----------------------------|:------------
-    /// | `SbiRet::success()`         | Hart has suspended and resumed back successfully from a retentive suspend state.
+    /// | `SbiRet::success()`
+    /// | Hart has been suspended and resumed back successfully from a retentive suspend state.
     /// | `SbiRet::invalid_param()`   | `suspend_type` is not valid.
     /// | `SbiRet::not_supported()`   | `suspend_type` is valid but not implemented.
-    /// | `SbiRet::invalid_address()` | `resume_addr` is not valid, possibly due to the following reasons: it is not a valid physical address, or 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::invalid_address()` | `resume_addr` is not valid, possibly due to the following reasons:
+    /// it is not a valid physical address,
+    /// or 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.
     #[inline]
     fn hart_suspend(&self, suspend_type: u32, resume_addr: usize, opaque: usize) -> SbiRet {
         let _ = (suspend_type, resume_addr, opaque);

src/lib.rs

@@ -2,13 +2,13 @@
 //!
 //! *Note: If you are a user looking for binary distribution download for RustSBI, you may consider
 //! using the [RustSBI Prototyping System](https://github.com/rustsbi/standalone)
-//! which will provide binaries for each platforms.
+//! which will provide binaries for each platform.
 //! If you are a vendor or contributor who wants to adapt RustSBI to your new product or board,
 //! you may consider adapting the Prototyping System first to get your board adapted in a short period of time;
-//! or build a discrete crate if your team have a plenty of time working on this board.*
+//! or build a discrete crate if your team has plenty of time working on this board.*
 //!
-//! *For more details on binary downloads the the RustSBI Prototyping System,
-//! see section [Prototyping System vs discrete packages](#download-binary-file-the-prototyping-system-vs-discrete-packages).*
+//! *For more details on binary downloads the RustSBI Prototyping System,
+//! see section [Prototyping System vs. discrete packages](#download-binary-file-the-prototyping-system-vs-discrete-packages).*
 //!
 //! The crate `rustsbi` acts as core trait, extension abstraction and implementation generator
 //! of the RustSBI ecosystem.
@@ -17,7 +17,7 @@
 //!
 //! RISC-V SBI is short for RISC-V Supervisor Binary Interface. SBI acts as an interface to environment
 //! for the operating system kernel.
-//! An SBI implementation will allow furtherly bootstrap the kernel, and provide a supportive environment
+//! An SBI implementation will allow further bootstrapping the kernel and provide a supportive environment
 //! while the kernel is running.
 //!
 //! More generally, The SBI allows supervisor-mode (S-mode or VS-mode) software to be portable across
@@ -26,15 +26,15 @@
 //! # Use RustSBI services in the supervisor software
 //!
 //! SBI environment features include boot sequence and an S-mode environment. To bootstrap the
-//! S-mode software, the kernel (or other supervisor-lenel software) would be loaded
-//! into an implementation defined address, then RustSBI will prepare an environment and
+//! S-mode software, the kernel (or other supervisor-level software) would be loaded
+//! into an implementation-defined address, then RustSBI will prepare an environment and
 //! enter the S-mode software on the S-mode visible harts. If the firmware environment provides
-//! other bootloading standards upon SBI, following bootstrap process will provide further
-//! information to the supervisor software.
+//! other boot-loading standards upon SBI, following bootstrap process will provide further
+//! information on the supervisor software.
 //!
 //! ## Make SBI environment calls
 //!
-//! To use the underlying environment, the supervisor either use SBI calls or run software
+//! To use the underlying environment, the supervisor either uses SBI calls or run software
 //! implemented instructions.
 //! SBI calls are similar to the system calls for operating systems. The SBI extensions, whether
 //! defined by the RISC-V SBI Specification or by custom vendors, would either consume parameters
@@ -42,19 +42,19 @@
 //! would pick and call. Definition of parameters varies between extensions and functions.
 //!
 //! At this point, we have picked up an extension ID, a function ID, and a few SBI call parameters.
-//! Now instead of a conventinoal jump instruction, the software would invoke a special `ecall`
+//! Now instead of a conventional jump instruction, the software would invoke a special `ecall`
 //! instruction on supervisor level to transfer the control flow, resulting into a trap to the SBI
 //! environment. The SBI environment will process the `ecall` and fill in SBI call results,
 //! similar to what an operating system would handle system calls from user level.
 //!
 //! All SBI calls would return two integers: the error number and the return value.
-//! The error number will tell if the SBI call have been successfully proceeded, or which error
-//! have occurred. The return value indicates the result of a successful SBI call, whose
-//! meaning being different among different SBI extensions.
+//! The error number will tell if the SBI call has been successfully proceeded, or which error
+//! has occurred. The return value indicates the result of a successful SBI call, whose
+//! meaning is different among different SBI extensions.
 //!
 //! ## Call SBI in Rust or other programming languages
 //!
-//! Making SBI calls are similar to making system calls; RISC-V SBI calls pass extension ID,
+//! Making SBI calls is similar to making system calls; RISC-V SBI calls pass extension ID,
 //! function ID (if applicable) and parameters in integer registers.
 //!
 //! The extension ID is required to put on register `a7`, function ID on `a6` if applicable.
@@ -63,7 +63,7 @@
 //!
 //! After registers are ready, the S-mode software would invoke an `ecall` instruction.
 //! The SBI call will return two values placed in `a0` and `a1` registers;
-//! the error value could be read from `a0`, and return value is placed into `a1`.
+//! the error value could be read from `a0`, and the return value is placed into `a1`.
 //!
 //! In Rust, we would usually use crates like [`sbi-rt`](https://crates.io/crates/sbi-rt)
 //! to hide implementation details and focus on supervisor software development.
@@ -101,10 +101,10 @@
 //! ```
 //!
 //! SBI calls may fail, returning the corresponding type of error in an error code.
-//! In this example we only take the value, but in complete designs we should handle
+//! In this example, we only take the value, but in complete designs we should handle
 //! the `error` code returned by SbiRet thoroughly.
 //!
-//! In other programming languages, similiar methods may be achieved by inline assembly
+//! In other programming languages, similar methods may be achieved by inline assembly
 //! or other features; its documentation may suggest which is the best way to achieve this.
 //!
 //! # Implement RustSBI on machine environment
@@ -117,13 +117,13 @@
 //!
 //! Hypervisor and supervisor environment emulator developers may refer to
 //! [Hypervisor and emulator development with RustSBI](#hypervisor-and-emulator-development-with-rustsbi)
-//! for such purposes, as RustSBI provide different set of features dedicated for emulated or virtual
+//! for such purposes, as RustSBI provides a different set of features dedicated to emulated or virtual
 //! environments.
 //!
 //! ## Use the Prototyping System
 //!
 //! The RustSBI Prototyping System aims to get your platform working with SBI in a short period of time.
-//! It supports most RISC-V platforms available by providing scalable set of drivers and features.
+//! It supports most RISC-V platforms available by providing a scalable set of drivers and features.
 //! It provides useful custom features such as Penglai TEE, DramForever's emulated hypervisor extension,
 //! and Raven the firmware debugger framework.
 //!
@@ -132,12 +132,12 @@
 //! ## Discrete RustSBI package on bare metal RISC-V hardware
 //!
 //! Discrete packages provide developers with most scalability and complete control of underlying
-//! hardware. It is ideal if detailed SoC low power features, management cores and other features
+//! hardware. It is ideal if detailed SoC low-power features, management cores and other features
 //! would be used in the SBI implementation.
 //!
 //! RustSBI supports discrete package development out-of-box. If we are running on bare-metal, we
 //! can create a new `#![no_std]` bare-metal package, add runtime code or use runtime libraries
-//! to get started. Then, we add following lines to `Cargo.toml`:
+//! to get started. Then, we add the following lines to `Cargo.toml`:
 //!
 //! ```toml
 //! [dependencies]
@@ -149,7 +149,7 @@
 //! instructions, which fits our demand of using it on bare metal RISC-V.
 //!
 //! After hardware initialization process, the part of firmware with RustSBI linked should run on
-//! memory blocks with fast accesses, as it would be called frequently by operating system.
+//! memory blocks with fast access, as it would be called frequently by operating system.
 //! If the implementation treats the supervisor as a generator of traps, we insert `rustsbi::RustSBI`
 //! implementation in a hart executor structure.
 //!
@@ -199,8 +199,8 @@
 //! # }
 //! ```
 //!
-//! After each `run()`, the SBI implmenetaion would process the trap returned with the RustSBI
-//! instance in executor. Call the function `handle_ecall` (generated by derive macro `RustSBI`)
+//! After each `run()`, the SBI implementation would process the trap returned with the RustSBI
+//! instance in executor. Call the function `handle_ecall` (generated by the derive macro `RustSBI`)
 //! and fill in a `SupervisorContext` if necessary.
 //!
 //! ```no_run
@@ -251,14 +251,15 @@
 //!             }
 //!             // This line would also advance `sepc` with `4` to indicate the `ecall` is handled.
 //!             exec.fill_sbi_return(ans);
-//!         } else {
-//!             // other trap types ...
 //!         }
+//!         // else {
+//!         //    // other trap types ...
+//!         // }
 //!     }
 //! }
 //! ```
 //!
-//! Now, call supervisor execution function in your bare metal package to finish the discrete
+//! Now, call the supervisor execution function in your bare metal package to finish the discrete
 //! package project. Here is an example of a bare-metal entry; actual projects would either
 //! use a library for runtime, or write assemble code only if necessary.
 //!
@@ -272,7 +273,7 @@
 //!     static mut SBI_STACK: [u8; LEN_STACK_SBI] = [0; LEN_STACK_SBI];
 //!
 //!     // Note: actual assembly code varies between platforms.
-//!     // Double check documents before continue on.
+//!     // Double-check documents before continue on.
 //!     core::arch::asm!(
 //!         // 1. Turn off interrupt
 //!         "csrw  mie, zero",
@@ -316,25 +317,25 @@
 //! enum Operation {
 //!     Reboot,
 //!     Shutdown,
-//!     // Add board specific low power modes if necessary. This will allow the
-//!     // function `finalize` to operate on board specific power management chips.
+//!     // Add board-specific low-power modes if necessary. This will allow the
+//!     // function `finalize` to operate on board-specific power management chips.
 //! }
 //!
 //! /// Rust entry, call in `entry` assembly function
 //! extern "C" fn rust_main(_hart_id: usize, opaque: usize) -> Operation {
-//!     // .. board initialization process ...
+//!     // board initialization process
 //!     let board_params = board_init_once();
-//!     // .. print necessary information and rustsbi::LOGO ..
+//!     // print necessary information and rustsbi::LOGO
 //!     print_information_once();
 //!     // execute supervisor, return as Operation
 //!     execute_supervisor(&board_params)
 //! }
 //!
 //! # fn wfi() {}
-//! /// Perform board specific power operations.
+//! /// Perform board-specific power operations.
 //! ///
 //! /// The function here provides a stub to example power operations.
-//! /// Actual board developers should provide with more practical communications
+//! /// Actual board developers should provide more practical communications
 //! /// to external chips on power operation.
 //! unsafe extern "C" fn finalize(op: Operation) -> ! {
 //!     match op {
@@ -347,7 +348,7 @@
 //!             // easiest software reset is to jump to entry directly
 //!             entry()
 //!         }
-//!         // .. more power operations goes here ..
+//!         // more power operations go here
 //!     }
 //! }
 //! ```
@@ -356,35 +357,34 @@
 //! to check if it is properly implemented.
 //!
 //! 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
+//! Those platforms would typically provide two parts of code memory, the first one being relatively small, not fast
 //! 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
+//! train memory for later stages. In such a situation, RustSBI implementation should be treated as or concatenated
 //! to the second stage bootloader, and the first stage could be a standalone binary package bundled with it.
 //!
 //! # Hypervisor and emulator development with RustSBI
 //!
-//! RustSBI crate supports to develop RISC-V emulators, and both Type-1 and Type-2 hypervisors.
-//! Hypervisor developers may find it easy to handle standard SBI functions with an instance
-//! based RustSBI interface.
+//! RustSBI crate supports developing RISC-V emulators, and both Type-1 and Type-2 hypervisors.
+//! Hypervisor developers may find it easy to handle standard SBI functions with an instance-based RustSBI interface.
 //!
 //! ## Hypervisors using RustSBI
 //!
-//! Both Type-1 and Type-2 hypervisors on RISC-V run on HS-mode hardware. Depending on demands
-//! of virtualized systems, hypervisors may either provide transparent information from host machine
+//! Both Type-1 and Type-2 hypervisors on RISC-V run on HS-mode hardware. Depending on the demands
+//! of virtualized systems, hypervisors may either provide transparent information from the host machine
 //! or provide another set of information to override the current environment. Notably,
 //! RISC-V hypervisors do not have direct access to machine mode (M-mode) registers.
 //!
 //! RustSBI supports both by accepting an implementation of the `EnvInfo` trait.
-//! If RISC-V hypervisors choose to use existing information on current machine,
-//! it may require to call underlying M-mode environment using SBI calls and fill in information
+//! If RISC-V hypervisors choose to use existing information on the current machine,
+//! it may require calling underlying M-mode environment using SBI calls and fill in information
 //! into the variable implementing trait `EnvInfo`.
 //! If hypervisors use customized information other than taking the same one from the
 //! environment they reside in, they may build custom structures implementing `EnvInfo` to provide
 //! customized machine information.
 //! Deriving a RustSBI instance without bare-metal support would require an `EnvInfo` implementation
-//! as a input of the derive macro.
+//! as an input of the derive-macro.
 //!
 //! To begin with, include the RustSBI library in file `Cargo.toml`:
 //!
@@ -393,8 +393,8 @@
 //! rustsbi = "0.4.0"
 //! ```
 //!
-//! This will disable default feature `machine` which will assume that RustSBI runs on M-mode directly,
-//! which is not appropriate in our purpose. After that, define an SBI structure and derive its `RustSBI`
+//! This will disable the default feature `machine` which will assume that RustSBI runs on M-mode directly,
+//! which is not appropriate for our purpose. After that, define an SBI structure and derive its `RustSBI`
 //! implementation using `#[derive(RustSBI)]`. The defined SBI structure can be placed in
 //! a virtual machine structure representing a control flow executor to prepare for SBI environment:
 //!
@@ -404,7 +404,7 @@
 //! #[derive(RustSBI)]
 //! struct MySBI {
 //!     // add other fields later ...
-//!     // An environment information must be provided on
+//!     // The environment information must be provided on
 //!     // non-bare-metal RustSBI development.
 //!     info: MyEnvInfo,
 //! }
@@ -423,7 +423,7 @@
 //!
 //! When the virtual machine hart traps into hypervisor, its code should decide whether
 //! this trap is an SBI environment call. If that is true, pass in parameters by `sbi.handle_ecall`
-//! function. RustSBI will handle with SBI standard constants, call corresponding extension field
+//! function. RustSBI will handle with SBI standard constants, call the corresponding extension field
 //! and provide parameters according to the extension and function IDs (if applicable).
 //!
 //! Crate `rustsbi` adapts to standard RISC-V SBI calls.
@@ -452,9 +452,9 @@
 //!     if let Trap::Exception(Exception::SupervisorEcall) = trap.cause() {
 //!         // Firstly, handle custom extensions
 //!         let my_extension_sbiret = hart.my_extension_sbi.handle_ecall(hart.trap_params());
-//!         // If custom extension handles correctly, fill in its result and continue to hart.
+//!         // If the custom extension handles correctly, fill in its result and continue to hart.
 //!         // The custom handler may handle `probe_extension` in `base` extension as well
-//!         // to allow detections to whether custom extension exists.
+//!         // to allow detections to whether a custom extension exists.
 //!         if my_extension_sbiret != SbiRet::not_supported() {
 //!             hart.fill_in(my_extension_sbiret);
 //!             continue;
@@ -471,7 +471,7 @@
 //! ## Emulators using RustSBI
 //!
 //! 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,
+//! 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.
@@ -479,7 +479,7 @@
 //! 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
+//! # Download binary file: the Prototyping System vs. discrete packages
 //!
 //! RustSBI ecosystem would typically provide support for most platforms. Those support packages
 //! would be provided either from the RustSBI Prototyping System or vendor provided discrete SBI
@@ -490,18 +490,18 @@
 //! It also includes a universal test kernel to allow testing SBI implementations on current environment.
 //! Users may choose to download from [Prototyping System repository](https://github.com/rustsbi/standalone)
 //! to get various types of RustSBI packages for their boards.
-//! Vendors and contributors may find it easy to adapt new SoCs and boards into Prototyping System.
+//! Vendors and contributors may find it easy to adapt new SoCs and boards into the Prototyping System.
 //!
 //! 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
+//! maintenance situation would vary between vendors, and it would likely 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.
 //!
 //! To download binary package for the Prototyping System, visit its project website for a download link.
-//! To download them for discrete packages, RustSBI users may visit distribution source of SoC or board
+//! To download them for discrete packages, RustSBI users may visit distribution sources of SoC or board
 //! manufacturers. Additionally, users may visit [the awesome page](https://github.com/rustsbi/awesome-rustsbi)
 //! for a curated list of both Prototyping System and discrete packages provided by RustSBI ecosystem.
 //!
@@ -511,26 +511,26 @@
 //!
 //! ## RustSBI is a library for interfaces
 //!
-//! This library adapts to individual Rust traits and a derive macro to provide basic SBI features.
+//! This library adapts to individual Rust traits and a derive-macro to provide basic SBI features.
 //! When building for a specific platform, implement traits in this library and pass the types into
-//! a structure to derive RustSBI macro onto. After that, `handle_ecall`  would be called in the
-//! platform specific exception handler.
+//! a structure to derive RustSBI macro onto. After that, `handle_ecall` would be called in the
+//! platform-specific exception handler.
 //! The derive macro `RustSBI` would dispatch parameters from supervisor to the trait implementations
 //! to handle the SBI calls.
 //!
-//! The library also implements useful constants which may help with platform specific binaries.
+//! The library also implements useful constants which may help with platform-specific binaries.
 //! The `LOGO` and information on `VERSION` can be printed if necessary on SBI initialization
 //! processes.
 //!
-//! Note that this crate is a library which contains common building blocks in SBI implementation.
-//! The RustSBI ecosystem would provide different level of support for each board, those support
-//! packages would use `rustsbi` crate as library to provide different type of SBI binary releases.
+//! Note that this crate is a library that contains common building blocks in SBI implementation.
+//! The RustSBI ecosystem would provide different levels of support for each board, those support
+//! packages would use `rustsbi` crate as a library to provide different types of SBI binary releases.
 //!
 //! ## Hardware discovery and feature detection
 //!
 //! According to the RISC-V SBI specification, the SBI itself 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, ACPI, vendor specific ones or upcoming `configptr` CSRs)
+//! discovery methods (i.e., Device Tree, ACPI, vendor-specific ones or upcoming `configptr` CSRs)
 //! for that purpose.
 //!
 //! To detect any feature under bare metal or under supervisor level, developers may depend on
@@ -585,7 +585,7 @@ pub extern crate sbi_spec as spec;
 
 pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 
-/// Generate `RustSBI` implementation for structure of each extensions.
+/// Generate `RustSBI` implementation for structure of each extension.
 ///
 /// # Usage
 ///
@@ -612,8 +612,8 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// ```
 ///
 /// Here, we declared the field named `fence` with type `MyFence`. The variable name `fence` is special,
-/// it tells RustSBI derive macro that this field implements SBI Remote Fence instead of other SBI extensions.
-/// We can continue to adding more fields into `MySBI`. For example, if we have RISC-V SBI Time extension
+/// it tells the RustSBI derive-macro that this field implements SBI Remote Fence instead of other SBI extensions.
+/// We can continue to add more fields into `MySBI`. For example, if we have RISC-V SBI Time extension
 /// implementation with type `MyTimer`, we can add it to `MySBI`:
 ///
 /// ```rust
@@ -667,7 +667,7 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 ///
 /// The error message hints that we didn't provide any SBI environment information implementing trait
 /// `EnvInfo`. By default, RustSBI is targeted to provide RISC-V supervisor environment on any hardware,
-/// targeting hypervisor, emulator and binary translation applications. In this case, the virtualized
+/// focusing on hypervisor, emulator and binary translation applications. In this case, the virtualized
 /// environment should provide the supervisor with machine environment information like `mvendorid`,
 /// `marchid` and `mimpid` values. RustSBI could also be used on bare-metal RISC-V machines where such
 /// values would be directly accessible through CSR read operations.
@@ -680,8 +680,8 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// rustsbi = { version = "0.4.0", features = ["machine"] }
 /// ```
 ///
-/// If that's not the case and we are writing a virtualization targeted application, we should add a
-/// `EnvInfo` implementation into the structure like `MySBI` mentioned above, with a special field
+/// If that's not the case, and we are writing a virtualization-targeted application, we should add a
+/// `EnvInfo` implementation into the structure like `MySBI` mentioned above, with the special field
 /// name `info`. We can do it like:
 ///
 /// ```rust
@@ -717,11 +717,11 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// # }
 /// ```
 ///
-/// Then, when we compile our code with `MySBI`, we'll found that the code now compiles successfully.
+/// Then, when we compile our code with `MySBI`, we'll find that the code now compiles successfully.
 ///
 /// To use the derived `RustSBI` implementation, we note out that this structure now implements the trait
-/// `RustSBI` with function `handle_ecall`. We can pass SBI extension, function and parameters into
-/// `handle_ecall`, and reads the SBI call result from its return value with the type `SbiRet`.
+/// `RustSBI` with function `handle_ecall`. We can pass the SBI extension, function and parameters into
+/// `handle_ecall`, and read the SBI call result from its return value with the type `SbiRet`.
 /// To illustrate this feature, we make an SBI call to read the SBI implementation ID, like:
 ///
 /// ```rust
@@ -753,13 +753,13 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// # }
 /// ```
 ///
-/// Run the code and we'll find following output in the console:
+/// Run the code, and we'll find the following output in the console:
 ///
 /// ```text
 /// SBI implementation ID for MySBI: 4
 /// ```
 ///
-/// The SBI call returns the number 4 as SBI call result. By looking up
+/// The SBI call returns the number 4 as the SBI call result. By looking up
 /// [the RISC-V SBI Specification](https://github.com/riscv-non-isa/riscv-sbi-doc/blob/cf86bda6f57afb8e0e7011b61504d4e8664b9b1d/src/ext-base.adoc#sbi-implementation-ids),
 /// we can know that RustSBI have the implementation ID of 4. You have successfully made your first
 /// SBI call from a derived `RustSBI` implementation!
@@ -770,18 +770,18 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// mode. Each `ecall` raises a RISC-V exception which the environment must process with. The SBI
 /// environment, either bare-metal or virtually, would save context, read extension, function and parameters
 /// and call the `handle_ecall` function provided by `RustSBI` trait. Then, the function returns
-/// with an `SbiRet`; we reads back `value` and `error` to store them into the saved context.
+/// with an `SbiRet`; we read back `value` and `error` to store them into the saved context.
 /// Finally, when the context restores, the supervisor mode software (kernels, etc.) could get the
 /// SBI call result from register values.
 ///
-/// Now we have learned basical usages of the derive macro `RustSBI`. We can dive deeper and use RustSBI
+/// Now we have learned basic usages of the derive-macro `RustSBI`. We can dive deeper and use RustSBI
 /// in real cases with ease. Congratulations!
 ///
 /// # Supported extensions
 ///
 /// The derive macro `RustSBI` supports all the standard RISC-V SBI extensions this library supports.
 /// When we add extensions into SBI structure fields, special field names are identified by RustSBI
-/// derive macro. Here is a list on them:
+/// derive macro. Here is a list of them:
 ///
 /// | Field names | RustSBI trait | Extension |
 /// |:------------|:----------|:--------------|
@@ -798,7 +798,7 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// | `sta` | [`Sta`](trait.Sta.html) | Steal Time Accounting extension |
 ///
 /// The `EnvInfo` parameter is used by RISC-V SBI Base extension which is always supported on all
-/// RISC-V SBI implementations. RustSBI provides Base extension with additional `EnvInfo` by default.
+/// RISC-V SBI implementations. RustSBI provides the Base extension with additional `EnvInfo` by default.
 ///
 /// | Field names | RustSBI trait | Description |
 /// |:------------|:----------|:--------------|
@@ -807,12 +807,12 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// Or, if `#[cfg(feature = "machine")]` is enabled, RustSBI derive macro does not require additional
 /// machine environment information but reads them by RISC-V CSR operation when we don't have any `EnvInfo`s
 /// in the structure. This feature would only work if RustSBI runs directly on machine mode hardware.
-/// If we are targeting other environments (virtualization etc.) we should provide `EnvInfo` instead
+/// If we are targeting other environments (virtualization etc.), we should provide `EnvInfo` instead
 /// of using the machine feature.
 ///
 /// # Examples
 ///
-/// This macro should be used over a struct of RISC-V SBI extension implementaions.
+/// This macro should be used over a struct of RISC-V SBI extension implementations.
 /// For example:
 ///
 /// ```rust
@@ -911,7 +911,7 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 ///
 /// // The derived `MySBI` implementation ignores the `fence: MyFence`. It can now
 /// // be used as a conventional struct field.
-/// // Notably, a `#[warn(unused)]` would be raised if `fence` is not furtherly used
+/// // Notably, a `#[warn(unused)]` would be raised if `fence` is not further used
 /// // by following code; `console` and `info` fields are not warned because they are
 /// // internally used by the trait implementation derived in the RustSBI macro.
 /// # use rustsbi::RustSBI;
@@ -936,7 +936,7 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// # }
 /// ```
 ///
-/// In some cases we may manually assign fields to certain SBI extension other than defaulting
+/// In some cases, we may manually assign fields to a certain SBI extension other than defaulting
 /// to special names defined above, and sometimes we need to provide multiple SBI extensions
 /// with one field only. By listing the extension names separated by comma in the helper attribute,
 /// we can assign one or multiple SBI extensions to a field to solve the issues above.
@@ -1000,7 +1000,7 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// # }
 /// ```
 ///
-/// RustSBI implementations usually provide regular structs to the derive macro.
+/// RustSBI implementations usually provide regular structs to the derive-macro.
 /// Alternatively, the RustSBI derive macro also accepts tuple structs or unit structs.
 ///
 /// ```rust
@@ -1027,8 +1027,8 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// ```
 /// ```rust
 /// // Unit structs.
-/// // Note that `info` is required on non-machine enironment; thus this crate
-/// // only allow unit structs with `machine` feature. No extensions except Base
+/// // Note that `info` is required in non-machine environment; thus this crate
+/// // only allows unit structs with `machine` feature. No extensions except Base
 /// // extension are provided on unit struct implementations.
 /// # use rustsbi::RustSBI;
 /// # #[cfg(feature = "machine")]
@@ -1037,7 +1037,7 @@ pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
 /// ```
 ///
 /// # Notes
-// note: following documents are inherted from `RustSBI` in the `rustsbi_macros` package.
+// note: the following documents are inherited from `RustSBI` in the `rustsbi_macros` package.
 #[doc(inline)]
 pub use rustsbi_macros::RustSBI;
 

src/pmu.rs

@@ -108,7 +108,7 @@ pub trait Pmu {
     /// | Return code               | Description
     /// |:--------------------------|:----------------------------------------------
     /// | `SbiRet::success()`       | counter found and configured successfully.
-    /// | `SbiRet::invalid_param()` | set of counters has at least one invalid counter.
+    /// | `SbiRet::invalid_param()` | the set of counters has at least one invalid counter.
     /// | `SbiRet::not_supported()` | none of the counters can monitor the specified event.
     fn counter_config_matching(
         &self,
@@ -142,8 +142,8 @@ pub trait Pmu {
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
     /// | `SbiRet::success()`         | counter started successfully.
-    /// | `SbiRet::invalid_param()`   | set of counters has at least one invalid counter.
-    /// | `SbiRet::already_started()` | set of counters includes at least one counter which is already started.
+    /// | `SbiRet::invalid_param()`   | the set of counters has at least one invalid counter.
+    /// | `SbiRet::already_started()` | the set of counters includes at least one counter which is already started.
     fn counter_start(
         &self,
         counter_idx_base: usize,
@@ -170,8 +170,8 @@ pub trait Pmu {
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
     /// | `SbiRet::success()`         | counter stopped successfully.
-    /// | `SbiRet::invalid_param()`   | set of counters has at least one invalid counter.
-    /// | `SbiRet::already_stopped()` | set of counters includes at least one counter which is already stopped.
+    /// | `SbiRet::invalid_param()`   | the set of counters has at least one invalid counter.
+    /// | `SbiRet::already_stopped()` | the set of counters includes at least one counter which is already stopped.
     fn counter_stop(
         &self,
         counter_idx_base: usize,

src/rfence.rs

@@ -82,7 +82,7 @@ pub trait Rfence {
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
     /// | `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::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 {

src/sta.rs

@@ -21,7 +21,7 @@ pub trait Sta {
     /// calling virtual hart and enable the SBI implementation's steal-time information
     /// reporting.
     ///
-    /// 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 64-byte aligned. The size of the shared memory must be 64 bytes.
     /// The SBI implementation MUST zero the shared memory before returning from the SBI
@@ -34,7 +34,7 @@ pub trait Sta {
     ///
     /// It is not expected for the shared memory to be written by the supervisor-mode
     /// software while it is in use for steal-time accounting. However, the SBI
-    /// implementation MUST not misbehave if a write from supervisor-mode software
+    /// implementation MUST not misbehave if a write operation from supervisor-mode software
     /// occurs, however, in that case, it MAY leave the shared memory filled with
     /// inconsistent data.
     ///

src/susp.rs

@@ -1,8 +1,8 @@
 use sbi_spec::binary::SbiRet;
 
-/// System Suspend extension.
+/// System-Suspend extension.
 ///
-/// The system suspend extension defines a set of system-level sleep states and a
+/// The system-suspend extension defines a set of system-level sleep states and a
 /// function which allows the supervisor-mode software to request that the system
 /// transitions to a sleep state. Sleep states are identified with 32-bit wide
 /// identifiers (`sleep_type`). The possible values for the identifiers are shown
@@ -21,7 +21,7 @@ use sbi_spec::binary::SbiRet;
 ///
 /// The system suspend extension does not provide any way for supported sleep types
 /// to be probed. Platforms are expected to specify their supported system sleep
-/// types and per-type wake up devices in their hardware descriptions. The
+/// types and per-type wake-up devices in their hardware descriptions. The
 /// `SUSPEND_TO_RAM` sleep type is the one exception, and its presence is implied
 /// by that of the extension.
 pub trait Susp {

src/traits.rs

@@ -49,7 +49,7 @@ impl<T: EnvInfo> EnvInfo for &T {
 }
 
 // Macro internal structures and functions.
-// DO NOT USE code here directly; use derive macro #[derive(RustSBI)] instead.
+// DO NOT USE code here directly; use derive-macro #[derive(RustSBI)] instead.
 
 #[cfg(feature = "machine")]
 #[doc(hidden)]
@@ -97,8 +97,8 @@ pub fn _rustsbi_base_env_info<T: EnvInfo, U: _ExtensionProbe>(
 
 // Probe not only standard SBI extensions, but also (reserving for) custom extensions.
 // For standard SBI extensions only, the macro would use `_StandardExtensionProbe`;
-// for implementation with custom SBI extension, a custom structure implementing this trait
-// would be used by macro.
+// for implementation with custom SBI extensions, macro would use a custom structure
+// implementing this trait.
 pub trait _ExtensionProbe {
     // Implementors are encouraged to add #[inline] hints on this function.
     fn probe_extension(&self, extension: usize) -> usize;
@@ -118,7 +118,7 @@ pub struct _StandardExtensionProbe {
     pub cppc: usize,
     pub nacl: usize,
     pub sta: usize,
-    // NOTE: don't forget to add to `fn probe_extension` in `impl _ExtensionProbe` as well
+    // NOTE: remember to add to `fn probe_extension` in `impl _ExtensionProbe` as well
 }
 
 impl _ExtensionProbe for _StandardExtensionProbe {