Tweak driver to better model FreeRTOS APIs (#4076)

Author: bugadani

esp-preempt/src/lib.rs

@@ -321,6 +321,10 @@ impl esp_radio_preempt_driver::Scheduler for Scheduler {
         timer::yield_task()
     }
 
+    fn yield_task_from_isr(&self) {
+        self.yield_task();
+    }
+
     fn max_task_priority(&self) -> u32 {
         255
     }

esp-preempt/src/queue.rs

@@ -187,7 +187,11 @@ impl QueueImplementation for Queue {
         unsafe { queue.send_to_back(item, timeout_us) }
     }
 
-    unsafe fn try_send_to_back(queue: QueuePtr, item: *const u8) -> bool {
+    unsafe fn try_send_to_back_from_isr(
+        queue: QueuePtr,
+        item: *const u8,
+        _higher_prio_task_waken: Option<&mut bool>,
+    ) -> bool {
         let queue = unsafe { Queue::from_ptr(queue) };
 
         unsafe { queue.try_send_to_back(item) }
@@ -199,7 +203,11 @@ impl QueueImplementation for Queue {
         unsafe { queue.receive(item, timeout_us) }
     }
 
-    unsafe fn try_receive(queue: QueuePtr, item: *mut u8) -> bool {
+    unsafe fn try_receive_from_isr(
+        queue: QueuePtr,
+        item: *mut u8,
+        _higher_prio_task_waken: Option<&mut bool>,
+    ) -> bool {
         let queue = unsafe { Queue::from_ptr(queue) };
 
         unsafe { queue.try_receive(item) }

esp-preempt/src/semaphore.rs

@@ -131,6 +131,14 @@ impl SemaphoreImplementation for Semaphore {
 
         semaphore.try_take()
     }
+
+    unsafe fn try_give_from_isr(semaphore: SemaphorePtr, _hptw: Option<&mut bool>) -> bool {
+        unsafe { <Self as SemaphoreImplementation>::give(semaphore) }
+    }
+
+    unsafe fn try_take_from_isr(semaphore: SemaphorePtr, _hptw: Option<&mut bool>) -> bool {
+        unsafe { <Self as SemaphoreImplementation>::try_take(semaphore) }
+    }
 }
 
 register_semaphore_implementation!(Semaphore);

esp-preempt/src/timer_queue.rs

@@ -243,8 +243,23 @@ impl Timer {
 }
 
 impl TimerImplementation for Timer {
-    fn create(callback: Box<dyn FnMut() + Send>) -> TimerPtr {
-        let timer = Box::new(Timer::new(callback));
+    fn create(func: unsafe extern "C" fn(*mut c_void), data: *mut c_void) -> TimerPtr {
+        // TODO: get rid of the inner box (or its heap allocation) somehow
+        struct CCallback {
+            func: unsafe extern "C" fn(*mut c_void),
+            data: *mut c_void,
+        }
+        unsafe impl Send for CCallback {}
+
+        impl CCallback {
+            unsafe fn call(&mut self) {
+                unsafe { (self.func)(self.data) }
+            }
+        }
+
+        let mut callback = CCallback { func, data };
+
+        let timer = Box::new(Timer::new(Box::new(move || unsafe { callback.call() })));
         NonNull::from(Box::leak(timer)).cast()
     }
 

esp-radio-preempt-driver/src/lib.rs

@@ -9,6 +9,15 @@
 //!
 //! ## Implementing a scheduler driver
 //!
+//! This crate abstracts the capabilities of FreeRTOS. The scheduler must implement the following
+//! capabilities:
+//!
+//! - A preemptive task scheduler
+//! - Mutexes
+//! - Semaphores
+//! - Queues
+//! - Timers (functions that are executed at a specific time)
+//!
 //! In order to hook up a scheduler, implement the `Scheduler` trait for a struct, and register it
 //! using the `scheduler_impl!()` macro. Only one scheduler can be registered in a firmware.
 //!
@@ -45,6 +54,7 @@ unsafe extern "Rust" {
     fn esp_preempt_enable();
     fn esp_preempt_disable();
     fn esp_preempt_yield_task();
+    fn esp_preempt_yield_task_from_isr();
     fn esp_preempt_current_task() -> *mut c_void;
     fn esp_preempt_max_task_priority() -> u32;
     fn esp_preempt_task_create(
@@ -93,6 +103,12 @@ macro_rules! scheduler_impl {
             <$t as $crate::Scheduler>::yield_task(&$name)
         }
 
+        #[unsafe(no_mangle)]
+        #[inline]
+        fn esp_preempt_yield_task_from_isr() {
+            <$t as $crate::Scheduler>::yield_task_from_isr(&$name)
+        }
+
         #[unsafe(no_mangle)]
         #[inline]
         fn esp_preempt_current_task() -> *mut c_void {
@@ -165,9 +181,12 @@ pub trait Scheduler: Send + Sync + 'static {
     /// This function is called by `esp-radio` to stop the task scheduler.
     fn disable(&self);
 
-    /// This function is called by `esp_radio::init` to yield control to another task.
+    /// This function is called by `esp_radio` to yield control to another task.
     fn yield_task(&self);
 
+    /// This function is called by `esp_radio` to yield control to another task.
+    fn yield_task_from_isr(&self);
+
     /// This function is called by `esp_radio::init` to retrieve a pointer to the current task.
     fn current_task(&self) -> *mut c_void;
 
@@ -236,6 +255,12 @@ pub fn yield_task() {
     unsafe { esp_preempt_yield_task() }
 }
 
+/// Yields control to another task for an interrupt.
+#[inline]
+pub fn yield_task_from_isr() {
+    unsafe { esp_preempt_yield_task_from_isr() }
+}
+
 /// Returns a pointer to the current task.
 #[inline]
 pub fn current_task() -> *mut c_void {

esp-radio-preempt-driver/src/queue.rs

@@ -19,9 +19,17 @@ unsafe extern "Rust" {
         item: *const u8,
         timeout_us: Option<u32>,
     ) -> bool;
-    fn esp_preempt_queue_try_send_to_back(queue: QueuePtr, item: *const u8) -> bool;
+    fn esp_preempt_queue_try_send_to_back_from_isr(
+        queue: QueuePtr,
+        item: *const u8,
+        higher_prio_task_waken: Option<&mut bool>,
+    ) -> bool;
     fn esp_preempt_queue_receive(queue: QueuePtr, item: *mut u8, timeout_us: Option<u32>) -> bool;
-    fn esp_preempt_queue_try_receive(queue: QueuePtr, item: *mut u8) -> bool;
+    fn esp_preempt_queue_try_receive_from_isr(
+        queue: QueuePtr,
+        item: *mut u8,
+        higher_prio_task_waken: Option<&mut bool>,
+    ) -> bool;
     fn esp_preempt_queue_remove(queue: QueuePtr, item: *const u8);
     fn esp_preempt_queue_messages_waiting(queue: QueuePtr) -> usize;
 }
@@ -67,11 +75,18 @@ pub trait QueueImplementation {
     ///
     /// If the queue is full, this function will immediately return `false`.
     ///
+    /// The `higher_prio_task_waken` parameter is an optional mutable reference to a boolean flag.
+    /// If the flag is `Some`, the implementation may set it to `true` to request a context switch.
+    ///
     /// # Safety
     ///
     /// The caller must ensure that `item` can be dereferenced and points to an allocation of
     /// a size equal to the queue's item size.
-    unsafe fn try_send_to_back(queue: QueuePtr, item: *const u8) -> bool;
+    unsafe fn try_send_to_back_from_isr(
+        queue: QueuePtr,
+        item: *const u8,
+        higher_prio_task_waken: Option<&mut bool>,
+    ) -> bool;
 
     /// Dequeues an item from the queue.
     ///
@@ -90,13 +105,20 @@ pub trait QueueImplementation {
     ///
     /// If the queue is empty, this function will return `false` immediately.
     ///
+    /// The `higher_prio_task_waken` parameter is an optional mutable reference to a boolean flag.
+    /// If the flag is `Some`, the implementation may set it to `true` to request a context switch.
+    ///
     /// This function returns `true` if the item was successfully dequeued, `false` otherwise.
     ///
     /// # Safety
     ///
     /// The caller must ensure that `item` can be dereferenced and points to an allocation of
     /// a size equal to the queue's item size.
-    unsafe fn try_receive(queue: QueuePtr, item: *mut u8) -> bool;
+    unsafe fn try_receive_from_isr(
+        queue: QueuePtr,
+        item: *mut u8,
+        higher_prio_task_waken: Option<&mut bool>,
+    ) -> bool;
 
     /// Removes an item from the queue.
     ///
@@ -151,8 +173,18 @@ macro_rules! register_queue_implementation {
 
         #[unsafe(no_mangle)]
         #[inline]
-        fn esp_preempt_queue_try_send_to_back(queue: QueuePtr, item: *const u8) -> bool {
-            unsafe { <$t as $crate::queue::QueueImplementation>::try_send_to_back(queue, item) }
+        fn esp_preempt_queue_try_send_to_back_from_isr(
+            queue: QueuePtr,
+            item: *const u8,
+            higher_prio_task_waken: Option<&mut bool>,
+        ) -> bool {
+            unsafe {
+                <$t as $crate::queue::QueueImplementation>::try_send_to_back_from_isr(
+                    queue,
+                    item,
+                    higher_prio_task_waken,
+                )
+            }
         }
 
         #[unsafe(no_mangle)]
@@ -167,8 +199,18 @@ macro_rules! register_queue_implementation {
 
         #[unsafe(no_mangle)]
         #[inline]
-        fn esp_preempt_queue_try_receive(queue: QueuePtr, item: *mut u8) -> bool {
-            unsafe { <$t as $crate::queue::QueueImplementation>::try_receive(queue, item) }
+        fn esp_preempt_queue_try_receive_from_isr(
+            queue: QueuePtr,
+            item: *mut u8,
+            higher_prio_task_waken: Option<&mut bool>,
+        ) -> bool {
+            unsafe {
+                <$t as $crate::queue::QueueImplementation>::try_receive_from_isr(
+                    queue,
+                    item,
+                    higher_prio_task_waken,
+                )
+            }
         }
 
         #[unsafe(no_mangle)]
@@ -256,12 +298,21 @@ impl QueueHandle {
     ///
     /// If the queue is full, this function will immediately return `false`.
     ///
+    /// If a higher priority task is woken up by this operation, the `higher_prio_task_waken` flag
+    /// is set to `true`.
+    ///
     /// # Safety
     ///
     /// The caller must ensure that `item` can be dereferenced and points to an allocation of
     /// a size equal to the queue's item size.
-    pub unsafe fn try_send_to_back(&self, item: *const u8) -> bool {
-        unsafe { esp_preempt_queue_try_send_to_back(self.0, item) }
+    pub unsafe fn try_send_to_back_from_isr(
+        &self,
+        item: *const u8,
+        higher_priority_task_waken: Option<&mut bool>,
+    ) -> bool {
+        unsafe {
+            esp_preempt_queue_try_send_to_back_from_isr(self.0, item, higher_priority_task_waken)
+        }
     }
 
     /// Dequeues an item from the queue.
@@ -285,12 +336,19 @@ impl QueueHandle {
     ///
     /// This function returns `true` if the item was successfully dequeued, `false` otherwise.
     ///
+    /// If a higher priority task is woken up by this operation, the `higher_prio_task_waken` flag
+    /// is set to `true`.
+    ///
     /// # Safety
     ///
     /// The caller must ensure that `item` can be dereferenced and points to an allocation of
     /// a size equal to the queue's item size.
-    pub unsafe fn try_receive(&self, item: *mut u8) -> bool {
-        unsafe { esp_preempt_queue_try_receive(self.0, item) }
+    pub unsafe fn try_receive_from_isr(
+        &self,
+        item: *mut u8,
+        higher_priority_task_waken: Option<&mut bool>,
+    ) -> bool {
+        unsafe { esp_preempt_queue_try_receive_from_isr(self.0, item, higher_priority_task_waken) }
     }
 
     /// Removes an item from the queue.