feat(kernel): add and implement Kernel::{boost_priority, unboost_priority}

Author: yvt

src/constance/src/kernel.rs

@@ -1,7 +1,12 @@
 //! The RTOS kernel
 use atomic_ref::AtomicRef;
 use core::{
-    borrow::BorrowMut, fmt, mem::forget, num::NonZeroUsize, ops::Range, sync::atomic::Ordering,
+    borrow::BorrowMut,
+    fmt,
+    mem::forget,
+    num::NonZeroUsize,
+    ops::Range,
+    sync::atomic::{AtomicBool, Ordering},
 };
 
 use crate::utils::{intrusive_list::StaticListHead, BinUInteger, Init, PrioBitmap};
@@ -51,6 +56,35 @@ pub trait Kernel: Port + KernelCfg2 + Sized + 'static {
     /// Return a flag indicating whether CPU Lock is currently active.
     fn has_cpu_lock() -> bool;
 
+    /// Activate [Priority Boost].
+    ///
+    /// Returns [`BadContext`] if Priority Boost is already active, the
+    /// calling context is not a task context, or CPU Lock is active.
+    ///
+    /// [Priority Boost]: crate#system-states
+    /// [`BadContext`]: CpuLockError::BadContext
+    fn boost_priority() -> Result<(), BoostPriorityError>;
+
+    /// Deactivate [Priority Boost].
+    ///
+    /// Returns [`BadContext`] if Priority Boost is already inactive, the
+    /// calling context is not a task context, or CPU Lock is active.
+    ///
+    /// [Priority Boost]: crate#system-states
+    /// [`BadContext`]: CpuLockError::BadContext
+    ///
+    /// # Safety
+    ///
+    /// Priority Boost is useful for creating a critical section. By making this
+    /// method `unsafe`, safe code is prevented from interfering with a critical
+    /// section.
+    unsafe fn unboost_priority() -> Result<(), BoostPriorityError>;
+
+    /// Return a flag indicating whether [Priority Boost] is currently active.
+    ///
+    /// [Priority Boost]: crate#system-states
+    fn is_priority_boost_active() -> bool;
+
     /// Terminate the current task, putting it into a Dormant state.
     ///
     /// The kernel (to be precise, the port) makes an implicit call to this
@@ -106,6 +140,18 @@ impl<T: Port + KernelCfg2 + 'static> Kernel for T {
         Self::is_cpu_lock_active()
     }
 
+    fn boost_priority() -> Result<(), BoostPriorityError> {
+        state::boost_priority::<Self>()
+    }
+
+    unsafe fn unboost_priority() -> Result<(), BoostPriorityError> {
+        state::unboost_priority::<Self>()
+    }
+
+    fn is_priority_boost_active() -> bool {
+        Self::state().priority_boost.load(Ordering::Relaxed)
+    }
+
     unsafe fn exit_task() -> Result<!, ExitTaskError> {
         // Safety: Just forwarding the function call
         unsafe { exit_current_task::<Self>() }
@@ -399,6 +445,9 @@ pub struct State<
     /// Invariant: `task_ready_bitmap[i].first.is_some() ==
     ///  task_ready_queue.get(i)`
     task_ready_queue: utils::CpuLockCell<System, TaskReadyQueue>,
+
+    /// `true` if Priority Boost is active.
+    priority_boost: AtomicBool,
 }
 
 impl<
@@ -413,6 +462,7 @@ impl<
         running_task: AtomicRef::new(None),
         task_ready_bitmap: Init::INIT,
         task_ready_queue: Init::INIT,
+        priority_boost: AtomicBool::new(false),
     };
 }
 
@@ -429,6 +479,7 @@ impl<
             .field("running_task", &self.running_task)
             .field("task_ready_bitmap", &self.task_ready_bitmap)
             .field("task_ready_queue", &self.task_ready_queue)
+            .field("priority_boost", &self.priority_boost)
             .finish()
     }
 }

src/constance/src/kernel/error.rs

@@ -215,6 +215,19 @@ define_error! {
     }
 }
 
