lib: amend documentation on `SbiRet::failed` error

- rustsbi: susp: amend documentation on `system_suspend` function.
- spec: binary: amend documentation on `SbiRet::denied()` error.

Signed-off-by: Zhouqi Jiang <luojia@hust.edu.cn>

CHANGELOG.md

@@ -13,6 +13,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Modified
 
+- susp: amend documentation on `system_suspend` function.
+
 ### Removed
 
 ## [0.4.0]

sbi-spec/CHANGELOG.md

@@ -14,6 +14,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ### Modified
 
+- binary: amend documentation on `SbiRet::denied()` error.
+
 ### Fixed
 
 ## [0.0.7] - 2024-02-05

sbi-spec/src/binary.rs

@@ -29,7 +29,7 @@ pub const RET_ERR_FAILED: usize = -1isize as _;
 pub const RET_ERR_NOT_SUPPORTED: usize = -2isize as _;
 /// Error for invalid parameter.
 pub const RET_ERR_INVALID_PARAM: usize = -3isize as _;
-/// Error for denied (unused in standard extensions).
+/// Error for denied.
 pub const RET_ERR_DENIED: usize = -4isize as _;
 /// Error for invalid address.
 pub const RET_ERR_INVALID_ADDRESS: usize = -5isize as _;
@@ -69,7 +69,7 @@ pub enum Error {
     NotSupported,
     /// Error for invalid parameter.
     InvalidParam,
-    /// Error for denied (unused in standard extensions).
+    /// Error for denied.
     Denied,
     /// Error for invalid address.
     InvalidAddress,
@@ -126,12 +126,8 @@ impl SbiRet {
             value: 0,
         }
     }
-    /// SBI call denied.
-    ///
-    /// As the time this document was written,
-    /// there is currently no function in SBI standard that returns this error.
-    /// However, custom extensions or future standard functions may return this
-    /// error if appropriate.
+    /// SBI call denied for unsatisfied entry criteria, or insufficient access
+    /// permission to debug console or CPPC register.
     #[inline]
     pub const fn denied() -> Self {
         Self {

src/susp.rs

@@ -76,9 +76,9 @@ pub trait Susp {
     /// | --------------------------- | -------------------
     /// | `SbiRet::success()`         | System has been suspended and resumed successfully.
     /// | `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::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 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::denied()` | The suspend request failed due to unsatisfied entry criteria.
     /// | `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.