pmu: add missing pmu_snapshot_set_shmem function

- rustsbi: pmu: add missing `snapshot_set_shmem` function in `Pmu` trait, impl for `&T` and `Option<T>` and `Forward` structure
- rt: `pmu_snapshot_set_shmem` function signature, TODO: documents and implementation
- spec: pmu: add `shmem_size` module for PMU snapshot shared memory, add unit test for `pmu::shmem_size::SIZE`

Signed-off-by: Zhouqi Jiang <[email protected]>

CHANGELOG.md

@@ -9,6 +9,8 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Added
 
+- pmu: add missing `snapshot_set_shmem` function in `Pmu` trait, impl for `&T` and `Option<T>` and `Forward` structure
+
 ### Modified
 
 ### Removed

sbi-rt/CHANGELOG.md

@@ -7,6 +7,14 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- `pmu_snapshot_set_shmem` function signature, TODO: documents and implementation
+
+### Modified
+
+### Fixed
+
 ## [0.0.3] - 2024-02-08
 
 This version adds support to the RISC-V SBI Specification version 2.0 ratified.

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::{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,
     },
 };
 
@@ -286,6 +286,19 @@ 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.
+///
+/// TODO detailed documents from rustsbi library
+#[inline]
+pub fn pmu_snapshot_set_shmem(shmem: SharedPtr<[u8; SIZE]>, flags: usize) -> SbiRet {
+    // TODO call sbi_call_3 for this argument list:
+    // struct sbiret sbi_pmu_snapshot_set_shmem(unsigned long shmem_phys_lo,
+    //     unsigned long shmem_phys_hi,
+    //     unsigned long flags)
+    let _ = (shmem, flags);
+    todo!()
+}
+
 /// Flags to configure performance counter.
 pub trait ConfigFlags {
     /// Get a raw value to pass to SBI environment.

sbi-spec/CHANGELOG.md

@@ -10,6 +10,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - base: add Coreboot and Oreboot to `impl_id` module
 - binary: add counter index mask type
+- pmu: add `shmem_size` module for PMU snapshot shared memory, add unit test for `pmu::shmem_size::SIZE`
 
 ### Modified
 

sbi-spec/src/lib.rs

@@ -251,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);
     }
     // §12
     #[test]

sbi-spec/src/pmu.rs

@@ -185,3 +185,11 @@ pub mod firmware_event {
     /// The `event_data` configuration (or parameter) contains the event encoding.
     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;
+}

src/forward.rs

@@ -2,6 +2,7 @@ use crate::{Console, Cppc, EnvInfo, Fence, Hsm, Ipi, Nacl, Pmu, Reset, Sta, Susp
 use sbi_spec::{
     binary::{HartMask, Physical, SbiRet, SharedPtr},
     nacl::shmem_size::NATIVE,
+    pmu,
 };
 
 /// Forwards SBI calls onto current supervisor environment.
@@ -508,6 +509,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/pmu.rs

@@ -1,4 +1,5 @@
 use sbi_spec::binary::SbiRet;
+use spec::{binary::SharedPtr, pmu::shmem_size::SIZE};
 
 /// Performance Monitoring Unit extension.
 ///
@@ -224,6 +225,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 +347,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 +430,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),