doc: amend using SBI 2.0-rc1 specification

improve document layout on mobile browsers

CHANGELOG.md

@@ -17,6 +17,8 @@ Bump RISC-V SBI specification version to 2.0-rc1.
 
 ### Modified
 
+- doc: amend using SBI 2.0-rc1 specification
+
 ### Removed
 
 ## [0.3.1] - 2023-01-20

src/console.rs

@@ -76,7 +76,7 @@ pub trait Console {
     /// `SbiRet::failed()`, if there are I/O errors.
     /// # Return value
     ///
-    /// The `SbiRet.value` is set to zero and` 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/hsm.rs

@@ -11,19 +11,19 @@ use sbi_spec::binary::SbiRet;
 ///
 /// | State ID | State Name | Description
 /// |:---------|:-----------|:------------
-/// | 0 | STARTED | The hart is physically powered-up and executing normally.
-/// | 1 | STOPPED | The hart is not executing in supervisor-mode or any lower privilege mode. It is probably powered-down by the SBI implementation if the underlying platform has a mechanism to physically power-down harts.
-/// | 2 | START_PENDING | Some other hart has requested to start (or power-up) the hart from the **STOPPED** state and the SBI implementation is still working to get the hart in the **STARTED** state.
-/// | 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.
-/// | 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.
+/// | 0 | `STARTED` | The hart is physically powered-up and executing normally.
+/// | 1 | `STOPPED` | The hart is not executing in supervisor-mode or any lower privilege mode. It is probably powered-down by the SBI implementation if the underlying platform has a mechanism to physically power-down harts.
+/// | 2 | `START_PENDING` | Some other hart has requested to start (or power-up) the hart from the **STOPPED** state and the SBI implementation is still working to get the hart in the **STARTED** state.
+/// | 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.
+/// | 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 a 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:
@@ -45,7 +45,7 @@ use sbi_spec::binary::SbiRet;
 pub trait Hsm: Send + Sync {
     /// Request the SBI implementation to start executing the given hart at specified address in supervisor-mode.
     ///
-    /// This call is asynchronous - more specifically, the `sbi_hart_start()` may return before target hart
+    /// 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.
     ///
     /// It is recommended that if the SBI implementation is a platform runtime firmware executing in machine-mode (M-mode)
@@ -57,6 +57,10 @@ pub trait Hsm: Send + Sync {
     /// - 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`.
     ///
+    /// *NOTE:* A single `usize` parameter is sufficient as `start_addr`,
+    /// because the hart will start execution in the supervisor-mode with MMU off,
+    /// hence the `start_addr` must be less than XLEN bits wide.
+    ///
     /// # Behavior
     ///
     /// The target hart jumps to supervisor mode at address specified by `start_addr` with following values in specific registers.
@@ -75,16 +79,16 @@ pub trait Hsm: Send + Sync {
     /// | 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 following reasons: 1. It is not a valid physical address. 2. The address is prohibited by PMP to run in supervisor mode.
+    /// | `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::already_available()` | The given hartid is already started.
     /// | `SbiRet::failed()`            | The start request failed for unknown reasons.
     fn hart_start(&self, hartid: usize, start_addr: usize, opaque: usize) -> SbiRet;
     /// Request the SBI implementation to stop executing the calling hart in supervisor-mode
-    /// and return it’s ownership to the SBI implementation.
+    /// and return its ownership to the SBI implementation.
     ///
     /// This call is not expected to return under normal conditions.
-    /// The `sbi_hart_stop()` must be called with the supervisor-mode interrupts disabled.
+    /// The `hart_stop()` must be called with supervisor-mode interrupts disabled.
     ///
     /// # Return value
     ///
@@ -96,8 +100,8 @@ pub trait Hsm: Send + Sync {
     fn hart_stop(&self) -> SbiRet;
     /// Get the current status (or HSM state id) of the given hart.
     ///
-    /// The harts may transition HSM states at any time due to any concurrent `sbi_hart_start()`
-    /// or `sbi_hart_stop()` calls, the return value from this function may not represent the actual state
+    /// The harts may transition HSM states at any time due to any concurrent `hart_start()`
+    /// or `hart_stop()` calls, the return value from this function may not represent the actual state
     /// of the hart at the time of return value verification.
     ///
     /// # Parameters
@@ -169,7 +173,11 @@ pub trait Hsm: Send + Sync {
     /// where the hart can resume execution in supervisor-mode after a non-retentive
     /// suspend.
     ///
-    /// The `opaque` parameter is a XLEN-bit value which will be set in the `a1`
+    /// *NOTE:* A single `usize` parameter is sufficient as `resume_addr`,
+    /// 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
     /// non-retentive suspend.
     ///
@@ -182,7 +190,7 @@ pub trait Hsm: Send + Sync {
     /// | `SbiRet::success()`         | Hart has 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 following reasons: it is not a valid physical address, or the address is prohibited by PMP to run in supervisor mode.
+    /// | `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.
     /// | `SbiRet::failed()`          | The suspend request failed for unknown reasons.
     fn hart_suspend(&self, suspend_type: u32, resume_addr: usize, opaque: usize) -> SbiRet {
         let _ = (suspend_type, resume_addr, opaque);

src/pmu.rs

@@ -32,8 +32,8 @@ use sbi_spec::binary::SbiRet;
 /// The event_idx is a 20 bits wide number encoded as follows:
 ///
 /// ```text
-///    event_idx[19:16] = type;
-///    event_idx[15:0] = code;
+/// event_idx[19:16] = type;
+/// event_idx[15:0] = code;
 /// ```
 pub trait Pmu: Send + Sync {
     /// Returns the number of counters (both hardware and firmware).
@@ -46,10 +46,10 @@ pub trait Pmu: Send + Sync {
     /// The `counter_info` returned by this SBI call is encoded as follows:
     ///
     /// ```text
-    ///     counter_info[11:0] = CSR; // (12bit CSR number)
-    ///     counter_info[17:12] = Width; // (One less than number of bits in CSR)
-    ///     counter_info[XLEN-2:18] = Reserved; // Reserved for future use
-    ///     counter_info[XLEN-1] = Type; // (0 = hardware and 1 = firmware)
+    /// counter_info[11:0] = CSR; // (12bit CSR number)
+    /// counter_info[17:12] = Width; // (One less than number of bits in CSR)
+    /// counter_info[XLEN-2:18] = Reserved; // Reserved for future use
+    /// counter_info[XLEN-1] = Type; // (0 = hardware and 1 = firmware)
     /// ```
     /// If `counter_info.type` == `1` then `counter_info.csr` and `counter_info.width` should be ignored.
     ///
@@ -70,23 +70,23 @@ pub trait Pmu: Send + Sync {
     /// # Parameters
     ///
     /// The `counter_idx_base` and `counter_idx_mask` parameters represent the set of counters,
-    /// whereas the `event_idx` represent the event to be monitored
+    /// whereas the `event_idx` represents 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 counter configuration and filter flags.
     /// The bit definitions of the `config_flags` parameter are shown in the table below:
     ///
-    /// | Flag Name                    | Bits       | Description
-    /// |:-----------------------------|:-----------|:------------
-    /// | SBI_PMU_CFG_FLAG_SKIP_MATCH  | 0:0        | Skip the counter matching
-    /// | SBI_PMU_CFG_FLAG_CLEAR_VALUE | 1:1        | Clear (or zero) the counter value in counter configuration
-    /// | SBI_PMU_CFG_FLAG_AUTO_START  | 2:2        | Start the counter after configuring a matching counter
-    /// | SBI_PMU_CFG_FLAG_SET_VUINH   | 3:3        | Event counting inhibited in VU-mode
-    /// | SBI_PMU_CFG_FLAG_SET_VSINH   | 4:4        | Event counting inhibited in VS-mode
-    /// | SBI_PMU_CFG_FLAG_SET_UINH    | 5:5        | Event counting inhibited in U-mode
-    /// | SBI_PMU_CFG_FLAG_SET_SINH    | 6:6        | Event counting inhibited in S-mode
-    /// | SBI_PMU_CFG_FLAG_SET_MINH    | 7:7        | Event counting inhibited in M-mode
-    /// | _RESERVED_                   | 8:(XLEN-1) | _All non-zero values are reserved for future use._
+    /// | Flag Name                      | Bits         | Description
+    /// |:-------------------------------|:-------------|:------------
+    /// | `SBI_PMU_CFG_FLAG_SKIP_MATCH`  | `0:0`        | Skip the counter matching
+    /// | `SBI_PMU_CFG_FLAG_CLEAR_VALUE` | `1:1`        | Clear (or zero) the counter value in counter configuration
+    /// | `SBI_PMU_CFG_FLAG_AUTO_START`  | `2:2`        | Start the counter after configuring a matching counter
+    /// | `SBI_PMU_CFG_FLAG_SET_VUINH`   | `3:3`        | Event counting inhibited in VU-mode
+    /// | `SBI_PMU_CFG_FLAG_SET_VSINH`   | `4:4`        | Event counting inhibited in VS-mode
+    /// | `SBI_PMU_CFG_FLAG_SET_UINH`    | `5:5`        | Event counting inhibited in U-mode
+    /// | `SBI_PMU_CFG_FLAG_SET_SINH`    | `6:6`        | Event counting inhibited in S-mode
+    /// | `SBI_PMU_CFG_FLAG_SET_MINH`    | `7:7`        | Event counting inhibited in M-mode
+    /// | _RESERVED_                     | `8:(XLEN-1)` | _All non-zero values are reserved for future use._
     ///
     /// *NOTE:* When *SBI_PMU_CFG_FLAG_SKIP_MATCH* is set in `config_flags`, the
     /// SBI implementation will unconditionally select the first counter from the
@@ -108,8 +108,8 @@ pub trait Pmu: Send + Sync {
     /// | Return code               | Description
     /// |:--------------------------|:----------------------------------------------
     /// | `SbiRet::success()`       | counter found and configured successfully.
-    /// | `SbiRet::invalid_param()` | set of counters has an invalid counter.
-    /// | `SbiRet::not_supported()` | none of the counters can monitor specified event.
+    /// | `SbiRet::invalid_param()` | 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,
         counter_idx_base: usize,
@@ -127,10 +127,10 @@ pub trait Pmu: Send + Sync {
     ///
     /// The bit definitions of the `start_flags` parameter are shown in the table below:
     ///
-    /// | Flag Name                    | Bits       | Description
-    /// |:-----------------------------|:-----------|:------------
-    /// | 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._
+    /// | Flag Name                      | Bits         | Description
+    /// |:-------------------------------|:-------------|:------------
+    /// | `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.
@@ -142,8 +142,8 @@ pub trait Pmu: Send + Sync {
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
     /// | `SbiRet::success()`         | counter started successfully.
-    /// | `SbiRet::invalid_param()`   | some of the counters specified in parameters are invalid.
-    /// | `SbiRet::already_started()` | some of the counters specified in parameters are already started.
+    /// | `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.
     fn counter_start(
         &self,
         counter_idx_base: usize,
@@ -158,10 +158,10 @@ pub trait Pmu: Send + Sync {
     /// The `counter_idx_base` and `counter_idx_mask` parameters represent the set of counters.
     /// The bit definitions of the `stop_flags` parameter are shown in the table below:
     ///
-    /// | Flag Name               | Bits       | Description
-    /// |:------------------------|:-----------|:------------
-    /// | SBI_PMU_STOP_FLAG_RESET | 0:0        | Reset the counter to event mapping.
-    /// | _RESERVED_              | 1:(XLEN-1) | *All non-zero values are reserved for future use.*
+    /// | Flag Name                 | Bits         | Description
+    /// |:--------------------------|:-------------|:------------
+    /// | `SBI_PMU_STOP_FLAG_RESET` | `0:0`        | Reset the counter to event mapping.
+    /// | _RESERVED_                | `1:(XLEN-1)` | *All non-zero values are reserved for future use.*
     ///
     /// # Return value
     ///
@@ -170,8 +170,8 @@ pub trait Pmu: Send + Sync {
     /// | Return code                 | Description
     /// |:----------------------------|:----------------------------------------------
     /// | `SbiRet::success()`         | counter stopped successfully.
-    /// | `SbiRet::invalid_param()`   | some of the counters specified in parameters are invalid.
-    /// | `SbiRet::already_stopped()` | some of the counters specified in parameters are already stopped.
+    /// | `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.
     fn counter_stop(
         &self,
         counter_idx_base: usize,