Merge remote-tracking branch 'refs/remotes/origin/main'

.github/workflows/Changelog.yml

@@ -0,0 +1,50 @@
+name: Changelog
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+env:
+  CARGO_UNSTABLE_SPARSE_REGISTRY: true
+  CARGO_TERM_COLOR: always
+
+jobs:
+  check-changelog:
+    name: Check if CHANGELOG.md is updated
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Get latest updated files
+        run: |
+          updated_files=$(git show --name-only --pretty=format: HEAD)
+      - name: Check if changlog is updated
+        run: |
+          if git show --name-only --pretty=format: HEAD | grep -q "CHANGELOG.md"; then
+            echo "Main CHANGELOG.md changed in the latest commit."
+          else
+            echo "Main CHANGELOG.md is not changed in the latest commit."
+            exit 1
+          fi
+          for file in $updated_files; do
+            first_path=$(dirname "$file")
+            if [[ "$first_path" == *"sbi-rt"* ]]; then
+              file_path = "./sbi-rt"
+            elif [[ "$first_path" == *"sbi-spec"* ]]; then
+              file_path = "./sbi-spec"
+            elif [[ "$first_path" == *"sbi-testing"* ]]; then
+              file_path = "./sbi-testing"
+            else
+              file_path = "./"
+            fi
+            changelog_path="$file_path/CHANGELOG.md"
+            # Check if changelog is updated
+            if git diff --name-only "$file_path" | grep -q "CHANGELOG.md"; then
+              echo "File $changelog_path changed in the latest commit."
+            else
+              echo "File $changelog_path is not changed in the latest commit."
+              exit 1
+            fi
+          done

.github/workflows/DCO.yml

@@ -0,0 +1,34 @@
+name: DCO
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  workflow_dispatch:
+
+env:
+  CARGO_UNSTABLE_SPARSE_REGISTRY: true
+  CARGO_TERM_COLOR: always
+
+jobs:
+  check-commit-signatures:
+    name: Check commit signatures
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check if commit is signed
+        run: |
+          COMMIT=$(git log -1)
+          if echo "$COMMIT" | grep -q "Author: "; then
+              echo "Commit is signed."
+          else
+              echo "Commit is NOT signed."
+              exit 1
+          fi
+      - name: Print author's information
+        run: |
+          AUTHOR_NAME=$(git log -1 --format='%an')
+          AUTHOR_EMAIL=$(git log -1 --format='%ae')
+          echo "Author's name: $AUTHOR_NAME"
+          echo "Author's email: $AUTHOR_EMAIL"

.github/workflows/ci.yml → .github/workflows/Rust.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Rust
 
 on:
   push:

CHANGELOG.md

@@ -9,8 +9,17 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- ci: add `check-changlog` and `check-commit-signatures` in `workflows`.
+- pmu: add missing `snapshot_set_shmem` function and testcases in `Pmu` trait.
+- pmu: add missing `snapshot_set_shmem` function in `Pmu` trait, impl for `&T` and `Option<T>` and `Forward` structure
+- forward: derive `Copy`, `Default`, `PartialEq`, `Eq` and `Hash` for struct Forward
+- pmu: mark that signatures of `pmu_counter_{config_matching, start, stop}` would be changed in RustSBI 0.5.0, as they are breaking changes.
+- lib: re-export `CounterMask` structure from `sbi-spec` crate.
+
 ### Modified
 
+- susp: amend documentation on `system_suspend` function.
+
 ### Removed
 
 ## [0.4.0]

Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "rustsbi"
 description = "Minimal RISC-V's SBI implementation library in Rust"
