test(test_suite): add a kernel benchmark test mutex_ceiling and `mu…

…tex_none`

src/constance_test_suite/src/kernel_benchmarks/mutex.rs

@@ -0,0 +1,84 @@
+//! The common part of `mutex_*`. See [`super::mutex_none`] for a sequence
+//! diagram.
+use constance::{
+    kernel::{cfg::CfgBuilder, Kernel, Mutex, MutexProtocol, Task},
+    time::Duration,
+};
+use core::marker::PhantomData;
+
+use super::Bencher;
+use crate::utils::benchmark::Interval;
+
+pub(super) struct AppInner<System, Options> {
+    task1: Task<System>,
+    mtx: Mutex<System>,
+    _phantom: PhantomData<Options>,
+}
+
+pub(super) trait MutexBenchmarkOptions: 'static + Send + Sync {
+    const PROTOCOL: MutexProtocol;
+}
+
+pub(super) type AppInnerNone<System> = AppInner<System, NoneOptions>;
+pub(super) type AppInnerCeiling<System> = AppInner<System, CeilingOptions>;
+
+pub(super) struct NoneOptions;
+pub(super) struct CeilingOptions;
+
+impl MutexBenchmarkOptions for NoneOptions {
+    const PROTOCOL: MutexProtocol = MutexProtocol::None;
+}
+
+impl MutexBenchmarkOptions for CeilingOptions {
+    const PROTOCOL: MutexProtocol = MutexProtocol::Ceiling(1);
+}
+
+const I_LOCK: Interval = "lock mutex";
+const I_UNLOCK_DISPATCHING: Interval = "unlock mutex with dispatch";
+const I_UNLOCK: Interval = "unlock mutex";
+
+impl<System: Kernel, Options: MutexBenchmarkOptions> AppInner<System, Options> {
+    /// Used by `use_benchmark_in_kernel_benchmark!`
+    pub(super) const fn new<B: Bencher<Self>>(b: &mut CfgBuilder<System>) -> Self {
+        let task1 = Task::build()
+            .start(task1_body::<System, Options, B>)
+            .priority(1)
+            .finish(b);
+
+        let mtx = Mutex::build().protocol(Options::PROTOCOL).finish(b);
+
+        Self {
+            task1,
+            mtx,
+            _phantom: PhantomData,
+        }
+    }
+
+    /// Used by `use_benchmark_in_kernel_benchmark!`
+    pub(super) fn iter<B: Bencher<Self>>() {
+        B::mark_start(); // I_LOCK
+        B::app().mtx.lock().unwrap();
+        B::mark_end(I_LOCK);
+
+        B::app().task1.activate().unwrap();
+        System::sleep(Duration::from_millis(200)).unwrap();
+
+        B::mark_start(); // I_UNLOCK_DISPATCHING
+        B::app().mtx.unlock().unwrap();
+    }
+}
+
+fn task1_body<
+    System: Kernel,
+    Options: MutexBenchmarkOptions,
+    B: Bencher<AppInner<System, Options>>,
+>(
+    _: usize,
+) {
+    B::app().mtx.lock().unwrap();
+    B::mark_end(I_UNLOCK_DISPATCHING);
+
+    B::mark_start();
+    B::app().mtx.unlock().unwrap();
+    B::mark_end(I_UNLOCK);
+}

src/constance_test_suite/src/kernel_benchmarks/mutex_ceiling.rs

@@ -0,0 +1,12 @@
+//! Measures the execution times of mutex operations using a mutex created with
+//! [`Ceiling`] as its locking protocol.
+//!
+//! [`Ceiling`]: constance::kernel::MutexProtocol::Ceiling
+//!
+//! See [`mutex_none`](super::mutex_none) for the sequence diagram of this test.
+//!
+use_benchmark_in_kernel_benchmark! {
+    pub unsafe struct App<System> {
+        inner: super::mutex::AppInnerCeiling<System>,
+    }
+}

src/constance_test_suite/src/kernel_benchmarks/mutex_none.rs

@@ -0,0 +1,38 @@
+//! Measures the execution times of mutex operations using a mutex created with
+//! [`None`] as its locking protocol.
+//!
+//! [`None`]: constance::kernel::MutexProtocol::None
+//!
+//! ```text
+//!             ┌─────┐                  ┌────┐
+//!      mtx   pri　main               task1 pri
+//!      │1│   │3│　 │ │                 ┊    ┊
+//!      │ │   │ │　 │ │                 ┊    ┊     ┐
+//!      ├─┤   ├─┤　 │ │ mtx lock        ┊    ┊     │ I_LOCK
+//!      │0│   │1│　 │ │                 ┊    ┊     ┘
+//!      │ │   │ │　 │ │    activate     ┊    ┊
+//!      │ │   │ │　 │ │ ─────────────►  ┊    ┊
+//!      │ │   │ │　 │ │      sleep      ┊    ┊    
+//!      │ │   │ │　 └┬┘ ─────────────► ┌┴┐  ┌┴┐
+//!      │ │   │ │　  │                 │ │  │1│
+//!      │ │   │ │　  │        mtx lock └┬┘  │ │
+//!      │ │   │ │　  │                  │   │ │
+//!      │ │   │ │　 ┌┴┐ sleep end       │   │ │
+//!      │ │   │ │　 │ │                 │   │ │
+//!      │ │   │ │　 │ │   mtx unlock    │   │ │    ┐
+//!      ├─┤   ├─┤　 └┬┘ ─────────────► ┌┴┐  │ │    │ I_UNLOCK_DISPATCING
+//!      │0│   │3│　  ┊                 │ │  │ │    ┘
+//!      │ │   │ │　  ┊                 │ │  │ │             ┐
+//!      ├─┤   │ │　  ┊                 │ │  │ │ mtx unlock  │ I_UNLOCK
+//!      │1│   │ │　  ┊    exit_task    │ │  │ │             ┘
+//!      │ │   │ │　 ┌┴┐ ◀───────────── └┬┘  └┬┘
+//!      │ │   │ │　 │ │                 ┊    ┊
+//!
+//!  pri: effective priority (assuming mtx uses the priority ceiling protocol)
+//! ```　
+//!
+use_benchmark_in_kernel_benchmark! {
+    pub unsafe struct App<System> {
+        inner: super::mutex::AppInnerNone<System>,
+    }
+}

src/constance_test_suite/src/lib.rs

@@ -498,10 +498,19 @@ pub mod kernel_benchmarks {
 
     define_kernel_benchmarks! {
         [$]
+        (mod mutex_ceiling {}, "mutex_ceiling"),
+        (mod mutex_none {}, "mutex_none"),
         (mod semaphore {}, "semaphore"),
         (mod task_lifecycle {}, "task_lifecycle"),
     }
 
+    #[cfg(any(
+        feature = "tests_all",
+        all(feature = "tests_selective", kernel_benchmark = "mutex_none"),
+        all(feature = "tests_selective", kernel_benchmark = "mutex_ceiling"),
+    ))]
+    mod mutex;
+
     /// Invoke the specified macro with a description of test cases
     /// selected by `CONSTANCE_TEST`.
     ///