fix(rustsbi): clarify error codes in documents of SBI IPI and RFENCE extensions

Ref: https://github.com/riscv-non-isa/riscv-sbi-doc/commit/8a09fb49fc6be075e57aeadf6400e9b0b1d654f7
Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

library/rustsbi/CHANGELOG.md

@@ -22,6 +22,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - susp: amend documentation on `system_suspend` function.
 - lib: replace map+unwrap_or with Option::map_or in impls
 - doc: lib: alter link to Prototyper firmware in documentation.
+- doc: lib: clarify error codes in documents of SBI IPI and RFENCE extensions
 
 ### Removed
 

library/rustsbi/src/ipi.rs

@@ -8,7 +8,13 @@ pub trait Ipi {
     ///
     /// # Return value
     ///
-    /// Should return `SbiRet::success()` if IPI was sent to all the targeted harts successfully.
+    /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
+    ///
+    /// | Return code               | Description
+    /// |:--------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`       | IPI was sent to all the targeted harts successfully.
+    /// | `SbiRet::invalid_param()` | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+    /// | `SbiRet::failed()`        | The request failed for unspecified or unknown other reasons.
     fn send_ipi(&self, hart_mask: HartMask) -> SbiRet;
     /// Function internal to macros. Do not use.
     #[doc(hidden)]

library/rustsbi/src/rfence.rs

@@ -10,7 +10,13 @@ pub trait Rfence {
     ///
     /// # Return value
     ///
-    /// Returns `SbiRet::success()` when a remote fence was sent to all the targeted harts successfully.
+    /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
+    ///
+    /// | Return code               | Description
+    /// |:--------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`       | A remote fence was sent to all the targeted harts successfully.
+    /// | `SbiRet::invalid_param()` | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+    /// | `SbiRet::failed()`        | The request failed for unspecified or unknown other reasons.
     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`.
@@ -23,6 +29,8 @@ pub trait Rfence {
     /// |:----------------------------|:----------------------------------------------
     /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
     /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
+    /// | `SbiRet::invalid_param()`   | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+    /// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
     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`.
@@ -36,6 +44,8 @@ pub trait Rfence {
     /// |:----------------------------|:----------------------------------------------
     /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
     /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
+    /// | `SbiRet::invalid_param()`   | Either `asid`, or at least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+    /// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
     fn remote_sfence_vma_asid(
         &self,
         hart_mask: HartMask,
@@ -58,6 +68,8 @@ pub trait Rfence {
     /// | `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::invalid_address()` | `start_addr` or `size` is not valid.
+    /// | `SbiRet::invalid_param()`   | Either `vmid`, or at least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+    /// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
     #[inline]
     fn remote_hfence_gvma_vmid(
         &self,
@@ -84,6 +96,8 @@ pub trait Rfence {
     /// | `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::invalid_address()` | `start_addr` or `size` is not valid.
+    /// | `SbiRet::invalid_param()`   | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+    /// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
     #[inline]
     fn remote_hfence_gvma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet {
         let _ = (hart_mask, start_addr, size);
@@ -105,6 +119,8 @@ pub trait Rfence {
     /// | `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::invalid_address()` | `start_addr` or `size` is not valid.
+    /// | `SbiRet::invalid_param()`   | Either `asid`, or at least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+    /// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
     #[inline]
     fn remote_hfence_vvma_asid(
         &self,
@@ -131,6 +147,8 @@ pub trait Rfence {
     /// | `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::invalid_address()` | `start_addr` or `size` is not valid.
+    /// | `SbiRet::invalid_param()`   | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+    /// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
     #[inline]
     fn remote_hfence_vvma(&self, hart_mask: HartMask, start_addr: usize, size: usize) -> SbiRet {
         let _ = (hart_mask, start_addr, size);

library/sbi-rt/CHANGELOG.md

@@ -17,6 +17,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - rt: add DBTR extension support to SBI implementation.
 - dbtr: use `TriggerMask` structure in sbi-rt DBTR functions
 - rt: add structure for SSE, FWFT, DBTR, and MPXY extensions
+- lib: clarify error codes in documents of SBI IPI and RFENCE extensions
 
 ### Modified
 

library/sbi-rt/src/rfnc.rs

@@ -14,7 +14,13 @@ use sbi_spec::{
 ///
 /// # Return value
 ///
-/// Returns `SbiRet::success()` when a remote fence was sent to all the targeted harts successfully.
+/// The possible return error codes returned in `SbiRet.error` are shown in the table below:
+///
+/// | Return code               | Description
+/// |:--------------------------|:----------------------------------------------
+/// | `SbiRet::success()`       | A remote fence was sent to all the targeted harts successfully.
+/// | `SbiRet::invalid_param()` | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+/// | `SbiRet::failed()`        | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.1.
 #[inline]
@@ -37,6 +43,8 @@ pub fn remote_fence_i(hart_mask: HartMask) -> SbiRet {
 /// |:----------------------------|:----------------------------------------------
 /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
 /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
+/// | `SbiRet::invalid_param()`   | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+/// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.2.
 #[inline]
@@ -67,6 +75,8 @@ pub fn remote_sfence_vma(hart_mask: HartMask, start_addr: usize, size: usize) ->
 /// |:----------------------------|:----------------------------------------------
 /// | `SbiRet::success()`         | A remote fence was sent to all the targeted harts successfully.
 /// | `SbiRet::invalid_address()` | `start_addr` or `size` is not valid.
+/// | `SbiRet::invalid_param()`   | Either `asid`, or at least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+/// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.3.
 #[inline]
@@ -106,6 +116,8 @@ pub fn remote_sfence_vma_asid(
 /// | `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.
+/// | `SbiRet::invalid_param()`   | Either `vmid`, or at least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+/// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.4.
 #[inline]
@@ -145,6 +157,8 @@ pub fn remote_hfence_gvma_vmid(
 /// | `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.
+/// | `SbiRet::invalid_param()`   | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+/// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.5.
 #[inline]
@@ -179,6 +193,8 @@ pub fn remote_hfence_gvma(hart_mask: HartMask, start_addr: usize, size: usize) -
 /// | `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.
+/// | `SbiRet::invalid_param()`   | Either `asid`, or at least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+/// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.6.
 #[inline]
@@ -218,6 +234,8 @@ pub fn remote_hfence_vvma_asid(
 /// | `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.
+/// | `SbiRet::invalid_param()`   | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+/// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 8.7.
 #[inline]

library/sbi-rt/src/spi.rs

@@ -13,7 +13,13 @@ use sbi_spec::{
 ///
 /// # Return value
 ///
-/// Should return `SbiRet::success()` if IPI was sent to all the targeted harts successfully.
+/// The possible return error codes returned in `SbiRet.error` are shown in the table below:
+///
+/// | Return code               | Description
+/// |:--------------------------|:----------------------------------------------
+/// | `SbiRet::success()`       | IPI was sent to all the targeted harts successfully.
+/// | `SbiRet::invalid_param()` | At least one hartid constructed from `hart_mask`, is not valid, i.e. either the hartid is not enabled by the platform or is not available to the supervisor.
+/// | `SbiRet::failed()`        | The request failed for unspecified or unknown other reasons.
 ///
 /// This function is defined in RISC-V SBI Specification chapter 7.1.
 #[inline]