refactor(bench)!: move benchmarking facilities to their own crate

.github/workflows/main.yml

@@ -136,7 +136,7 @@ jobs:
       - name: clippy
         uses: clechasseur/rs-clippy-check@v3
         with:
-          args: --verbose --locked -p riot-rs-embassy
+          args: --verbose --locked -p riot-rs-embassy -p riot-rs-bench
 
       # TODO: we'll eventually want to enable relevant features
       - name: "rustdoc"

Cargo.toml

@@ -49,6 +49,7 @@ esp-wifi = { git = "https://github.com/kaspar030/esp-wifi", branch = "update-esp
 linkme = { version = "0.3.21", features = ["used_linker"] }
 
 riot-rs = { path = "src/riot-rs", default-features = false }
+riot-rs-bench = { path = "src/riot-rs-bench", default-features = false }
 riot-rs-debug = { path = "src/riot-rs-debug", default-features = false }
 riot-rs-rt = { path = "src/riot-rs-rt" }
 riot-rs-runqueue = { path = "src/riot-rs-runqueue" }

examples/benchmark/src/main.rs

@@ -7,7 +7,7 @@ use riot_rs::debug::println;
 
 #[riot_rs::thread]
 fn main() {
-    match riot_rs::rt::benchmark(10000, || {
+    match riot_rs::bench::benchmark(10000, || {
         //
     }) {
         Ok(ticks) => {

src/riot-rs-bench/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "riot-rs-bench"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+repository.workspace = true
+
+[lints]
+workspace = true
+
+[dependencies]
+cfg-if = { workspace = true }
+
+[target.'cfg(context = "cortex-m")'.dependencies]
+cortex-m = { workspace = true, features = ["critical-section-single-core"] }

src/riot-rs-bench/src/cortexm.rs

@@ -0,0 +1,36 @@
+use cortex_m::{
+    peripheral::{syst::SystClkSource, SYST},
+    Peripherals,
+};
+
+use crate::Error;
+
+#[allow(missing_docs)]
+pub fn benchmark<F: Fn() -> ()>(iterations: usize, f: F) -> Result<usize, Error> {
+    let mut p = unsafe { Peripherals::steal() };
+    //
+    p.SCB.clear_sleepdeep();
+
+    //
+    p.SYST.set_clock_source(SystClkSource::Core);
+    p.SYST.set_reload(0x00FFFFFF);
+    p.SYST.clear_current();
+    p.SYST.enable_counter();
+
+    // Wait for the system timer to be ready
+    while SYST::get_current() == 0 {}
+
+    let before = SYST::get_current();
+
+    for _ in 0..iterations {
+        f();
+    }
+
+    let total = before - SYST::get_current();
+
+    if p.SYST.has_wrapped() {
+        Err(Error::SystemTimerWrapped)
+    } else {
+        Ok(total as usize / iterations)
+    }
+}

src/riot-rs-bench/src/lib.rs

@@ -0,0 +1,55 @@
+//! Provides on-board benchmarking facilities.
+
+#![cfg_attr(not(test), no_std)]
+#![feature(error_in_core)]
+#![deny(clippy::pedantic)]
+#![deny(missing_docs)]
+
+cfg_if::cfg_if! {
+    if #[cfg(context = "cortex-m")] {
+        mod cortexm;
+        use cortexm as bench;
+    }
+    else if #[cfg(context = "riot-rs")] {
+        // When run with laze but the architecture is not supported
+        compile_error!("benchmarking is not supported for this architecture");
+    } else {
+        // Provide a default bench module, for arch-independent tooling
+        mod bench {
+            use crate::Error;
+
+            /// Benchmarks "time" required to run the provided function.
+            ///
+            /// Runs the provided function `iterations` times, and returns the mean number of system timer
+            /// increments per iteration.
+            ///
+            /// # Errors
+            ///
+            /// Returns [`Error::SystemTimerWrapped`] if the system timer counter has wrapped when
+            /// benchmarking.
+            #[allow(unused_variables)]
+            pub fn benchmark<F: Fn()>(iterations: usize, f: F) -> Result<usize, Error> {
+                unimplemented!();
+            }
+        }
+    }
+}
+
+pub use bench::benchmark;
+
+/// Possible errors happening when benchmarking.
+#[derive(Debug)]
+pub enum Error {
+    /// The system timer wrapped when benchmarking.
+    SystemTimerWrapped,
+}
+
+impl core::fmt::Display for Error {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Self::SystemTimerWrapped => write!(f, "system timer wrapped"),
+        }
+    }
+}
+
+impl core::error::Error for Error {}

src/riot-rs-rt/src/cortexm.rs

@@ -208,34 +208,3 @@ pub fn init() {
         p.SCB.set_priority(SystemHandler::PendSV, 0xFF);
     }
 }
-
-pub fn benchmark<F: Fn() -> ()>(iterations: usize, f: F) -> core::result::Result<usize, ()> {
-    use cortex_m::peripheral::syst::SystClkSource;
-    use cortex_m::Peripherals;
-
-    let mut p = unsafe { Peripherals::steal() };
-    //
-    p.SCB.clear_sleepdeep();
-
-    //
-    p.SYST.set_clock_source(SystClkSource::Core);
-    p.SYST.set_reload(0x00FFFFFF);
-    p.SYST.clear_current();
-    p.SYST.enable_counter();
-
-    while cortex_m::peripheral::SYST::get_current() == 0 {}
-
-    let before = cortex_m::peripheral::SYST::get_current();
-
-    for _ in 0..iterations {
-        f();
-    }
-
-    let total = before - cortex_m::peripheral::SYST::get_current();
-
-    if p.SYST.has_wrapped() {
-        Err(())
-    } else {
-        Ok((total) as usize / iterations)
-    }
-}

src/riot-rs-rt/src/esp.rs

@@ -4,7 +4,3 @@ fn main() -> ! {
 }
 
 pub fn init() {}
-
-pub fn benchmark<F: Fn() -> ()>(_iterations: usize, _f: F) -> core::result::Result<usize, ()> {
-    unimplemented!()
-}

src/riot-rs-rt/src/lib.rs

@@ -36,15 +36,10 @@ cfg_if::cfg_if! {
         // Provide a default architecture, for arch-independent tooling
         mod arch {
             pub fn init() {}
-            pub fn benchmark<F: Fn()>(_iterations: usize, _f: F) -> core::result::Result<usize, ()> {
-                unimplemented!();
-            }
         }
     }
 }
 
-pub use arch::benchmark;
-
 const ISR_STACKSIZE: usize =
     riot_rs_utils::usize_from_env_or!("CONFIG_ISR_STACKSIZE", 8192, "ISR stack size (in bytes)");
 

src/riot-rs/Cargo.toml

@@ -9,6 +9,7 @@ workspace = true
 
 [dependencies]
 linkme = { workspace = true }
+riot-rs-bench = { workspace = true }
 riot-rs-boards = { path = "../riot-rs-boards" }
 riot-rs-buildinfo = { path = "../riot-rs-buildinfo" }
 riot-rs-debug = { workspace = true }

src/riot-rs/src/lib.rs

@@ -3,7 +3,10 @@
 //! This is a meta-package, pulling in the sub-crates of RIOT-rs.
 
 #![no_std]
+#![feature(doc_cfg)]
 
+#[doc(inline)]
+pub use riot_rs_bench as bench;
 pub use riot_rs_buildinfo as buildinfo;
 pub use riot_rs_debug as debug;
 pub use riot_rs_embassy::{self as embassy, define_peripherals};