doc: minor document fixes on rustsbi traits

CHANGELOG.md

@@ -85,7 +85,7 @@ module on SBI v0.3 format. Users are encouraged to use 0.2.1 and newer version i
 - Dump all trap frame registers when exception happened in reference implementations
 - Use `embedded-hal` dependency version `0.2.6`
 - Change to asynchronous lock structure trait style
-- Function `num_counters` returns `usize` and its SBI call must return `SBI_SUCCESS`
+- Function `num_counters` returns `usize` and its SBI call must return ``SbiRet::success()``
 - Use amo mutex for legacy stdio handler; remove dependency on `lazy_static` and `spin`
 - Improve documents to adapt to v1.0-rc2 specification
 

src/hsm.rs

@@ -72,13 +72,13 @@ pub trait Hsm: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code               | Description
-    /// |:--------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS               | Hart was previously in stopped state. It will start executing from `start_addr`.
-    /// | SBI_ERR_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.
-    /// | SBI_ERR_INVALID_PARAM     | `hartid` is not a valid hartid as corresponding hart cannot started in supervisor mode.
-    /// | SBI_ERR_ALREADY_AVAILABLE | The given hartid is already started.
-    /// | SBI_ERR_FAILED            | The start request failed for unknown reasons.
+    /// | 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_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.
@@ -90,9 +90,9 @@ pub trait Hsm: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Error code  | Description
-    /// |:------------|:------------
-    /// | SBI_ERR_FAILED | Failed to stop execution of the current hart
+    /// | Error code         | Description
+    /// |:-------------------|:------------
+    /// | `SbiRet::failed()` | Failed to stop execution of the current hart
     fn hart_stop(&self) -> SbiRet;
     /// Get the current status (or HSM state id) of the given hart.
     ///
@@ -117,9 +117,9 @@ pub trait Hsm: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Error code  | Description
-    /// |:------------|:------------
-    /// | SBI_ERR_INVALID_PARAM | The given `hartid` is not valid
+    /// | Error code                | Description
+    /// |:--------------------------|:------------
+    /// | `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.
@@ -177,13 +177,13 @@ pub trait Hsm: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Error code              | Description
-    /// |:------------------------|:------------
-    /// | SBI_SUCCESS             | Hart has suspended and resumed back successfully from a retentive suspend state.
-    /// | SBI_ERR_INVALID_PARAM   | `suspend_type` is not valid.
-    /// | SBI_ERR_NOT_SUPPORTED   | `suspend_type` is valid but not implemented.
-    /// | SBI_ERR_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.
-    /// | SBI_ERR_FAILED          | The suspend request failed for unknown reasons.
+    /// | Error code                  | Description
+    /// |:----------------------------|:------------
+    /// | `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::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);
         SbiRet::not_supported()

src/ipi.rs

@@ -9,7 +9,7 @@ pub trait Ipi: Send + Sync {
     ///
     /// # Return value
     ///
-    /// Should return error code `SBI_SUCCESS` if IPI was sent to all the targeted harts successfully.
+    /// Should return `SbiRet::success()` if IPI was sent to all the targeted harts successfully.
     fn send_ipi(&self, hart_mask: HartMask) -> SbiRet;
 }
 

src/pmu.rs

