rt: pmu: change `counter_idx_mask` and `counter_idx_base` parameters into `counter_idx` with type `CounterMask`.

Mark that in the `rustsbi` main package, signatures of those three functions would be changed in RustSBI 0.5.0, as they are breaking changes.

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

CHANGELOG.md

@@ -8,13 +8,12 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## Unreleased
 
 ### Added
+
 - ci: add `check-changlog` and `check-commit-signatures` in `workflows`.
 - pmu: add missing `snapshot_set_shmem` function and testcases in `Pmu` trait.
-
-### Added
-
 - 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.
 
 ### Modified
 

sbi-rt/CHANGELOG.md

@@ -7,15 +7,15 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
-### Added
-- pmu: add missing `pmu_snapshot_set_shmem` function.
-
 ### Added
 
-- `pmu_snapshot_set_shmem` function signature, TODO: documents and implementation
+- pmu: add missing `pmu_snapshot_set_shmem` function.
+- pmu: `pmu_snapshot_set_shmem` function signature, TODO: documents and implementation
 
 ### Modified
 
+- pmu: change `counter_idx_mask` and `counter_idx_base` parameters into `counter_idx` with type `CounterMask`.
+
 ### Fixed
 
 ## [0.0.3] - 2024-02-08

sbi-rt/src/pmu.rs

@@ -3,7 +3,7 @@
 use crate::binary::{sbi_call_0, sbi_call_1, sbi_call_3};
 
 use sbi_spec::{
-    binary::{SbiRet, SharedPtr},
+    binary::{CounterMask, SbiRet, SharedPtr},
     pmu::{
         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,
@@ -59,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.
 ///
@@ -80,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.
@@ -104,8 +104,7 @@ pub fn pmu_counter_get_info(counter_idx: usize) -> SbiRet {
 /// 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,
@@ -113,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(
@@ -142,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,15 +167,11 @@ where
 ///
 /// 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(
@@ -203,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,14 +219,11 @@ where
 ///
 /// 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,

src/forward.rs

@@ -1,6 +1,6 @@
 use crate::{Console, Cppc, EnvInfo, Fence, Hsm, Ipi, Nacl, Pmu, Reset, Sta, Susp, Timer};
 use sbi_spec::{
-    binary::{HartMask, Physical, SbiRet, SharedPtr},
+    binary::{CounterMask, HartMask, Physical, SbiRet, SharedPtr},
     nacl, pmu,
 };
 
@@ -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!()
             }
         }

src/pmu.rs

@@ -111,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,
@@ -145,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,
@@ -173,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,