-version = "0.4.0-alpha.3"
+version = "0.4.0"
 authors = [
     "Luo Jia <me@luojia.cc>",
     "Campbell He <hkp18@mails.tsinghua.edu.cn>",
@@ -17,8 +17,8 @@ categories = ["os", "embedded", "hardware-support", "no-std"]
 exclude = ["/.github"]
 
 [dependencies]
-sbi-spec = { version = "0.0.7", path = "sbi-spec" }
-riscv = { version = "0.11.1", optional = true }
+sbi-spec = { version = "0.0.8", path = "sbi-spec" }
+riscv = { version = "0.12.0", optional = true, default-features = false }
 sbi-rt = { version = "0.0.3", features = ["integer-impls"], optional = true, path = "sbi-rt" }
 rustsbi-macros = { version = "0.0.2", path = "macros" }
 

sbi-rt/CHANGELOG.md

@@ -7,6 +7,18 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- pmu: add missing `pmu_snapshot_set_shmem` function.
+- pmu: `pmu_snapshot_set_shmem` function signature, documents and implementation
+- lib: re-export `sbi_spec::base::CounterMask` on crate root.
+
+### Modified
+
+- pmu: change `counter_idx_mask` and `counter_idx_base` parameters into `counter_idx` with type `CounterMask`.
+
+### Fixed
+
 ## [0.0.3] - 2024-02-08
 
 This version adds support to the RISC-V SBI Specification version 2.0 ratified.

sbi-rt/Cargo.toml

@@ -21,7 +21,7 @@ targets = [
 ]
 
 [dependencies]
-sbi-spec = { version = "0.0.7", path = "../sbi-spec" }
+sbi-spec = { version = "0.0.8", path = "../sbi-spec" }
 
 [features]
 default = []

sbi-rt/src/legacy.rs

@@ -1,8 +1,11 @@
-//! Chapter 5. Legacy Extensions (EIDs #0x00 - #0x0F)
+//! Legacy Extensions (EIDs #0x00 - #0x0F).
+//!
+//! The legacy SBI extensions is deprecated in favor of the other extensions in the RISC-V SBI Specification.
+//! Developers should use new extensions instead of the deprecated legacy extensions listed below.
 
-pub use sbi_spec::legacy::*;
+use sbi_spec::legacy::*;
 
-/// §5.1
+/// Use [`set_timer`](super::set_timer) from [`TIME`](crate::base::Timer) extension instead.
 #[deprecated = "replaced by `set_timer` from Timer extension"]
 #[inline]
 pub fn set_timer(stime_value: u64) -> usize {
@@ -14,72 +17,57 @@ pub fn set_timer(stime_value: u64) -> usize {
     }
 }
 
-/// §5.2
-///
-/// No replacement.
-#[deprecated = "no replacement"]
+/// Use [`console_write`](super::console_write) and [`console_write_byte`](super::console_write_byte)
+/// from [`DBCN`](crate::base::Console) extension instead.
+#[deprecated = "replaced by `console_write` and `console_write_byte` from `DBCN` extension"]
 #[inline]
 pub fn console_putchar(c: usize) -> usize {
     sbi_call_legacy_1(LEGACY_CONSOLE_PUTCHAR, c)
 }
 
-/// §5.3
-///
-/// No replacement.
-#[deprecated = "no replacement"]
+/// Use [`console_read`](super::console_read) from [`DBCN`](crate::base::Console) extension instead.
+#[deprecated = "replaced by `console_read` from `DBCN` extension"]
 #[inline]
 pub fn console_getchar() -> usize {
     sbi_call_legacy_0(LEGACY_CONSOLE_GETCHAR)
 }
 
-/// §5.4
-///
-/// No replacement. Just clear `sip.SSIP` directly.
+/// Clear `sip.SSIP` CSR field instead.
 #[deprecated = "you can clear `sip.SSIP` CSR bit directly"]
 #[inline]
 pub fn clear_ipi() -> usize {
     sbi_call_legacy_0(LEGACY_CLEAR_IPI)
 }
 
-/// §5.5
-///
-/// Replaced by [`send_ipi`](super::send_ipi) from [`sPI`](super::EID_SPI) extension.
+/// Use [`send_ipi`](super::send_ipi) from [`sPI`](crate::base::Ipi) extension instead.
 #[deprecated = "replaced by `send_ipi` from `sPI` extension"]
 #[inline]
 pub fn send_ipi(hart_mask: usize) -> usize {
     sbi_call_legacy_1(LEGACY_SEND_IPI, hart_mask)
 }
 
-/// §5.6
-///
-/// Replaced by [`remote_fence_i`](super::remote_fence_i) from [`RFNC`](super::EID_RFNC) extension.
+/// Use [`remote_fence_i`](super::remote_fence_i) from [`RFNC`](crate::base::Fence) extension instead.
 #[deprecated = "replaced by `remote_fence_i` from `RFNC` extension"]
 #[inline]
 pub fn remote_fence_i(hart_mask: usize) -> usize {
     sbi_call_legacy_1(LEGACY_REMOTE_FENCE_I, hart_mask)
 }
 
-/// §5.7
-///
-/// Replaced by [`remote_sfence_vma`](super::remote_sfence_vma) from [`RFNC`](super::EID_RFNC) extension.
+/// Use [`remote_sfence_vma`](super::remote_sfence_vma) from [`RFNC`](crate::base::Fence) extension instead.
 #[deprecated = "replaced by `remote_sfence_vma` from `RFNC` extension"]
 #[inline]
 pub fn remote_fence_vma(hart_mask: usize, start: usize, size: usize) -> usize {
     sbi_call_legacy_3(LEGACY_REMOTE_SFENCE_VMA, hart_mask, start, size)
 }
 
-/// §5.8
-///
-/// Replaced by [`remote_sfence_vma_asid`](super::remote_sfence_vma_asid) from [`RFNC`](super::EID_RFNC) extension.
+/// Use [`remote_sfence_vma_asid`](super::remote_sfence_vma_asid) from [`RFNC`](crate::base::Fence) extension instead.
 #[deprecated = "replaced by `remote_sfence_vma_asid` from `RFNC` extension"]
 #[inline]
 pub fn remote_fence_vma_asid(hart_mask: usize, start: usize, size: usize, asid: usize) -> usize {
     sbi_call_legacy_4(LEGACY_REMOTE_SFENCE_VMA_ASID, hart_mask, start, size, asid)
 }
 
-/// §5.9
-///
-/// Replaced by [`system_reset`](super::system_reset) in the [`SRST`](super::EID_SRST) extension.
+/// Use [`system_reset`](super::system_reset) in the [`SRST`](crate::base::Reset) extension instead.
 #[deprecated = "replaced by `system_reset` from System `SRST` extension"]
 #[inline]
 pub fn shutdown() -> ! {

sbi-rt/src/lib.rs

@@ -33,7 +33,7 @@ mod sta;
 
 pub use sbi_spec::{
     base::Version,
-    binary::{HartMask, Physical, SbiRet, SharedPtr},
+    binary::{CounterMask, HartMask, Physical, SbiRet, SharedPtr},
 };
 
 // module `binary` includes crate-local `sbi_call_*` functions and is thus not re-exported

sbi-rt/src/pmu.rs

@@ -3,10 +3,10 @@
 use crate::binary::{sbi_call_0, sbi_call_1, sbi_call_3};
 
 use sbi_spec::{
-    binary::SbiRet,
+    binary::{CounterMask, SbiRet, SharedPtr},
     pmu::{
-        COUNTER_CONFIG_MATCHING, COUNTER_FW_READ, COUNTER_FW_READ_HI, COUNTER_GET_INFO,
-        COUNTER_START, COUNTER_STOP, EID_PMU, NUM_COUNTERS,
+        shmem_size::SIZE, COUNTER_CONFIG_MATCHING, COUNTER_FW_READ, COUNTER_FW_READ_HI,
+        COUNTER_GET_INFO, COUNTER_START, COUNTER_STOP, EID_PMU, NUM_COUNTERS, SNAPSHOT_SET_SHMEM,
     },
 };
 
@@ -14,7 +14,7 @@ use sbi_spec::{
 ///
 /// This call would always succeed without returning any error.
 ///
-/// This function is defined in RISC-V SBI Specification chapter 11.5.
+/// This function is defined in RISC-V SBI Specification chapter 11.6.
 #[inline]
 pub fn pmu_num_counters() -> usize {
     sbi_call_0(EID_PMU, NUM_COUNTERS).value
@@ -35,8 +35,6 @@ pub fn pmu_num_counters() -> usize {
 /// ```
 /// If `counter_info.type` == `1` then `counter_info.csr` and `counter_info.width` should be ignored.
 ///
-/// This function is defined in RISC-V SBI Specification chapter 11.6.
-///
 /// # Return value
 ///
 /// Returns the `counter_info` described above in `SbiRet.value`.
@@ -48,7 +46,7 @@ pub fn pmu_num_counters() -> usize {
 /// | `SbiRet::success()`       | `counter_info` read successfully.
 /// | `SbiRet::invalid_param()` | `counter_idx` points to an invalid counter.
 ///
-/// This function is defined in RISC-V SBI Specification chapter 11.6.
+/// This function is defined in RISC-V SBI Specification chapter 11.7.
 #[inline]
 pub fn pmu_counter_get_info(counter_idx: usize) -> SbiRet {
     sbi_call_1(EID_PMU, COUNTER_GET_INFO, counter_idx)
@@ -61,7 +59,7 @@ pub fn pmu_counter_get_info(counter_idx: usize) -> SbiRet {
 ///
 /// # Parameters
 ///
-/// The `counter_idx_base` and `counter_idx_mask` parameters represent the set of counters,
+/// The `counter_idx` parameter represent the set of counters,
 /// whereas the `event_idx` represent the event to be monitored
 /// and `event_data` represents any additional event configuration.
 ///
@@ -82,7 +80,7 @@ pub fn pmu_counter_get_info(counter_idx: usize) -> SbiRet {
 ///
 /// *NOTE:* When *SBI_PMU_CFG_FLAG_SKIP_MATCH* is set in `config_flags`, the
 /// SBI implementation will unconditionally select the first counter from the
-/// set of counters specified by the `counter_idx_base` and `counter_idx_mask`.
+/// set of counters specified by the `counter_idx`.
 ///
 /// *NOTE:* The *SBI_PMU_CFG_FLAG_AUTO_START* flag in `config_flags` has no
 /// impact on the value of the counter.
@@ -103,11 +101,10 @@ pub fn pmu_counter_get_info(counter_idx: usize) -> SbiRet {
 /// | `SbiRet::invalid_param()` | set of counters has an invalid counter.
 /// | `SbiRet::not_supported()` | none of the counters can monitor specified event.
 ///
-/// This function is defined in RISC-V SBI Specification chapter 11.7.
+/// This function is defined in RISC-V SBI Specification chapter 11.8.
 #[inline]
 pub fn pmu_counter_config_matching<T>(
-    counter_idx_base: usize,
-    counter_idx_mask: usize,
+    counter_idx: CounterMask,
     config_flags: T,
     event_idx: usize,
     event_data: u64,
@@ -115,6 +112,7 @@ pub fn pmu_counter_config_matching<T>(
 where
     T: ConfigFlags,
 {
+    let (counter_idx_mask, counter_idx_base) = counter_idx.into_inner();
     match () {
         #[cfg(target_pointer_width = "32")]
         () => crate::binary::sbi_call_6(
@@ -144,7 +142,7 @@ where
 ///
 /// # Parameters
 ///
-/// The `counter_idx_base` and `counter_idx_mask` parameters represent the set of counters.
+/// The `counter_idx` parameter represent the set of counters.
 /// whereas the `initial_value` parameter specifies the initial value of the counter.
 ///
 /// The bit definitions of the `start_flags` parameter are shown in the table below:
@@ -167,17 +165,13 @@ where
 /// | `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.
 ///
-/// This function is defined in RISC-V SBI Specification chapter 11.8.
+/// This function is defined in RISC-V SBI Specification chapter 11.9.
 #[inline]
-pub fn pmu_counter_start<T>(
-    counter_idx_base: usize,
-    counter_idx_mask: usize,
-    start_flags: T,
-    initial_value: u64,
-) -> SbiRet
+pub fn pmu_counter_start<T>(counter_idx: CounterMask, start_flags: T, initial_value: u64) -> SbiRet
 where
     T: StartFlags,
 {
+    let (counter_idx_mask, counter_idx_base) = counter_idx.into_inner();
     match () {
         #[cfg(target_pointer_width = "32")]
         () => crate::binary::sbi_call_5(
@@ -205,7 +199,7 @@ where
 ///
 /// # Parameters
 ///
-/// The `counter_idx_base` and `counter_idx_mask` parameters represent the set of counters.
+/// The `counter_idx` parameter represents the set of counters.
 /// The bit definitions of the `stop_flags` parameter are shown in the table below:
 ///
 /// | Flag Name               | Bits       | Description
@@ -223,16 +217,13 @@ where
 /// | `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.
 ///
-/// This function is defined in RISC-V SBI Specification chapter 11.9.
+/// This function is defined in RISC-V SBI Specification chapter 11.10.
 #[inline]
-pub fn pmu_counter_stop<T>(
-    counter_idx_base: usize,
-    counter_idx_mask: usize,
-    stop_flags: T,
-) -> SbiRet
+pub fn pmu_counter_stop<T>(counter_idx: CounterMask, stop_flags: T) -> SbiRet
 where
     T: StopFlags,
 {
+    let (counter_idx_mask, counter_idx_base) = counter_idx.into_inner();
     sbi_call_3(
         EID_PMU,
         COUNTER_STOP,
@@ -261,7 +252,7 @@ where
 /// | `SbiRet::success()`       | firmware counter read successfully.
 /// | `SbiRet::invalid_param()` | `counter_idx` points to a hardware counter or an invalid counter.
 ///
-/// This function is defined in RISC-V SBI Specification chapter 11.10.
+/// This function is defined in RISC-V SBI Specification chapter 11.11.
 #[inline]
 pub fn pmu_counter_fw_read(counter_idx: usize) -> SbiRet {
     sbi_call_1(EID_PMU, COUNTER_FW_READ, counter_idx)
@@ -280,12 +271,51 @@ pub fn pmu_counter_fw_read(counter_idx: usize) -> SbiRet {
 /// | `SbiRet::success()`       | firmware counter read successfully.
 /// | `SbiRet::invalid_param()` | `counter_idx` points to a hardware counter or an invalid counter.
 ///
-/// This function is defined in RISC-V SBI Specification chapter 11.11.
+/// This function is defined in RISC-V SBI Specification chapter 11.12.
 #[inline]
 pub fn pmu_counter_fw_read_hi(counter_idx: usize) -> SbiRet {
     sbi_call_1(EID_PMU, COUNTER_FW_READ_HI, counter_idx)
 }
 
+/// Set and enable the PMU snapshot shared memory on the calling hart.
+///
+/// This function should be invoked only once per hart at boot time. Once configured, the SBI
+/// implementation has read/write access to the shared memory when `sbi_pmu_counter_stop` is
+/// invoked with the `TAKE_SNAPSHOT` flag set.
+///
+/// # Parameters
+///
+/// If `shmem` address parameter are not all-ones bitwise then
+/// `shmem` specifies the shared memory physical base address.
+/// The `shmem` physical address MUST be 4096 bytes (i.e. page) aligned
+/// and the size of the snapshot shared memory must be 4096 bytes.
+///
+/// The `flags` parameter is reserved for future use and must be zero.
+///
+/// # Return value
+///
+/// The possible return error codes returned in `SbiRet.error` are shown in the table below:
+///
+/// | Return code                 | Description
+/// |:----------------------------|:----------------------------------------------
+/// | `SbiRet::success()`         | Shared memory was set or cleared successfully.
+/// | `SbiRet::not_supported()`   | The SBI PMU snapshot functionality is not available in the SBI implementation.
+/// | `SbiRet::invalid_param()`   | The flags parameter is not zero or the `shmem` parameter is not 4096 bytes aligned.
+/// | `SbiRet::invalid_address()` | The shared memory pointed to by the `shmem` parameter is not writable or does not satisfy other requirements of RISC-V SBI Specification chapter 3.2.
+/// | `SbiRet::failed()`          | The request failed for unspecified or unknown other reasons.
+///
+/// This function is defined in RISC-V SBI Specification chapter 11.13.
+#[inline]
+pub fn pmu_snapshot_set_shmem(shmem: SharedPtr<[u8; SIZE]>, flags: usize) -> SbiRet {
+    sbi_call_3(
+        EID_PMU,
+        SNAPSHOT_SET_SHMEM,
+        shmem.phys_addr_lo(),
+        shmem.phys_addr_hi(),
+        flags,
+    )
+}
+
 /// Flags to configure performance counter.
 pub trait ConfigFlags {
     /// Get a raw value to pass to SBI environment.

sbi-spec/CHANGELOG.md

@@ -14,6 +14,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 ### Fixed
 - Add missing impl_id: Xen: 7 and PolarFire: 8 in chapter4
 
+## [0.0.8] - 2024-10-25
+
+### Added
+
+- base: add Coreboot and Oreboot to `impl_id` module
+- binary: add counter index mask type ([#71](https://github.com/rustsbi/rustsbi/pull/71))
+- pmu: add `shmem_size` module for PMU snapshot shared memory, add unit test for `pmu::shmem_size::SIZE`
+- binary: add function `is_ok_and`, `is_err_and`, `inspect` and `inspect_err` for `SbiRet` structure
+- base: impl `Eq`, `PartialEq`, `Ord`, `PartialOrd` and `Hash` for `Version`, add unit tests
+
+### Modified
+
+- binary: amend documentation on `SbiRet::denied()` error.
+- binary: change `SbiRet::and` signature to `fn and<U>(self, res: Result<U, Error>) -> Result<U, Error>`
+
+### Fixed
+
+- pmu: fix serial number issues in docs.
+
 ## [0.0.7] - 2024-02-05
 
 `sbi-spec` crate now supports RISC-V SBI version 2.0 ratified.

sbi-spec/Cargo.toml

@@ -1,7 +1,7 @@
 [package]
 name = "sbi-spec"
-description = "Definitions and constants in RISC-V Supervisor Binary Interface (RISC-V SBI)"
-version = "0.0.7"
+description = "Definitions and constants in the RISC-V Supervisor Binary Interface (RISC-V SBI)"
+version = "0.0.8"
 authors = ["YdrMaster <ydrml@hotmail.com>", "Luo Jia <me@luojia.cc>"]
 documentation = "https://docs.rs/sbi-spec"
 edition.workspace = true

sbi-spec/src/base.rs

@@ -9,10 +9,12 @@ pub const UNAVAILABLE_EXTENSION: usize = 0;
 
 /// SBI specification version.
 ///
+/// In RISC-V SBI specification, the bit 31 must be 0 and is reserved for future expansion.
+///
 /// Not to be confused with 'implementation version'.
 ///
 /// Declared in §4.1.
-#[derive(Clone, Copy, Debug)]
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Ord, Hash)]
 #[repr(transparent)]
 pub struct Version {
     raw: usize,
@@ -45,6 +47,15 @@ impl core::fmt::Display for Version {
     }
 }
 
+impl core::cmp::PartialOrd for Version {
+    #[inline]
+    fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
+        self.major()
+            .partial_cmp(&other.major())
+            .map(|ordering| ordering.then_with(|| self.minor().cmp(&other.minor())))
+    }
+}
+
 /// Declared in §4.8
 mod fid {
     /// Function ID to get the current SBI specification version.
@@ -95,8 +106,109 @@ pub mod impl_id {
     pub const DIOSIX: usize = 5;
     /// Coffer.
     pub const COFFER: usize = 6;
-    /// Xen Project
+    /// Xen Project.
     pub const XEN: usize = 7;
     /// PolarFire Hart Software Services.
     pub const POLARFIRE_HSS: usize = 8;
+    /// Coreboot.
+    pub const COREBOOT: usize = 9;
+    /// Oreboot.
+    pub const OREBOOT: usize = 10;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::Version;
+
+    #[test]
+    fn version_parse() {
+        let v1_0 = Version::from_raw(0x100_0000);
+        assert_eq!(v1_0.major(), 1);
+        assert_eq!(v1_0.minor(), 0);
+
+        let v2_0 = Version::from_raw(0x200_0000);
+        assert_eq!(v2_0.major(), 2);
+        assert_eq!(v2_0.minor(), 0);
+
+        let v2_1 = Version::from_raw(0x200_0001);
+        assert_eq!(v2_1.major(), 2);
+        assert_eq!(v2_1.minor(), 1);
+
+        let v2_max = Version::from_raw(0x2ff_ffff);
+        assert_eq!(v2_max.major(), 2);
+        assert_eq!(v2_max.minor(), 16777215);
+
+        let vmax_3 = Version::from_raw(0x7f00_0003);
+        assert_eq!(vmax_3.major(), 127);
+        assert_eq!(vmax_3.minor(), 3);
+
+        let vmax_max = Version::from_raw(0x7fff_ffff);
+        assert_eq!(vmax_max.major(), 127);
+        assert_eq!(vmax_max.minor(), 16777215);
+    }
+
+    #[test]
+    fn version_display() {
+        extern crate alloc;
+        use alloc::string::ToString;
+
+        assert_eq!("0.0", &Version::from_raw(0).to_string());
+        assert_eq!("0.1", &Version::from_raw(0x1).to_string());
+        assert_eq!("1.0", &Version::from_raw(0x100_0000).to_string());
+        assert_eq!("1.1", &Version::from_raw(0x100_0001).to_string());
+        assert_eq!("2.0", &Version::from_raw(0x200_0000).to_string());
+        assert_eq!("127.0", &Version::from_raw(0x7f00_0000).to_string());
+        assert_eq!("2.16777215", &Version::from_raw(0x2ff_ffff).to_string());
+        assert_eq!("127.16777215", &Version::from_raw(0x7fff_ffff).to_string());
+    }
+
+    #[test]
+    fn version_ordering() {
+        use core::cmp::Ordering;
+        let v0_0 = Version::from_raw(0x0);
+        let v0_3 = Version::from_raw(0x3);
+        let v1_0 = Version::from_raw(0x100_0000);
+        let v2_0 = Version::from_raw(0x200_0000);
+        let v2_1 = Version::from_raw(0x200_0001);
+        let v2_max = Version::from_raw(0x2ff_ffff);
+        let vmax_3 = Version::from_raw(0x7f00_0003);
+        let vmax_max = Version::from_raw(0x7fff_ffff);
+
+        assert!(v0_3 != v0_0);
+        assert!(!(v0_3 == v0_0));
+        assert!(v0_0 == v0_0);
+        assert!(vmax_max == vmax_max);
+
+        assert!(v0_3 > v0_0);
+        assert!(v0_3 >= v0_0);
+        assert!(v0_0 < v0_3);
+        assert!(v0_0 <= v0_3);
+        assert!(v0_0 >= v0_0);
+        assert!(v0_0 <= v0_0);
+
+        assert!(v0_3 > v0_0);
+        assert!(v1_0 > v0_3);
+        assert!(v2_0 > v1_0);
+        assert!(v2_1 > v2_0);
+        assert!(v2_max > v2_1);
+        assert!(vmax_3 > v2_max);
+        assert!(vmax_max > vmax_3);
+
+        assert_eq!(Version::partial_cmp(&v1_0, &v0_0), Some(Ordering::Greater));
+        assert_eq!(Version::partial_cmp(&v0_0, &v1_0), Some(Ordering::Less));
+        assert_eq!(Version::partial_cmp(&v0_0, &v0_0), Some(Ordering::Equal));
+
+        assert_eq!(Version::max(v0_0, v0_0), v0_0);
+        assert_eq!(Version::max(v1_0, v0_0), v1_0);
+        assert_eq!(Version::max(v0_0, v1_0), v1_0);
+        assert_eq!(Version::min(v0_0, v0_0), v0_0);
+        assert_eq!(Version::min(v1_0, v0_0), v0_0);
+        assert_eq!(Version::min(v0_0, v1_0), v0_0);
+
+        assert_eq!(v0_0.clamp(v0_3, v2_0), v0_3);
+        assert_eq!(v0_3.clamp(v0_3, v2_0), v0_3);
+        assert_eq!(v1_0.clamp(v0_3, v2_0), v1_0);
+        assert_eq!(v2_0.clamp(v0_3, v2_0), v2_0);
+        assert_eq!(v2_1.clamp(v0_3, v2_0), v2_0);
+    }
 }

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 {
@@ -231,6 +227,29 @@ impl SbiRet {
         matches!(self.error, RET_SUCCESS)
     }
 
+    /// Returns `true` if the SBI call succeeded and the value inside of it matches a predicate.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// # use sbi_spec::binary::SbiRet;
+    /// let x = SbiRet::success(2);
+    /// assert_eq!(x.is_ok_and(|x| x > 1), true);
+    ///
+    /// let x = SbiRet::success(0);
+    /// assert_eq!(x.is_ok_and(|x| x > 1), false);
+    ///
+    /// let x = SbiRet::no_shmem();
+    /// assert_eq!(x.is_ok_and(|x| x > 1), false);
+    /// ```
+    #[must_use]
+    #[inline]
+    pub fn is_ok_and(self, f: impl FnOnce(usize) -> bool) -> bool {
+        self.into_result().is_ok_and(f)
+    }
+
     /// Returns `true` if current SBI return is an error.
     ///
     /// # Examples
@@ -251,6 +270,27 @@ impl SbiRet {
         !self.is_ok()
     }
 
+    /// Returns `true` if the result is an error and the value inside of it matches a predicate.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use sbi_spec::binary::{SbiRet, Error};
+    /// let x = SbiRet::denied();
+    /// assert_eq!(x.is_err_and(|x| x == Error::Denied), true);
+    ///
+    /// let x = SbiRet::invalid_address();
+    /// assert_eq!(x.is_err_and(|x| x == Error::Denied), false);
+    ///
+    /// let x = SbiRet::success(0);
+    /// assert_eq!(x.is_err_and(|x| x == Error::Denied), false);
+    /// ```
+    #[must_use]
+    #[inline]
+    pub fn is_err_and(self, f: impl FnOnce(Error) -> bool) -> bool {
+        self.into_result().is_err_and(f)
+    }
+
     /// Converts from `SbiRet` to [`Option<usize>`].
     ///
     /// Converts `self` into an [`Option<usize>`], consuming `self`,
@@ -415,6 +455,54 @@ impl SbiRet {
         self.into_result().map_err(op)
     }
 
+    /// Calls a function with a reference to the contained value if current SBI call succeeded.
+    ///
+    /// Returns the original result.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use sbi_spec::binary::SbiRet;
+    /// // Assume that SBI debug console have read 512 bytes into a buffer.
+    /// let ret = SbiRet::success(512);
+    /// // Inspect the SBI DBCN call result.
+    /// let idx = ret
+    ///     .inspect(|x| println!("bytes written: {x}"))
+    ///     .map(|x| x - 1)
+    ///     .expect("SBI DBCN call failed");
+    /// assert_eq!(idx, 511);
+    /// ```
+    #[inline]
+    pub fn inspect<F: FnOnce(&usize)>(self, f: F) -> Self {
+        if let Ok(ref t) = self.into_result() {
+            f(t);
+        }
+
+        self
+    }
+
+    /// Calls a function with a reference to the contained value if current SBI result is an error.
+    ///
+    /// Returns the original result.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use sbi_spec::binary::SbiRet;
+    /// // Assume that SBI debug console write operation failed for invalid parameter.
+    /// let ret = SbiRet::invalid_param();
+    /// // Print the error if SBI DBCN call failed.
+    /// let ret = ret.inspect_err(|e| eprintln!("failed to read from SBI console: {e:?}"));
+    /// ```
+    #[inline]
+    pub fn inspect_err<F: FnOnce(&Error)>(self, f: F) -> Self {
+        if let Err(ref e) = self.into_result() {
+            f(e);
+        }
+
+        self
+    }
+
     /// Returns the contained success value, consuming the `self` value.
     ///
     /// # Panics
@@ -543,7 +631,7 @@ impl SbiRet {
     // fixme: should be pub const fn once this function in Result is stablized in constant
     // fixme: should parameter be `res: SbiRet`?
     #[inline]
-    pub fn and(self, res: Result<usize, Error>) -> Result<usize, Error> {
+    pub fn and<U>(self, res: Result<U, Error>) -> Result<U, Error> {
         self.into_result().and(res)
     }
 

sbi-spec/src/lib.rs

@@ -106,6 +106,8 @@ mod tests {
         const_assert_eq!(6, impl_id::COFFER);
         const_assert_eq!(7, impl_id::XEN);
         const_assert_eq!(8, impl_id::POLARFIRE_HSS);
+        const_assert_eq!(9, impl_id::COREBOOT);
+        const_assert_eq!(10, impl_id::OREBOOT);
     }
     // §5
     #[cfg(feature = "legacy")]
@@ -249,6 +251,8 @@ mod tests {
         const_assert_eq!(20, firmware_event::HFENCE_VVMA_ASID_SENT);
         const_assert_eq!(21, firmware_event::HFENCE_VVMA_ASID_RECEIVED);
         const_assert_eq!(65535, firmware_event::PLATFORM);
+
+        const_assert_eq!(4096, shmem_size::SIZE);
         const_assert_eq!(1, flags::CounterCfgFlags::SKIP_MATCH.bits());
         const_assert_eq!(2, flags::CounterCfgFlags::CLEAR_VALUE.bits());
         const_assert_eq!(4, flags::CounterCfgFlags::AUTO_START.bits());

sbi-spec/src/pmu.rs

@@ -8,35 +8,35 @@ pub use fid::*;
 mod fid {
     /// Function ID to get the number of counters, both hardware and firmware.
     ///
-    /// Declared in §11.5.
+    /// Declared in §11.6.
     pub const NUM_COUNTERS: usize = 0;
     /// Function ID to get details about the specified counter.
     ///
-    /// Declared in §11.6.
+    /// Declared in §11.7.
     pub const COUNTER_GET_INFO: usize = 1;
     /// Function ID to find and configure a counter from a set of counters.
     ///
-    /// Declared in §11.7.
+    /// Declared in §11.8.
     pub const COUNTER_CONFIG_MATCHING: usize = 2;
     /// Function ID to start or enable a set of counters on the calling hart with the specified initial value.
     ///
-    /// Declared in §11.8.
+    /// Declared in §11.9.
     pub const COUNTER_START: usize = 3;
     /// Function ID to stop or disable a set of counters on the calling hart.
     ///
-    /// Declared in §11.9.
+    /// Declared in §11.10.
     pub const COUNTER_STOP: usize = 4;
     /// Function ID to provide the current value of a firmware counter.
     ///
-    /// Declared in §11.10.
+    /// Declared in §11.11.
     pub const COUNTER_FW_READ: usize = 5;
     /// Function ID to provide the upper 32 bits from the value of the current firmware counter.
     ///
-    /// Declared in §11.11.
+    /// Declared in §11.12.
     pub const COUNTER_FW_READ_HI: usize = 6;
     /// Function ID to set and enable the PMU snapshot shared memory.
     ///
-    /// Declared in §11.12.
+    /// Declared in §11.13.
     pub const SNAPSHOT_SET_SHMEM: usize = 7;
 }
 
@@ -186,6 +186,14 @@ pub mod firmware_event {
     pub const PLATFORM: usize = 65535;
 }
 
+/// Size of shared memory on PMU extension set by supervisor software for current hart.
+pub mod shmem_size {
+    /// Size of PMU snapshot shared memory.
+    ///
+    /// PMU snapshot memory size must be 4096 size on all architecture XLEN configurations.
+    pub const SIZE: usize = 4096;
+}
+
 /// Find and configure a matching counter.
 /// Start a set of counters.
 /// Stop a set of counters.

sbi-testing/Cargo.toml

@@ -19,8 +19,8 @@ targets = ["riscv32imac-unknown-none-elf", "riscv64imac-unknown-none-elf"]
 
 [dependencies]
 sbi-rt = { version = "0.0.3", path = "../sbi-rt" }
-sbi-spec = { version = "0.0.7", path = "../sbi-spec" }
-riscv = "0.11.1"
+sbi-spec = { version = "0.0.8", path = "../sbi-spec" }
+riscv = { version = "0.12.0", default-features = false }
 log = { version = "0.4", package = "log", optional = true }
 
 [features]

sbi-testing/src/base.rs

@@ -90,6 +90,8 @@ pub fn test(mut f: impl FnMut(Case)) {
         impl_id::COFFER => Ok("Coffer"),
         impl_id::XEN => Ok("Xen Project"),
         impl_id::POLARFIRE_HSS => Ok("PolarFire Hart Software Services"),
+        impl_id::COREBOOT => Ok("Coreboot"),
+        impl_id::OREBOOT => Ok("Oreboot"),
         unknown => Err(unknown),
     }));
     f(Case::GetSbiImplVersion(sbi::get_sbi_impl_version()));

sbi-testing/src/hsm.rs

@@ -235,19 +235,18 @@ fn test_batch(batch: &[usize], mut f: impl FnMut(Case)) -> bool {
 /// 测试用启动入口
 #[naked]
 unsafe extern "C" fn test_entry(hartid: usize, opaque: *mut ItemPerHart) -> ! {
-    core::arch::asm!(
+    core::arch::naked_asm!(
         "csrw sie, zero",   // 关中断
         "call {set_stack}", // 设置栈
         "j    {rust_main}", // 进入 rust
         set_stack = sym set_stack,
         rust_main = sym rust_main,
-        options(noreturn),
     )
 }
 
 #[naked]
 unsafe extern "C" fn set_stack(hart_id: usize, ptr: *const ItemPerHart) {
-    core::arch::asm!("addi sp, a1, 512", "ret", options(noreturn));
+    core::arch::naked_asm!("addi sp, a1, 512", "ret");
 }
 
 #[inline(never)]

sbi-testing/src/lib.rs

@@ -2,7 +2,7 @@
 
 #![no_std]
 #![deny(warnings, missing_docs)]
-#![feature(naked_functions, asm_const)]
+#![feature(naked_functions)]
 
 mod thread;
 

sbi-testing/src/spi.rs

@@ -1,10 +1,12 @@
-//! Inter-processor interrupt extension test suite.
+//! Inter-processor interrupt extension test suite.
 
 use crate::thread::Thread;
-use riscv::register::{
-    scause::Interrupt,
-    scause::{self, Trap},
-    sie,
+use riscv::{
+    interrupt::supervisor::{Exception, Interrupt},
+    register::{
+        scause::{self, Trap},
+        sie,
+    },
 };
 use sbi::HartMask;
 
@@ -18,7 +20,7 @@ pub enum Case {
     /// Test process for an inter-processor interrupt has been received.
     SendIpi,
     /// Test failed for unexpected trap occurred upon tests.
-    UnexpectedTrap(Trap),
+    UnexpectedTrap(Trap<usize, usize>),
     /// All test cases on inter-processor interrupt extension has passed.
     Pass,
 }
@@ -45,12 +47,13 @@ pub fn test(hart_id: usize, mut f: impl FnMut(Case)) {
         sie::set_ssoft();
         thread.execute();
     }
-    match scause::read().cause() {
-        Trap::Interrupt(Interrupt::SupervisorSoft) => {
+    let trap = scause::read().cause();
+    match trap.try_into::<Interrupt, Exception>() {
+        Ok(Trap::Interrupt(Interrupt::SupervisorSoft)) => {
             f(Case::SendIpi);
             f(Case::Pass);
         }
-        trap => {
+        _ => {
             f(Case::UnexpectedTrap(trap));
         }
     }

sbi-testing/src/thread.rs

@@ -109,7 +109,7 @@ impl Thread {
 /// 裸函数。
 #[naked]
 unsafe extern "C" fn execute_naked() {
-    core::arch::asm!(
+    core::arch::naked_asm!(
         r"  .altmacro
             .macro SAVE n
                 sd x\n, \n*8(sp)
@@ -176,6 +176,5 @@ unsafe extern "C" fn execute_naked() {
         // 返回调度
         "   ret",
         "   .option pop",
-        options(noreturn)
     )
 }

sbi-testing/src/time.rs

@@ -1,7 +1,13 @@
 //! Timer programmer extension test suite.
 
 use crate::thread::Thread;
-use riscv::register::scause::{self, Trap};
+use riscv::{
+    interrupt::supervisor::{Exception, Interrupt},
+    register::{
+        scause::{self, Trap},
+        sie, time,
+    },
+};
 
 /// Timer programmer extension test cases.
 #[derive(Clone, Debug)]
@@ -29,15 +35,13 @@ pub enum Case {
     /// Test process for timer has been set.
     SetTimer,
     /// Test failed for unexpected trap during timer test.
-    UnexpectedTrap(Trap),
+    UnexpectedTrap(Trap<usize, usize>),
     /// All test cases on timer extension has passed.
     Pass,
 }
 
 /// Test timer extension.
 pub fn test(delay: u64, mut f: impl FnMut(Case)) {
-    use riscv::register::{scause::Interrupt, sie, time};
-
     if sbi::probe_extension(sbi::Timer).is_unavailable() {
         f(Case::NotExist);
         return;
@@ -84,13 +88,14 @@ pub fn test(delay: u64, mut f: impl FnMut(Case)) {
         sie::set_stimer();
         thread.execute();
     }
-    match scause::read().cause() {
-        Trap::Interrupt(Interrupt::SupervisorTimer) => {
+    let trap = scause::read().cause();
+    match trap.try_into::<Interrupt, Exception>() {
+        Ok(Trap::Interrupt(Interrupt::SupervisorTimer)) => {
             sbi::set_timer(u64::MAX);
             f(Case::SetTimer);
             f(Case::Pass);
         }
-        trap => {
+        _ => {
             f(Case::UnexpectedTrap(trap));
         }
     }

src/forward.rs

@@ -1,7 +1,7 @@
 use crate::{Console, Cppc, EnvInfo, Fence, Hsm, Ipi, Nacl, Pmu, Reset, Sta, Susp, Timer};
 use sbi_spec::{
-    binary::{HartMask, Physical, SbiRet, SharedPtr},
-    nacl::shmem_size::NATIVE,
+    binary::{CounterMask, HartMask, Physical, SbiRet, SharedPtr},
+    nacl, pmu,
 };
 
 /// Forwards SBI calls onto current supervisor environment.
@@ -39,7 +39,7 @@ use sbi_spec::{
 /// #     fn hart_get_status(&self, _: usize) -> SbiRet { unimplemented!() }
 /// # }
 /// ```
-#[derive(Debug, Clone)]
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
 pub struct Forward;
 
 impl Console for Forward {
@@ -331,7 +331,7 @@ impl Nacl for Forward {
     }
 
     #[inline]
-    fn set_shmem(&self, shmem: SharedPtr<[u8; NATIVE]>, flags: usize) -> SbiRet {
+    fn set_shmem(&self, shmem: SharedPtr<[u8; nacl::shmem_size::NATIVE]>, flags: usize) -> SbiRet {
         match () {
             #[cfg(feature = "forward")]
             () => sbi_rt::nacl_set_shmem(shmem, flags),
@@ -413,24 +413,18 @@ impl Pmu for Forward {
         event_idx: usize,
         event_data: u64,
     ) -> SbiRet {
+        let counter_mask = CounterMask::from_mask_base(counter_idx_mask, counter_idx_base);
         match () {
             #[cfg(feature = "forward")]
             () => sbi_rt::pmu_counter_config_matching(
-                counter_idx_base,
-                counter_idx_mask,
+                counter_mask,
                 config_flags,
                 event_idx,
                 event_data,
             ),
             #[cfg(not(feature = "forward"))]
             () => {
-                let _ = (
-                    counter_idx_base,
-                    counter_idx_mask,
-                    config_flags,
-                    event_idx,
-                    event_data,
-                );
+                let _ = (counter_mask, config_flags, event_idx, event_data);
                 unimplemented!()
             }
         }
@@ -444,22 +438,13 @@ impl Pmu for Forward {
         start_flags: usize,
         initial_value: u64,
     ) -> SbiRet {
+        let counter_mask = CounterMask::from_mask_base(counter_idx_mask, counter_idx_base);
         match () {
             #[cfg(feature = "forward")]
-            () => sbi_rt::pmu_counter_start(
-                counter_idx_base,
-                counter_idx_mask,
-                start_flags,
-                initial_value,
-            ),
+            () => sbi_rt::pmu_counter_start(counter_mask, start_flags, initial_value),
             #[cfg(not(feature = "forward"))]
             () => {
-                let _ = (
-                    counter_idx_base,
-                    counter_idx_mask,
-                    start_flags,
-                    initial_value,
-                );
+                let _ = (counter_mask, start_flags, initial_value);
                 unimplemented!()
             }
         }
@@ -472,12 +457,13 @@ impl Pmu for Forward {
         counter_idx_mask: usize,
         stop_flags: usize,
     ) -> SbiRet {
+        let counter_mask = CounterMask::from_mask_base(counter_idx_mask, counter_idx_base);
         match () {
             #[cfg(feature = "forward")]
-            () => sbi_rt::pmu_counter_stop(counter_idx_base, counter_idx_mask, stop_flags),
+            () => sbi_rt::pmu_counter_stop(counter_mask, stop_flags),
             #[cfg(not(feature = "forward"))]
             () => {
-                let _ = (counter_idx_base, counter_idx_mask, stop_flags);
+                let _ = (counter_mask, stop_flags);
                 unimplemented!()
             }
         }
@@ -508,6 +494,23 @@ impl Pmu for Forward {
             }
         }
     }
+
+    #[inline]
+    fn snapshot_set_shmem(
+        &self,
+        shmem: SharedPtr<[u8; pmu::shmem_size::SIZE]>,
+        flags: usize,
+    ) -> SbiRet {
+        match () {
+            #[cfg(feature = "forward")]
+            () => sbi_rt::pmu_snapshot_set_shmem(shmem, flags),
+            #[cfg(not(feature = "forward"))]
+            () => {
+                let _ = (shmem, flags);
+                unimplemented!()
+            }
+        }
+    }
 }
 
 impl Reset for Forward {

src/lib.rs

@@ -583,7 +583,7 @@ pub const VERSION: &str = env!("CARGO_PKG_VERSION");
 
 pub extern crate sbi_spec as spec;
 
-pub use sbi_spec::binary::{HartMask, Physical, SbiRet, SharedPtr};
+pub use sbi_spec::binary::{CounterMask, HartMask, Physical, SbiRet, SharedPtr};
 
 /// Generate `RustSBI` implementation for structure of each extension.
 ///

src/nacl.rs

@@ -22,7 +22,6 @@ use spec::{
 /// *NOTE:* The M-mode firmware should not implement the SBI nested acceleration
 /// extension if the underlying platform has the RISC-V H-extension implemented
 /// in hardware.
-
 pub trait Nacl {
     /// Probe nested acceleration feature.
     ///

src/pmu.rs

@@ -1,4 +1,5 @@
 use sbi_spec::binary::SbiRet;
+use spec::{binary::SharedPtr, pmu::shmem_size::SIZE};
 
 /// Performance Monitoring Unit extension.
 ///
@@ -110,6 +111,7 @@ pub trait Pmu {
     /// | `SbiRet::success()`       | counter found and configured successfully.
     /// | `SbiRet::invalid_param()` | the set of counters has at least one invalid counter.
     /// | `SbiRet::not_supported()` | none of the counters can monitor the specified event.
+    // TODO: (breaking change) change parameter `counter_idx_base` and `counter_idx_mask` into `CounterMask` for RustSBI 0.5.0
     fn counter_config_matching(
         &self,
         counter_idx_base: usize,
@@ -144,6 +146,7 @@ pub trait Pmu {
     /// | `SbiRet::success()`         | counter started successfully.
     /// | `SbiRet::invalid_param()`   | the set of counters has at least one invalid counter.
     /// | `SbiRet::already_started()` | the set of counters includes at least one counter which is already started.
+    // TODO: (breaking change) change parameter `counter_idx_base` and `counter_idx_mask` into `CounterMask` for RustSBI 0.5.0
     fn counter_start(
         &self,
         counter_idx_base: usize,
@@ -172,6 +175,7 @@ pub trait Pmu {
     /// | `SbiRet::success()`         | counter stopped successfully.
     /// | `SbiRet::invalid_param()`   | the set of counters has at least one invalid counter.
     /// | `SbiRet::already_stopped()` | the set of counters includes at least one counter which is already stopped.
+    // TODO: (breaking change) change parameter `counter_idx_base` and `counter_idx_mask` into `CounterMask` for RustSBI 0.5.0
     fn counter_stop(
         &self,
         counter_idx_base: usize,
@@ -224,6 +228,60 @@ pub trait Pmu {
             }
         }
     }
+    /// Set and enable the PMU snapshot shared memory on the calling hart.
+    ///
+    /// This is an optional function and the SBI implementation may choose not to implement it.
+    ///
+    /// # Parameters
+    ///
+    /// If `shmem` physical address is not all-ones bitwise, then `shmem` specifies
+    /// the snapshot shared memory physical base address.
+    /// The `shmem` MUST be 4096 bytes (i.e. RV64 page) aligned and the size of the snapshot
+    /// shared memory must be 4096 bytes.
+    ///
+    /// If `shmem` physical address is all-ones bitwise, then the PMU snapshot shared memory
+    /// is cleared and disabled.
+    ///
+    /// The `flags` parameter is reserved for future use and must be zero.
+    ///
+    /// The layout of the snapshot shared memory is described in the table below.
+    ///
+    /// | Name | Offset | Size | Description |
+    /// |:------|:-------|:-----|:-----------|
+    /// | `counter_overflow_bitmap` | `0x0000` | `8` | A bitmap of all logical overflown counters relative to the `counter_idx_base`. This is valid only if the `Sscofpmf` ISA extension is available. Otherwise, it must be zero. |
+    /// | `counter_values` | `0x0008` | `512` | An array of 64-bit logical counters where each index represents the value of each logical counter associated with hardware/firmware relative to the `counter_idx_base`. |
+    /// | _Reserved_ | `0x0208` | `3576` | Reserved for future use. |
+    ///
+    /// Any future revisions to this structure should be made in a backward compatible manner and will be associated with an SBI version.
+    ///
+    /// The logical counter indicies in the `counter_overflow_bitmap` and `counter_values` array are
+    /// relative w.r.t to `counter_idx_base` argument present in the `pmu_counter_stop` and
+    /// `pmu_counter_start` functions.
+    /// This allows the users to use snapshot feature for more than `XLEN` counters if required.
+    ///
+    /// This function should be invoked only once per hart at boot time. Once configured, the SBI
+    /// implementation has read/write access to the shared memory when `pmu_counter_stop` is
+    /// invoked with the `TAKE_SNAPSHOT` flag set. The SBI implementation has read only access when
+    /// `pmu_counter_start` is invoked with the `INIT_SNAPSHOT` flag set.
+    /// The SBI implementation must not access this memory any other time.
+    ///
+    /// # Return value
+    ///
+    /// The possible return error codes returned in `SbiRet.error` are shown in the table below:
+    ///
+    /// | Return code               | Description
+    /// |:--------------------------|:----------------------------------------------
+    /// | `SbiRet::success()`       | Shared memory was set or cleared successfully.
+    /// | `SbiRet::not_supported()` | The SBI PMU snapshot functionality is not available in the SBI implementation.
+    /// | `SbiRet::invalid_param()` | The `flags` parameter is not zero or the `shmem` is not 4096-byte aligned.
+    /// | `SbiRet::invalid_address()` | The shared memory pointed to by the `shmem` and is not writable or does not satisfy other requirements of shared memory
+    /// | `SbiRet::failed()` | The request failed for unspecified or unknown other reasons.
+    #[inline]
+    fn snapshot_set_shmem(&self, shmem: SharedPtr<[u8; SIZE]>, flags: usize) -> SbiRet {
+        // Optional function, `not_supported` is returned if not implemented.
+        let _ = (shmem, flags);
+        SbiRet::not_supported()
+    }
     /// Function internal to macros. Do not use.
     #[doc(hidden)]
     #[inline]
@@ -292,6 +350,10 @@ impl<T: Pmu> Pmu for &T {
     fn counter_fw_read_hi(&self, counter_idx: usize) -> SbiRet {
         T::counter_fw_read_hi(self, counter_idx)
     }
+    #[inline]
+    fn snapshot_set_shmem(&self, shmem: SharedPtr<[u8; SIZE]>, flags: usize) -> SbiRet {
+        T::snapshot_set_shmem(self, shmem, flags)
+    }
 }
 
 impl<T: Pmu> Pmu for Option<T> {
@@ -371,6 +433,12 @@ impl<T: Pmu> Pmu for Option<T> {
             .unwrap_or(SbiRet::not_supported())
     }
     #[inline]
+    fn snapshot_set_shmem(&self, shmem: SharedPtr<[u8; SIZE]>, flags: usize) -> SbiRet {
+        self.as_ref()
+            .map(|inner| T::snapshot_set_shmem(inner, shmem, flags))
+            .unwrap_or(SbiRet::not_supported())
+    }
+    #[inline]
     fn _rustsbi_probe(&self) -> usize {
         match self {
             Some(_) => sbi_spec::base::UNAVAILABLE_EXTENSION.wrapping_add(1),

src/sta.rs

@@ -13,7 +13,6 @@ use sbi_spec::binary::{SbiRet, SharedPtr};
 /// as steal-time accounting. The Steal-time Accounting (STA) extension defines the
 /// mechanism in which an SBI implementation provides steal-time and preemption
 /// information, for each virtual hart, to supervisor-mode software.
-
 pub trait Sta {
     /// Set Steal-time Shared Memory Address.
     ///

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.

src/traits.rs

@@ -255,6 +255,9 @@ pub fn _rustsbi_pmu<T: crate::Pmu>(pmu: &T, param: [usize; 6], function: usize)
                 spec::pmu::COUNTER_STOP => pmu.counter_stop(param0, param1, param2),
                 spec::pmu::COUNTER_FW_READ => pmu.counter_fw_read(param0),
                 spec::pmu::COUNTER_FW_READ_HI => pmu.counter_fw_read_hi(param0),
+                spec::pmu::SNAPSHOT_SET_SHMEM => {
+                    pmu.snapshot_set_shmem(SharedPtr::new(param0, param1), param2)
+                }
                 _ => SbiRet::not_supported(),
             }
         }
@@ -278,6 +281,9 @@ pub fn _rustsbi_pmu<T: crate::Pmu>(pmu: &T, param: [usize; 6], function: usize)
                 spec::pmu::COUNTER_STOP => pmu.counter_stop(param0, param1, param2),
                 spec::pmu::COUNTER_FW_READ => pmu.counter_fw_read(param0),
                 spec::pmu::COUNTER_FW_READ_HI => pmu.counter_fw_read_hi(param0),
+                spec::pmu::SNAPSHOT_SET_SHMEM => {
+                    pmu.snapshot_set_shmem(SharedPtr::new(param0, param1), param2)
+                }
                 _ => SbiRet::not_supported(),
             }
         }

tests/build-full.rs

@@ -3,6 +3,7 @@ use rustsbi::RustSBI;
 use sbi_spec::{
     binary::{HartMask, Physical, SbiRet, SharedPtr},
     nacl::shmem_size::NATIVE,
+    pmu::shmem_size::SIZE,
 };
 
 #[derive(RustSBI)]
@@ -176,21 +177,23 @@ fn generated_extensions() {
     assert_eq!(sbi.handle_ecall(0x504D55, 4, [0; 6]), SbiRet::success(22));
     assert_eq!(sbi.handle_ecall(0x504D55, 5, [0; 6]), SbiRet::success(23));
     assert_eq!(sbi.handle_ecall(0x504D55, 6, [0; 6]), SbiRet::success(24));
-    assert_eq!(sbi.handle_ecall(0x53525354, 0, [0; 6]), SbiRet::success(25));
-    assert_eq!(sbi.handle_ecall(0x52464E43, 0, [0; 6]), SbiRet::success(26));
-    assert_eq!(sbi.handle_ecall(0x52464E43, 1, [0; 6]), SbiRet::success(27));
-    assert_eq!(sbi.handle_ecall(0x52464E43, 2, [0; 6]), SbiRet::success(28));
-    assert_eq!(sbi.handle_ecall(0x52464E43, 3, [0; 6]), SbiRet::success(29));
-    assert_eq!(sbi.handle_ecall(0x52464E43, 4, [0; 6]), SbiRet::success(30));
-    assert_eq!(sbi.handle_ecall(0x52464E43, 5, [0; 6]), SbiRet::success(31));
-    assert_eq!(sbi.handle_ecall(0x52464E43, 6, [0; 6]), SbiRet::success(32));
-    assert_eq!(sbi.handle_ecall(0x535441, 0, [0; 6]), SbiRet::success(33));
-    assert_eq!(sbi.handle_ecall(0x53555350, 0, [0; 6]), SbiRet::success(34));
+    assert_eq!(sbi.handle_ecall(0x504D55, 7, [0; 6]), SbiRet::success(25));
+    // TODO eid and fid of snapshot_set_shmem
+    assert_eq!(sbi.handle_ecall(0x53525354, 0, [0; 6]), SbiRet::success(26));
+    assert_eq!(sbi.handle_ecall(0x52464E43, 0, [0; 6]), SbiRet::success(27));
+    assert_eq!(sbi.handle_ecall(0x52464E43, 1, [0; 6]), SbiRet::success(28));
+    assert_eq!(sbi.handle_ecall(0x52464E43, 2, [0; 6]), SbiRet::success(29));
+    assert_eq!(sbi.handle_ecall(0x52464E43, 3, [0; 6]), SbiRet::success(30));
+    assert_eq!(sbi.handle_ecall(0x52464E43, 4, [0; 6]), SbiRet::success(31));
+    assert_eq!(sbi.handle_ecall(0x52464E43, 5, [0; 6]), SbiRet::success(32));
+    assert_eq!(sbi.handle_ecall(0x52464E43, 6, [0; 6]), SbiRet::success(33));
+    assert_eq!(sbi.handle_ecall(0x535441, 0, [0; 6]), SbiRet::success(34));
+    assert_eq!(sbi.handle_ecall(0x53555350, 0, [0; 6]), SbiRet::success(35));
     assert!(sbi.handle_ecall(0x54494D45, 0, [0; 6]).is_ok());
-    assert_eq!(sbi.timer.0.take(), 35);
-    assert_eq!(sbi.handle_ecall(0x10, 4, [0; 6]), SbiRet::success(36));
-    assert_eq!(sbi.handle_ecall(0x10, 5, [0; 6]), SbiRet::success(37));
-    assert_eq!(sbi.handle_ecall(0x10, 6, [0; 6]), SbiRet::success(38));
+    assert_eq!(sbi.timer.0.take(), 36);
+    assert_eq!(sbi.handle_ecall(0x10, 4, [0; 6]), SbiRet::success(37));
+    assert_eq!(sbi.handle_ecall(0x10, 5, [0; 6]), SbiRet::success(38));
+    assert_eq!(sbi.handle_ecall(0x10, 6, [0; 6]), SbiRet::success(39));
 }
 
 struct DummyConsole;
@@ -310,13 +313,18 @@ impl rustsbi::Pmu for DummyPmu {
     fn counter_fw_read_hi(&self, _: usize) -> SbiRet {
         SbiRet::success(24)
     }
+
+    fn snapshot_set_shmem(&self, _: SharedPtr<[u8; SIZE]>, _: usize) -> SbiRet {
+        SbiRet::success(25)
+    }
+    // TODO fn snapshot_set_shmem
 }
 
 struct DummyReset;
 
 impl rustsbi::Reset for DummyReset {
     fn system_reset(&self, _: u32, _: u32) -> SbiRet {
-        SbiRet::success(25)
+        SbiRet::success(26)
     }
 }
 
@@ -324,31 +332,31 @@ struct DummyFence;
 
 impl rustsbi::Fence for DummyFence {
     fn remote_fence_i(&self, _: HartMask) -> SbiRet {
-        SbiRet::success(26)
+        SbiRet::success(27)
     }
 
     fn remote_sfence_vma(&self, _: HartMask, _: usize, _: usize) -> SbiRet {
-        SbiRet::success(27)
+        SbiRet::success(28)
     }
 
     fn remote_sfence_vma_asid(&self, _: HartMask, _: usize, _: usize, _: usize) -> SbiRet {
-        SbiRet::success(28)
+        SbiRet::success(29)
     }
 
     fn remote_hfence_gvma_vmid(&self, _: HartMask, _: usize, _: usize, _: usize) -> SbiRet {
-        SbiRet::success(29)
+        SbiRet::success(30)
     }
 
     fn remote_hfence_gvma(&self, _: HartMask, _: usize, _: usize) -> SbiRet {
-        SbiRet::success(30)
+        SbiRet::success(31)
     }
 
     fn remote_hfence_vvma_asid(&self, _: HartMask, _: usize, _: usize, _: usize) -> SbiRet {
-        SbiRet::success(31)
+        SbiRet::success(32)
     }
 
     fn remote_hfence_vvma(&self, _: HartMask, _: usize, _: usize) -> SbiRet {
-        SbiRet::success(32)
+        SbiRet::success(33)
     }
 }
 
@@ -356,7 +364,7 @@ struct DummySta;
 
 impl rustsbi::Sta for DummySta {
     fn set_shmem(&self, _: SharedPtr<[u8; 64]>, _: usize) -> SbiRet {
-        SbiRet::success(33)
+        SbiRet::success(34)
     }
 }
 
@@ -364,7 +372,7 @@ struct DummySusp;
 
 impl rustsbi::Susp for DummySusp {
     fn system_suspend(&self, _: u32, _: usize, _: usize) -> SbiRet {
-        SbiRet::success(34)
+        SbiRet::success(35)
     }
 }
 
@@ -372,7 +380,7 @@ struct DummyTimer(RefCell<u64>);
 
 impl rustsbi::Timer for DummyTimer {
     fn set_timer(&self, _: u64) {
-        self.0.replace(35);
+        self.0.replace(36);
     }
 }
 
@@ -380,14 +388,14 @@ struct DummyEnvInfo;
 
 impl rustsbi::EnvInfo for DummyEnvInfo {
     fn mvendorid(&self) -> usize {
-        36
+        37
     }
 
     fn marchid(&self) -> usize {
-        37
+        38
     }
 
     fn mimpid(&self) -> usize {
-        38
+        39
     }
 }