+define_error! {
+    /// Error type for [`Kernel::boost_priority`] and
+    /// [`Kernel::unboost_priority`].
+    ///
+    /// [`Kernel::boost_priority`]: super::Kernel::boost_priority
+    /// [`Kernel::unboost_priority`]: super::Kernel::unboost_priority
+    pub enum BoostPriorityError: BadContextError {
+        /// Priority Boost is already active or inactive, the current
+        /// context is not a task context, or CPU Lock is active.
+        BadContext,
+    }
+}
+
 define_error! {
     /// Error type for wait operations such as [`EventGroup::wait`].
     ///

src/constance/src/kernel/state.rs

@@ -1,11 +1,45 @@
-use super::{BadContextError, Kernel};
+use core::sync::atomic::Ordering;
+
+use super::{task, utils, BadContextError, BoostPriorityError, Kernel};
 
 /// If the current context is not waitable, return `Err(BadContext)`.
 pub(super) fn expect_waitable_context<System: Kernel>() -> Result<(), BadContextError> {
-    if System::is_interrupt_context() {
+    if System::is_interrupt_context() || System::is_priority_boost_active() {
         Err(BadContextError::BadContext)
     } else {
-        // TODO: priority boost
+        Ok(())
+    }
+}
+
+/// Implements `Kernel::boost_priority`.
+pub(super) fn boost_priority<System: Kernel>() -> Result<(), BoostPriorityError> {
+    if System::is_cpu_lock_active()
+        || System::is_interrupt_context()
+        || System::is_priority_boost_active()
+    {
+        Err(BoostPriorityError::BadContext)
+    } else {
+        System::state()
+            .priority_boost
+            .store(true, Ordering::Relaxed);
+        Ok(())
+    }
+}
+
+/// Implements `Kernel::unboost_priority`.
+pub(super) fn unboost_priority<System: Kernel>() -> Result<(), BoostPriorityError> {
+    if System::is_interrupt_context() || !System::is_priority_boost_active() {
+        Err(BoostPriorityError::BadContext)
+    } else {
+        // Acquire CPU Lock after checking other states so that
+        // `drop_in_place(&mut lock)` doesn't get emitted twice
+        let lock = utils::lock_cpu()?;
+        System::state()
+            .priority_boost
+            .store(false, Ordering::Relaxed);
+
+        // Check pending preemption
+        task::unlock_cpu_and_check_preemption::<System>(lock);
         Ok(())
     }
 }

src/constance/src/kernel/task.rs

@@ -357,6 +357,11 @@ pub(super) unsafe fn exit_current_task<System: Kernel>() -> Result<!, ExitTaskEr
         utils::assume_cpu_lock::<System>()
     };
 
+    // If Priority Boost is active, deacrivate it.
+    System::state()
+        .priority_boost
+        .store(false, Ordering::Release);
+
     // Transition the current task to Dormant
     let running_task = System::state().running_task().unwrap();
     assert_eq!(*running_task.st.read(&*lock), TaskSt::Running);
@@ -482,6 +487,16 @@ pub(super) unsafe fn make_ready<System: Kernel>(
 /// System services that transition a task into a Ready state should call
 /// this before returning to the caller.
 pub(super) fn unlock_cpu_and_check_preemption<System: Kernel>(lock: utils::CpuLockGuard<System>) {
+    // If Priority Boost is active, treat the currently running task as the
+    // highest-priority task.
+    if System::is_priority_boost_active() {
+        debug_assert_eq!(
+            *System::state().running_task().unwrap().st.read(&*lock),
+            TaskSt::Running
+        );
+        return;
+    }
+
     let prev_task_priority = if let Some(running_task) = System::state().running_task() {
         running_task.priority.to_usize().unwrap()
     } else {
@@ -508,6 +523,17 @@ pub(super) fn unlock_cpu_and_check_preemption<System: Kernel>(lock: utils::CpuLo
 pub(super) fn choose_next_running_task<System: Kernel>(
     mut lock: utils::CpuLockGuardBorrowMut<System>,
 ) {
+    // If Priority Boost is active, treat the currently running task as the
+    // highest-priority task.
+    if System::is_priority_boost_active() {
+        // Blocking system calls aren't allowed when Priority Boost is active
+        debug_assert_eq!(
+            *System::state().running_task().unwrap().st.read(&*lock),
+            TaskSt::Running
+        );
+        return;
+    }
+
     // The priority of `running_task`
     let prev_running_task = System::state().running_task();
     let prev_task_priority = if let Some(running_task) = prev_running_task {

src/constance/src/lib.md

@@ -139,16 +139,13 @@ A system can be in some of the system states described in this section at any po
 
 Like a lock guard of a mutex, CPU Lock can be thought of as something to be “owned” by a current thread. This conception allows it to be seamlessly integrated with Rust's vocabulary and mental model around the ownership model.
 
-**Priority Boost** temporarily raises the effective priority of the current task to higher than any values possible in normal circumstances. Priority Boost can only be activated or deactivated in a task context. Potentially blocking system services are disallowed when Priority Boost is active, and will return [`BadContext`].
+**Priority Boost** temporarily raises the effective priority of the current task to higher than any values possible in normal circumstances. Priority Boost can only be activated or deactivated in a task context. Potentially blocking system services are disallowed when Priority Boost is active, and will return [`BadContext`]. Application code can use [`boost_priority`] to activate Priority Boost.
 
+[`boost_priority`]: crate::kernel::Kernel::boost_priority
 [`BadContext`]: crate::kernel::ResultCode::BadContext
 
 <div class="admonition-follows"></div>
 
-> **To be implemented:** Supporting priority boost
-
-<div class="admonition-follows"></div>
-
 > **Relation to Other Specifications:** Inspired from [the μITRON4.0 specification](http://www.ertl.jp/ITRON/SPEC/mitron4-e.html). CPU Lock and Priority Boost correspond to a CPU locked state and a dispatching state from μITRON4.0, respectively. In contrast to this specification, both concepts are denoted by proper nouns in the Constance RTOS. This means phrases like “when the CPU is locked” are not allowed.
 >
 > CPU Lock corresponds to `SuspendOSInterrupts` and `ResumeOSInterrupts` from the OSEK/VDX specification.

src/constance_test_suite/src/kernel_tests/priority_boost.rs

@@ -0,0 +1,74 @@
+//! Activates and deactivates Priority Boost.
+use constance::{kernel::Task, prelude::*};
+
+use super::Driver;
+
+#[derive(Debug)]
+pub struct App<System> {
+    task: Task<System>,
+}
+
+impl<System: Kernel> App<System> {
+    constance::configure! {
+        pub const fn new<D: Driver<Self>>(_: &mut CfgBuilder<System>) -> Self {
+            let task = new! { Task<_>, start = task_body::<System, D>, priority = 0, active = true };
+
+            App { task }
+        }
+    }
+}
+
+fn task_body<System: Kernel, D: Driver<App<System>>>(_: usize) {
+    assert!(!System::is_priority_boost_active());
+
+    // Activate Priority Boost
+    System::boost_priority().unwrap();
+
+    // Can't do it again because it's already acquired
+    assert!(System::is_priority_boost_active());
+    assert_eq!(
+        System::boost_priority(),
+        Err(constance::kernel::BoostPriorityError::BadContext),
+    );
+    assert!(System::is_priority_boost_active());
+
+    // -------------------------------------------------------------------
+
+    // Try acquiring CPU Lock while Priority Boost being active
+    System::acquire_cpu_lock().unwrap();
+    assert!(System::has_cpu_lock());
+    unsafe { System::release_cpu_lock() }.unwrap();
+
+    // Blocking operations are disallowed
+    assert_eq!(
+        System::park(),
+        Err(constance::kernel::ParkError::BadContext),
+    );
+
+    // -------------------------------------------------------------------
+
+    // Deactivate Priority Boost
+    unsafe { System::unboost_priority() }.unwrap();
+
+    // Can't do it again because it's already deactivated
+    assert!(!System::is_priority_boost_active());
+    assert_eq!(
+        unsafe { System::unboost_priority() },
+        Err(constance::kernel::BoostPriorityError::BadContext),
+    );
+    assert!(!System::is_priority_boost_active());
+
+    // -------------------------------------------------------------------
+
+    // Acquire CPU Lock, and see that Priority Boost doesn't activate in it
+    System::acquire_cpu_lock().unwrap();
+    assert_eq!(
+        System::boost_priority(),
+        Err(constance::kernel::BoostPriorityError::BadContext),
+    );
+    unsafe { System::release_cpu_lock() }.unwrap();
+
+    assert!(!System::is_priority_boost_active());
+
+    D::success();
+}

src/constance_test_suite/src/kernel_tests/task_park_priority_boost.rs

@@ -0,0 +1,57 @@
+//! Sequence the execution of tasks using the parking mechanism. Priority Boost
+//! is used to temporarily suppress preemption.
+use constance::{
+    kernel::{Hunk, Task},
+    prelude::*,
+};
+
+use super::Driver;
+use crate::utils::SeqTracker;
+
+pub struct App<System> {
+    task2: Task<System>,
+    seq: Hunk<System, SeqTracker>,
+}
+
+impl<System: Kernel> App<System> {
+    constance::configure! {
+        pub const fn new<D: Driver<Self>>(_: &mut CfgBuilder<System>) -> Self {
+            new! { Task<_>, start = task1_body::<System, D>, priority = 2, active = true };
+            let task2 = new! { Task<_>, start = task2_body::<System, D>, priority = 1, active = true };
+
+            let seq = new! { Hunk<_, SeqTracker> };
+
+            App { task2, seq }
+        }
+    }
+}
+
+fn task1_body<System: Kernel, D: Driver<App<System>>>(_: usize) {
+    D::app().seq.expect_and_replace(1, 2);
+
+    // Activate Boost Priority
+    System::boost_priority().unwrap();
+
+    // Boost Priority is active, so `task2` can't preempt yet even though it
+    // has a higher priority
+    D::app().task2.unpark_exact().unwrap();
+
+    D::app().seq.expect_and_replace(2, 3);
+
+    // Deactive Boost Priority. Now `task2` can preempt and run to completion
+    unsafe { System::unboost_priority() }.unwrap();
+
+    D::app().seq.expect_and_replace(4, 5);
+
+    D::success();
+}
+
+fn task2_body<System: Kernel, D: Driver<App<System>>>(_: usize) {
+    D::app().seq.expect_and_replace(0, 1);
+
+    System::park().unwrap(); // blocks, switching to `task1`
+
+    D::app().seq.expect_and_replace(3, 4);
+
+    // `task2` is done, now go back to `task1`
+}

src/constance_test_suite/src/kernel_tests/task_priority_boost_reset.rs

@@ -0,0 +1,32 @@
+//! Checks that Boost Priority is deactivated when a task completes.
+use constance::{kernel::Task, prelude::*};
+
+use super::Driver;
+
+pub struct App<System> {
+    task2: Task<System>,
+}
+
+impl<System: Kernel> App<System> {
+    constance::configure! {
+        pub const fn new<D: Driver<Self>>(_: &mut CfgBuilder<System>) -> Self {
+            new! { Task<_>, start = task1_body::<System, D>, priority = 2, active = true };
+            let task2 = new! { Task<_>, start = task2_body::<System, D>, priority = 1 };
+
+            App { task2 }
+        }
+    }
+}
+
+fn task1_body<System: Kernel, D: Driver<App<System>>>(_: usize) {
+    // Activate `task2` twice
+    D::app().task2.activate().unwrap();
+    D::app().task2.activate().unwrap();
+    D::success();
+}
+
+fn task2_body<System: Kernel, D: Driver<App<System>>>(_: usize) {
+    // Activate Priority Boost. This should succeed in both runs because
+    // it's automatically deactivated on each run.
+    System::boost_priority().unwrap();
+}