lib: (3/n) grammar fixes on documentation

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

sbi-rt/src/base.rs

@@ -11,11 +11,11 @@ use sbi_spec::base::{
 /// Return the current SBI specification version.
 ///
 /// The minor number of the SBI specification is encoded in the low 24 bits,
-/// with the major number encoded in the next 7 bits. Bit 31 must be 0 and
-/// is reserved for future expansion.
+/// with the major number encoded in the next 7 bits.
+/// Bit 31 must be zero and is reserved for future expansion.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 4.1.
-/// According to introduction of chapter 4, all base extension functions
+/// According to the introduction of chapter 4, all base extension functions
 /// must success and return no error code.
 #[inline]
 pub fn get_spec_version() -> Version {
@@ -29,7 +29,7 @@ pub fn get_spec_version() -> Version {
 /// for SBI implementation quirks.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 4.2.
-/// According to introduction of chapter 4, all base extension functions
+/// According to the introduction of chapter 4, all base extension functions
 /// must success and return no error code.
 #[inline]
 pub fn get_sbi_impl_id() -> usize {
@@ -41,21 +41,21 @@ pub fn get_sbi_impl_id() -> usize {
 /// The encoding of this version number is specific to the SBI implementation.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 4.3.
-/// According to introduction of chapter 4, all base extension functions
+/// According to the introduction of chapter 4, all base extension functions
 /// must success and return no error code.
 #[inline]
 pub fn get_sbi_impl_version() -> usize {
     sbi_call_0(EID_BASE, GET_SBI_IMPL_VERSION).value
 }
 
-/// Probe information about one SBI extension from current environment.
+/// Probe information about one SBI extension from the current environment.
 ///
 /// Returns 0 if given SBI `extension_id` is not available, or typically
 /// 1 if it's available. Implementation would define further non-zero
 /// return values for information about this extension if it is available.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 4.4.
-/// According to introduction of chapter 4, all base extension functions
+/// According to the introduction of chapter 4, all base extension functions
 /// must success and return no error code.
 #[inline]
 pub fn probe_extension<E>(extension: E) -> ExtensionInfo
@@ -66,39 +66,39 @@ where
     ExtensionInfo { raw: ans.value }
 }
 
-/// Return value of `mvendorid` register in current environment.
+/// Return the value of `mvendorid` register in the current environment.
 ///
 /// This function returns a value that is legal for the `mvendorid` register,
 /// and 0 is always a legal value for this register.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 4.5.
-/// According to introduction of chapter 4, all base extension functions
+/// According to the introduction of chapter 4, all base extension functions
 /// must success and return no error code.
 #[inline]
 pub fn get_mvendorid() -> usize {
     sbi_call_0(EID_BASE, GET_MVENDORID).value
 }
 
-/// Return value of `marchid` register in current environment.
+/// Return value of `marchid` register in the current environment.
 ///
 /// This function returns a value that is legal for the `marchid` register,
 /// and 0 is always a legal value for this register.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 4.6.
-/// According to introduction of chapter 4, all base extension functions
+/// According to the introduction of chapter 4, all base extension functions
 /// must success and return no error code.
 #[inline]
 pub fn get_marchid() -> usize {
     sbi_call_0(EID_BASE, GET_MARCHID).value
 }
 
-/// Return value of `mimpid` register in current environment.
+/// Return value of `mimpid` register in the current environment.
 ///
 /// This function returns a value that is legal for the `mimpid` register,
 /// and 0 is always a legal value for this register.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 4.7.
-/// According to introduction of chapter 4, all base extension functions
+/// According to the introduction of chapter 4, all base extension functions
 /// must success and return no error code.
 #[inline]
 pub fn get_mimpid() -> usize {

sbi-rt/src/cppc.rs

@@ -78,7 +78,7 @@ pub fn cppc_read(cppc_reg_id: u32) -> SbiRet {
 /// | `SbiRet::invalid_param()` | `cppc_reg_id` is reserved.
 /// | `SbiRet::not_supported()` | `cppc_reg_id` is not implemented by the platform.
 /// | `SbiRet::denied()`        | `cppc_reg_id` is a write-only register.
-/// | `SbiRet::failed()`        | The read request failed for unspecified or unknown other reasons.
+/// | `SbiRet::failed()`        | The read operation request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 14.3.
 #[inline]
@@ -104,7 +104,7 @@ pub fn cppc_read_hi(cppc_reg_id: u32) -> SbiRet {
 /// | `SbiRet::invalid_param()` | `cppc_reg_id` is reserved.
 /// | `SbiRet::not_supported()` | `cppc_reg_id` is not implemented by the platform.
 /// | `SbiRet::denied()`        | `cppc_reg_id` is a read-only register.
-/// | `SbiRet::failed()`        | The write request failed for unspecified or unknown other reasons.
+/// | `SbiRet::failed()`        | The write operation request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 14.4.
 #[inline]

sbi-rt/src/dbcn.rs

@@ -14,7 +14,7 @@ use sbi_spec::{
 ///
 /// # 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 or no write operations if
 /// the debug console is not able to accept more bytes.
 ///
 /// # Return value
@@ -51,7 +51,7 @@ pub fn console_write(bytes: Physical<&[u8]>) -> SbiRet {
 ///
 /// # 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.
 ///
@@ -82,12 +82,12 @@ pub fn console_read(bytes: Physical<&mut [u8]>) -> SbiRet {
 ///
 /// # 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.
+/// 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
 ///
-/// 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

sbi-rt/src/hsm.rs

@@ -6,17 +6,20 @@ use sbi_spec::hsm::{EID_HSM, HART_GET_STATUS, HART_START, HART_STOP, HART_SUSPEN
 
 /// 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.
+/// This call is asynchronous - more specifically, the `hart_start()` may return before target hart 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.
+/// 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 `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 `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`.
 ///
 /// *NOTE:* A single `usize` parameter is sufficient as `start_addr`,
 /// because the hart will start execution in the supervisor-mode with MMU off,
@@ -24,7 +27,8 @@ use sbi_spec::hsm::{EID_HSM, HART_GET_STATUS, HART_START, HART_STOP, HART_SUSPEN
 ///
 /// # Behavior
 ///
-/// The target hart jumps to supervisor mode at address specified by `start_addr` with following values in specific registers.
+/// The target hart jumps to supervisor mode at the address specified by `start_addr`
+/// with the following values in specific registers.
 ///
 /// | Register Name | Register Value
 /// |:--------------|:--------------
@@ -39,9 +43,13 @@ use sbi_spec::hsm::{EID_HSM, HART_GET_STATUS, HART_START, HART_STOP, HART_SUSPEN
 ///
 /// | Return code                   | Description
 /// |:------------------------------|:----------------------------------------------
-/// | `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 the address is prohibited by PMP or H-extension G-stage to run in supervisor-mode.
-/// | `SbiRet::invalid_param()`     | `hartid` is not a valid hartid as corresponding hart cannot started in supervisor mode.
+/// | `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 the address is prohibited by PMP or H-extension G-stage to run 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 unknown reasons.
 ///
@@ -112,21 +120,21 @@ pub fn hart_get_status(hartid: usize) -> SbiRet {
 /// (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 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-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.
 ///
 /// # 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
+/// Resuming from a non-retentive suspend state is relatively more involved, and it 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:
@@ -140,7 +148,7 @@ pub fn hart_get_status(hartid: usize) -> SbiRet {
 ///
 /// # Parameters
 ///
-/// The `suspend_type` parameter is 32 bits wide and the possible values are shown in the table below:
+/// The `suspend_type` parameter is 32 bits wide, and the possible values are shown in the table below:
 ///
 /// | Value                   | Description
 /// |:------------------------|:--------------
@@ -160,8 +168,8 @@ pub fn hart_get_status(hartid: usize) -> SbiRet {
 /// because the hart will resume execution in the supervisor-mode with MMU off,
 /// hence the `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
 /// non-retentive suspend.
 ///
 /// # Return value
@@ -170,7 +178,7 @@ pub fn hart_get_status(hartid: usize) -> SbiRet {
 ///
 /// | 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 the address is prohibited by PMP or H-extension G-stage to run in supervisor-mode.

sbi-rt/src/legacy.rs

@@ -79,7 +79,7 @@ pub fn remote_fence_vma_asid(hart_mask: usize, start: usize, size: usize, asid:
 
 /// §5.9
 ///
-/// Replaced by [`system_reset`](super::system_reset) from [`SRST`](super::EID_SRST) extension.
+/// Replaced by [`system_reset`](super::system_reset) in the [`SRST`](super::EID_SRST) extension.
 #[deprecated = "replaced by `system_reset` from System `SRST` extension"]
 #[inline]
 pub fn shutdown() -> ! {

sbi-rt/src/nacl.rs

@@ -34,11 +34,11 @@ pub fn nacl_probe_feature(feature_id: u32) -> SbiRet {
 ///
 /// # Parameters
 ///
-/// If `shmem` parameter is not all-ones bitwise then `shmem` specifies the shared
-/// memory physical base address. `shmem` MUST be 4096 bytes (i.e. page) aligned and
+/// If `shmem` parameter is not all-ones bitwise, then `shmem` specifies the shared
+/// memory physical base address. `shmem` MUST be 4096 bytes (i.e., page) aligned, and
 /// the size of the shared memory must be `4096 + (XLEN * 128)` bytes.
 ///
-/// If `shmem` parameter is all-ones bitwise then the nested acceleration features
+/// If `shmem` parameter is all-ones bitwise, then the nested acceleration features
 /// are disabled.
 ///
 /// The `flags` parameter is reserved for future use and must be zero.
@@ -65,13 +65,13 @@ pub fn nacl_set_shmem(shmem: SharedPtr<[u8; shmem_size::NATIVE]>, flags: usize)
 
 /// Synchronize CSRs in the nested acceleration shared memory.
 ///
-/// This is an optional function which is only available if the SBI_NACL_FEAT_SYNC_CSR feature is available.
+/// This is an 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 implementation (or L0 hypervisor) are synchronized.
+/// 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 CSR specified by the csr_num parameter is synchronized.
@@ -95,13 +95,13 @@ pub fn nacl_sync_csr(csr_num: usize) -> SbiRet {
 
 /// Synchronize HFENCEs in the nested acceleration shared memory.
 ///
-/// This is an optional function which is only available if the SBI_NACL_FEAT_SYNC_HFENCE feature is available.
+/// This is an 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 synchronized.
+/// 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 specified by the `entry_index` parameter is synchronized
 ///
@@ -124,15 +124,15 @@ pub fn nacl_sync_hfence(entry_index: usize) -> SbiRet {
 
 /// Synchronize CSRs and HFENCEs in the NACL shared memory and emulate the SRET instruction.
 ///
-/// This is an optional function which is only available if the SBI_NACL_FEAT_SYNC_SRET feature is available.
+/// 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
+/// This function is used by supervisor software (or L1 hypervisor) to do a synchronizing 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 `SbiRet.error` upon failure are shown in table below:
+/// This function does not return upon success, and the possible error codes
+/// returned in `SbiRet.error` upon failure are shown in the table below:
 ///
 /// | Error code                | Description
 /// |:--------------------------|:------------

sbi-rt/src/pmu.rs

@@ -20,7 +20,7 @@ pub fn pmu_num_counters() -> usize {
 /// Get details about the specified counter.
 ///
 /// The value returned includes details such as underlying CSR number, width of the counter,
-/// type of counter hardware/firmware, etc.
+/// type of counter (hardware or firmware), etc.
 ///
 /// The `counter_info` returned by this SBI call is encoded as follows:
 ///
@@ -62,7 +62,7 @@ pub fn pmu_counter_get_info(counter_idx: usize) -> SbiRet {
 /// whereas the `event_idx` represent the event to be monitored
 /// and `event_data` represents any additional event configuration.
 ///
-/// The `config_flags` parameter represent additional counter configuration and filter flags.
+/// The `config_flags` parameter represents additional configuration and filter flags of the counter.
 /// The bit definitions of the `config_flags` parameter are shown in the table below:
 ///
 /// | Flag Name                    | Bits       | Description
@@ -82,7 +82,7 @@ pub fn pmu_counter_get_info(counter_idx: usize) -> SbiRet {
 /// 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 the 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
@@ -151,8 +151,8 @@ where
 /// | 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
 ///
@@ -241,13 +241,13 @@ where
 
 /// Provide the current value of a firmware counter.
 ///
-/// 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 current
+/// 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 a user provides a hardware counter in `counter_idx` parameter.
 ///
 /// # Return value
 ///
@@ -264,7 +264,7 @@ pub fn pmu_counter_fw_read(counter_idx: usize) -> SbiRet {
     sbi_call_1(EID_PMU, COUNTER_FW_READ, counter_idx)
 }
 
-/// Provide the upper 32 bits of the current firmware counter value.
+/// Provide the upper 32 bits from the value of a firmware counter.
 ///
 /// This function always returns zero in `SbiRet.value` for RV64 (or higher) systems.
 ///

sbi-rt/src/rfnc.rs

@@ -14,7 +14,7 @@ use sbi_spec::{
 ///
 /// # 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.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.1.
 #[inline]
@@ -34,7 +34,7 @@ pub fn remote_fence_i(hart_mask: HartMask) -> SbiRet {
 ///
 /// | 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.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.2.
@@ -51,7 +51,7 @@ pub fn remote_sfence_vma(hart_mask: HartMask, start_addr: usize, size: usize) ->
     )
 }
 
-/// Execute address space based `SFENCE.VMA` instructions on remote harts.
+/// Execute address-space-based `SFENCE.VMA` instructions on remote harts.
 ///
 /// This function instructs the remote harts to execute one or more `SFENCE.VMA` instructions,
 /// covering the range of virtual addresses between `start_addr` and `size`.
@@ -63,7 +63,7 @@ pub fn remote_sfence_vma(hart_mask: HartMask, start_addr: usize, size: usize) ->
 ///
 /// | 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.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.3.
@@ -92,7 +92,7 @@ pub fn remote_sfence_vma_asid(
 /// instructions, 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
 ///
@@ -100,7 +100,7 @@ pub fn remote_sfence_vma_asid(
 ///
 /// | 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::not_supported()`   | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
 /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
 ///
@@ -130,7 +130,7 @@ pub fn remote_hfence_gvma_vmid(
 /// 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
 ///
@@ -138,7 +138,7 @@ pub fn remote_hfence_gvma_vmid(
 ///
 /// | 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::not_supported()`   | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
 /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
 ///
@@ -163,7 +163,7 @@ pub fn remote_hfence_gvma(hart_mask: HartMask, start_addr: usize, size: usize) -
 /// 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
 ///
@@ -171,7 +171,7 @@ pub fn remote_hfence_gvma(hart_mask: HartMask, start_addr: usize, size: usize) -
 ///
 /// | 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::not_supported()`   | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
 /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
 ///
@@ -195,13 +195,13 @@ pub fn remote_hfence_vvma_asid(
     )
 }
 
-/// Execute `HFENCE.VVMA` for all address spaces in current virtual machine on remote harts.
+/// Execute `HFENCE.VVMA` for all address spaces in the current virtual machine on remote harts.
 ///
 /// This function instructs the remote harts to execute one or more `HFENCE.VVMA` instructions,
 /// 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
 ///
@@ -209,7 +209,7 @@ pub fn remote_hfence_vvma_asid(
 ///
 /// | 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::not_supported()`   | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
 /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
 ///

sbi-rt/src/srst.rs

@@ -14,9 +14,10 @@ use sbi_spec::srst::{
 /// # 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.
@@ -101,9 +102,9 @@ macro_rules! define_reset_param {
 }
 
 define_reset_param! {
-    Shutdown(RESET_TYPE_SHUTDOWN): ResetType /// Shutdown as reset type.
-    ColdReboot(RESET_TYPE_COLD_REBOOT): ResetType /// Cold reboot as reset type.
-    WarmReboot(RESET_TYPE_WARM_REBOOT): ResetType /// Warm reboot as reset type.
-    NoReason(RESET_REASON_NO_REASON): ResetReason /// No reason as reset reason.
-    SystemFailure(RESET_REASON_SYSTEM_FAILURE): ResetReason /// System failure as reset reason.
+    Shutdown(RESET_TYPE_SHUTDOWN): ResetType /// Shutdown as a reset type.
+    ColdReboot(RESET_TYPE_COLD_REBOOT): ResetType /// Cold reboot as a reset type.
+    WarmReboot(RESET_TYPE_WARM_REBOOT): ResetType /// Warm reboot as a reset type.
+    NoReason(RESET_REASON_NO_REASON): ResetReason /// No reason as a reset reason.
+    SystemFailure(RESET_REASON_SYSTEM_FAILURE): ResetReason /// System failure as a reset reason.
 }

sbi-rt/src/sta.rs

@@ -14,7 +14,7 @@ use sbi_spec::{
 ///
 /// 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 occurs, however, in that case,
+/// if a write operation from supervisor-mode software occurs, however, in that case,
 /// it MAY leave the shared memory filled with inconsistent data.
 ///
 /// *NOTE:* Not writing to the shared memory when the supervisor-mode software is not runnable
@@ -25,11 +25,11 @@ use sbi_spec::{
 ///
 /// | Name      | Offset | Size | Description
 /// |:----------|:-------|:-----|:------------
-/// | sequence  | 0      | 4    | The SBI implementation MUST increment this field to an odd value before writing the `steal` field, and increment it again to an even value after writing `steal` (i.e. an odd sequence number indicates an in-progress update). The SBI implementation SHOULD ensure that the sequence field remains odd for only very short periods of time. <br><br> The supervisor-mode software MUST check this field before and after reading the `steal` field, and repeat the read if it is different or odd. <br><br> This sequence field enables the value of the steal field to be read by supervisor-mode software executing in a 32-bit environment.
-/// | flags     | 4      | 4    | Always zero. <br><br> Future extensions of the SBI call might allow the supervisor-mode software to write to some of the fields of the shared memory. Such extensions will not be enabled as long as a zero value is used for the flags argument to the SBI call.
-/// | steal     | 8      | 8    | The amount of time in which this virtual hart was not idle and scheduled out, in nanoseconds. The time during which the virtual hart is idle will not be reported as steal-time.
-/// | preempted | 16     | 1    | An advisory flag indicating whether the virtual hart which registered this structure is running or not. A non-zero value MAY be written by the SBI implementation if the virtual hart has been preempted (i.e. while the `steal` field is increasing), while a zero value MUST be written before the virtual hart starts to run again. <br><br> This preempted field can, for example, be used by the supervisor-mode software to check if a lock holder has been preempted, and, in that case, disable optimistic spinning.
-/// | pad       | 17     | 47   | Pad with zeros to a 64 byte boundary.
+/// | `sequence`  | 0      | 4    | The SBI implementation MUST increment this field to an odd value before writing the `steal` field, and increment it again to an even value after writing `steal` (i.e. an odd sequence number indicates an in-progress update). The SBI implementation SHOULD ensure that the sequence field remains odd for only very short periods of time. <br><br> The supervisor-mode software MUST check this field before and after reading the `steal` field, and repeat the read if it is different or odd. <br><br> This sequence field enables the value of the steal field to be read by supervisor-mode software executed in a 32-bit environment.
+/// | `flags`     | 4      | 4    | Always zero. <br><br> Future extensions of the SBI call might allow the supervisor-mode software to write to some fields of the shared memory. Such extensions will not be enabled as long as a zero value is used for the flags argument to the SBI call.
+/// | `steal`     | 8      | 8    | The amount of time in which this virtual hart was not idle and scheduled out, in nanoseconds. The time during which the virtual hart is idle will not be reported as steal-time.
+/// | `preempted` | 16     | 1    | An advisory flag indicating whether the virtual hart which registered this structure is running or not. A non-zero value MAY be written by the SBI implementation if the virtual hart has been preempted (i.e., while the `steal` field is increasing), while a zero value MUST be written before the virtual hart starts to run again. <br><br> This preempted field can, for example, be used by the supervisor-mode software to check if a lock holder has been preempted, and, in that case, disable optimistic spinning.
+/// | `pad`       | 17     | 47   | Pad with zeros to a 64-byte boundary.
 ///
 /// # Parameters
 ///
@@ -45,13 +45,13 @@ use sbi_spec::{
 ///
 /// # Return value
 ///
-/// `SbiRet.value` is set to zero and the possible error codes returned in `SbiRet.error` are shown in the table below:
+/// `SbiRet.value` is set to zero, and the possible error codes returned in `SbiRet.error` are shown in the table below:
 ///
 /// | Error code                  | Description
 /// |:----------------------------|:---------------------------------
 /// | `SbiRet::success()`         | The steal-time shared memory physical base address was set or cleared successfully.
 /// | `SbiRet::invalid_param()`   | The `flags` parameter is not zero or the shmem_phys_lo is not 64-byte aligned.
-/// | `SbiRet::invalid_address()` | The shared memory pointed to by the `shmem_phys_lo` and `shmem_phys_hi` parameters is not writable or does not satisfy other requirements of STA Shared Memory Structure.
+/// | `SbiRet::invalid_address()` | The shared memory pointed to by the `shmem` parameter is not writable or does not satisfy other requirements of STA Shared Memory Structure.
 /// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 16.1.

sbi-rt/src/susp.rs

@@ -18,7 +18,7 @@ use sbi_spec::susp::{EID_SUSP, SUSPEND};
 /// The `resume_addr` parameter points to a runtime-specified physical address,
 /// where the hart can resume execution in supervisor-mode after a system suspend.
 ///
-/// 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 execution at `resume_addr` after a system
 /// suspend.
 ///
@@ -29,7 +29,7 @@ use sbi_spec::susp::{EID_SUSP, SUSPEND};
 ///
 /// | Return code               | Description
 /// |:--------------------------|:----------------------------------------------
-/// | `SbiRet::success()`       | The suspend request is accepted and the system is suspended. The system will resume execution at `resume_addr` after the sleep period.
+/// | `SbiRet::success()`       | The suspend request is accepted, and the system is suspended. The system will resume execution at `resume_addr` after the sleep period.
 /// | `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.

sbi-rt/src/time.rs

@@ -4,9 +4,10 @@ use crate::SbiRet;
 
 use sbi_spec::time::{EID_TIME, SET_TIMER};
 
-/// Programs the clock for next event after an absolute time.
+/// Programs the clock for the next event after an absolute time.
 ///
-/// Parameter `stime_value` is in absolute time. This function must clear the pending timer interrupt bit as well.
+/// Parameter `stime_value` is in absolute time.
+/// This function must clear the pending timer-interrupt bit as well.
 ///
 /// If the supervisor wishes to clear the timer interrupt without scheduling the next timer event,
 /// it can either request a timer interrupt infinitely far into the future (i.e., `u64::MAX`),