@@ -38,7 +38,7 @@ use sbi_spec::binary::SbiRet;
 pub trait Pmu: Send + Sync {
     /// Returns the number of counters (both hardware and firmware).
     ///
-    /// The value is returned in `SbiRet.value`; this call always returns SBI_SUCCESS in `SbiRet.error`.
+    /// The value is returned in `SbiRet.value`; this call always returns `SbiRet::success()`.
     fn num_counters(&self) -> usize;
     /// Get details about the specified counter such as underlying CSR number, width of the counter,
     /// type of counter hardware/firmware, etc.
@@ -59,10 +59,10 @@ pub trait Pmu: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code             | Description
-    /// |:------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS             | `counter_info` read successfully.
-    /// | SBI_ERR_INVALID_PARAM   | `counter_idx` points to an invalid counter.
+    /// | Return code                 | Description
+    /// |:----------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`         | `counter_info` read successfully.
+    /// | `SbiRet::invalid_param()`   | `counter_idx` points to an invalid counter.
     fn counter_get_info(&self, counter_idx: usize) -> SbiRet;
     /// Find and configure a counter from a set of counters which is not started (or enabled)
     /// and can monitor the specified event.
@@ -105,11 +105,11 @@ pub trait Pmu: Send + Sync {
     ///
     /// In case of failure, the possible error codes returned in `sbiret.error` are shown in the table below:
     ///
-    /// | Return code           | Description
-    /// |:----------------------|:----------------------------------------------
-    /// | SBI_SUCCESS           | counter found and configured successfully.
-    /// | SBI_ERR_INVALID_PARAM | set of counters has an invalid counter.
-    /// | SBI_ERR_NOT_SUPPORTED | none of the counters can monitor specified event.
+    /// | 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.
     fn counter_config_matching(
         &self,
         counter_idx_base: usize,
@@ -139,11 +139,11 @@ pub trait Pmu: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code             | Description
-    /// |:------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS             | counter started successfully.
-    /// | SBI_ERR_INVALID_PARAM   | some of the counters specified in parameters are invalid.
-    /// | SBI_ERR_ALREADY_STARTED | some of the counters specified in parameters are already started.
+    /// | 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.
     fn counter_start(
         &self,
         counter_idx_base: usize,
@@ -167,11 +167,11 @@ pub trait Pmu: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code             | Description
-    /// |:------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS             | counter stopped successfully.
-    /// | SBI_ERR_INVALID_PARAM   | some of the counters specified in parameters are invalid.
-    /// | SBI_ERR_ALREADY_STOPPED | some of the counters specified in parameters are already stopped.
+    /// | 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.
     fn counter_stop(
         &self,
         counter_idx_base: usize,
@@ -189,10 +189,10 @@ pub trait Pmu: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code             | Description
-    /// |:------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS             | firmware counter read successfully.
-    /// | SBI_ERR_INVALID_PARAM   | `counter_idx` points to a hardware counter or an invalid counter.
+    /// | Return code               | Description
+    /// |:--------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`       | firmware counter read successfully.
+    /// | `SbiRet::invalid_param()` | `counter_idx` points to a hardware counter or an invalid counter.
     fn counter_fw_read(&self, counter_idx: usize) -> SbiRet;
 }
 
@@ -216,7 +216,7 @@ pub(crate) fn probe_pmu() -> bool {
 pub(crate) fn num_counters() -> SbiRet {
     if let Some(obj) = PMU.get() {
         // Returns the number of counters (both hardware and firmware) in sbiret.value
-        // and always returns SBI_SUCCESS in sbiret.error.
+        // and always returns `SbiRet::success()`.
         return SbiRet::success(obj.num_counters());
     }
     SbiRet::not_supported()

src/reset.rs

@@ -31,11 +31,11 @@ pub trait Reset: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Error code            | Description
-    /// |:----------------------|:---------------
-    /// | SBI_ERR_INVALID_PARAM | `reset_type` or `reset_reason` is not valid.
-    /// | SBI_ERR_NOT_SUPPORTED | `reset_type` is valid but not implemented.
-    /// | SBI_ERR_FAILED        | Reset request failed for unknown reasons.
+    /// | Error code                | Description
+    /// |:--------------------------|:---------------
+    /// | `SbiRet::invalid_param()` | `reset_type` or `reset_reason` is not valid.
+    /// | `SbiRet::not_supported()` | `reset_type` is valid but not implemented.
+    /// | `SbiRet::failed()`        | Reset request failed for unknown reasons.
     fn system_reset(&self, reset_type: u32, reset_reason: u32) -> SbiRet;
 
     /// Legacy extension's reset function

src/rfence.rs

@@ -11,7 +11,7 @@ pub trait Rfence: Send + Sync {
     ///
     /// # Return value
     ///
-    /// Returns `SBI_SUCCESS` when remote fence was sent to all the targeted harts successfully.
+    /// Returns `SbiRet::success()` when remote fence was sent to all the targeted harts successfully.
     fn remote_fence_i(&self, hart_mask: HartMask) -> SbiRet;
     /// Instructs the remote harts to execute one or more `SFENCE.VMA` instructions,
     /// covering the range of virtual addresses between `start_addr` and `size`.
@@ -20,10 +20,10 @@ pub trait Rfence: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code               | Description
-    /// |:--------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS               | Remote fence was sent to all the targeted harts successfully.
-    /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
+    /// | Return code                 | Description
+    /// |:----------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     fn remote_sfence_vma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet;
     /// Instruct the remote harts to execute one or more `SFENCE.VMA` instructions,
     /// covering the range of virtual addresses between `start_addr` and `size`.
@@ -33,10 +33,10 @@ pub trait Rfence: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code               | Description
-    /// |:--------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS               | Remote fence was sent to all the targeted harts successfully.
-    /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
+    /// | Return code                 | Description
+    /// |:----------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     fn remote_sfence_vma_asid(
         &self,
         hart_mask: HartMask,
@@ -54,11 +54,11 @@ pub trait Rfence: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code               | Description
-    /// |:--------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS               | Remote fence was sent to all the targeted harts successfully.
-    /// | SBI_ERR_NOT_SUPPORTED     | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
-    /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
+    /// | Return code                 | Description
+    /// |:----------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
+    /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     fn remote_hfence_gvma_vmid(
         &self,
         hart_mask: HartMask,
@@ -79,11 +79,11 @@ pub trait Rfence: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code               | Description
-    /// |:--------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS               | Remote fence was sent to all the targeted harts successfully.
-    /// | SBI_ERR_NOT_SUPPORTED     | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
-    /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
+    /// | Return code                 | Description
+    /// |:----------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
+    /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     fn remote_hfence_gvma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet {
         let _ = (hart_mask, start_addr, size);
         SbiRet::not_supported()
@@ -99,11 +99,11 @@ pub trait Rfence: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code               | Description
-    /// |:--------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS               | Remote fence was sent to all the targeted harts successfully.
-    /// | SBI_ERR_NOT_SUPPORTED     | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
-    /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
+    /// | Return code                 | Description
+    /// |:----------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target hart does not support hypervisor extension.
+    /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     fn remote_hfence_vvma_asid(
         &self,
         hart_mask: HartMask,
@@ -124,11 +124,11 @@ pub trait Rfence: Send + Sync {
     ///
     /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
     ///
-    /// | Return code               | Description
-    /// |:--------------------------|:----------------------------------------------
-    /// | SBI_SUCCESS               | Remote fence was sent to all the targeted harts successfully.
-    /// | SBI_ERR_NOT_SUPPORTED     | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
-    /// | SBI_ERR_INVALID_ADDRESS   | `start_addr` or `size` is not valid.
+    /// | Return code                 | Description
+    /// |:----------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`         | Remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::not_supported()`   | This function is not supported as it is not implemented or one of the target hart doesn’t support hypervisor extension.
+    /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
     fn remote_hfence_vvma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet {
         let _ = (hart_mask, start_addr, size);
         SbiRet::not_supported()