Merge pull request rustsbi#73 from 00xc/docs

Minor documentation fixes

sbi-rt/src/hsm.rs

@@ -20,9 +20,9 @@ use sbi_spec::{
 ///
 /// - 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.
+///   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`.
+///   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,

src/hsm.rs

@@ -29,17 +29,17 @@ use sbi_spec::binary::SbiRet;
 /// 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-management software
-///   will request deepest suspend state for the hart and higher topology groups.
-///   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
+///    will request deepest suspend state for the hart and higher topology groups.
+///    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-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
+///    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 {

src/lib.rs

@@ -569,7 +569,7 @@ const SBI_SPEC_MINOR: usize = 0;
 
 /// RustSBI implementation ID: 4.
 ///
-/// Ref: https://github.com/riscv-non-isa/riscv-sbi-doc/pull/61
+/// Ref: <https://github.com/riscv-non-isa/riscv-sbi-doc/pull/61>
 const IMPL_ID_RUSTSBI: usize = 4;
 
 const RUSTSBI_VERSION_MAJOR: usize = (env!("CARGO_PKG_VERSION_MAJOR").as_bytes()[0] - b'0') as _;

src/susp.rs

@@ -78,11 +78,8 @@ pub trait Susp {
     /// | `SbiRet::invalid_param()`   | `sleep_type` is reserved or is platform-specific and unimplemented.
     /// | `SbiRet::not_supported()`   | `sleep_type` is not reserved and is implemented,
     /// but the platform does not support it due to one or more missing dependencies.
-    /// | `SbiRet::invalid_address()` | `resume_addr` is not valid, possibly due to the following reasons:
-    /// * It is not a valid physical address.
-    /// * Executable access to the address is prohibited by a physical memory protection mechanism or H-extension G-stage for supervisor mode.
-    /// | `SbiRet::failed()`
-    /// | The suspend request failed for unspecified or unknown other reasons.
+    /// | `SbiRet::invalid_address()` | `resume_addr` is not valid, possibly because it is not a valid physical address, or because executable access is prohibited (e.g. by physical memory protection or H-extension G-stage for supervisor mode).
+    /// | `SbiRet::failed()` | The suspend request failed for unspecified or unknown other reasons.
     fn system_suspend(&self, sleep_type: u32, resume_addr: usize, opaque: usize) -> SbiRet;
     /// Function internal to macros. Do not use.
     #[doc(hidden)]