zephyr: Add async 'wait_for_high' and 'wait_for_low' to gpio

Implement a general async `wait_for_high` and `wait_for_low` to the
GpioPin interface.  The waiting is supported at the level of the gpio
driver. Each Gpio instance has an array of `AtomiWaker` to hold the
wakers that are waiting on the pins, as well as the callback handler
from using the pins in interrupt mode in Zephyr.

Although most of the examples of gpios in Zephyr use irq-gpios instead
of gpios in the custom properties, there isn't anything that happens
when this is done, and regular 'gpios' properties work just fine with
interrupts.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

zephyr-sys/wrapper.h

@@ -56,3 +56,8 @@ const uintptr_t ZR_STACK_RESERVED = K_KERNEL_STACK_RESERVED;
 const uint32_t ZR_POLL_TYPE_SEM_AVAILABLE = K_POLL_TYPE_SEM_AVAILABLE;
 const uint32_t ZR_POLL_TYPE_SIGNAL = K_POLL_TYPE_SIGNAL;
 const uint32_t ZR_POLL_TYPE_DATA_AVAILABLE = K_POLL_TYPE_DATA_AVAILABLE;
+
+#ifdef CONFIG_GPIO_ENABLE_DISABLE_INTERRUPT
+const uint32_t ZR_GPIO_INT_MODE_DISABLE_ONLY = GPIO_INT_MODE_DISABLE_ONLY;
+const uint32_t ZR_GPIO_INT_MODE_ENABLE_ONLY = GPIO_INT_MODE_ENABLE_ONLY;
+#endif

zephyr/Cargo.toml

@@ -81,3 +81,8 @@ time-driver = [
 executor-zephyr = [
   "dep:embassy-executor",
 ]
+
+# Enables async support in various drivers.
+async-drivers = [
+  "dep:embassy-sync",
+]

zephyr/src/device/gpio.rs

@@ -9,9 +9,242 @@
 
 use core::ffi::c_int;
 
-use super::Unique;
+use super::{NoStatic, Unique};
 use crate::raw;
 
+#[cfg(feature = "async-drivers")]
+mod async_io {
+    //! Async operations for gpio drivers.
+    //!
+    //! For now, we make an assumption that a gpio controller can contain up to 32 gpios, which is
+    //! the largest number currently used, although this might change with 64-bit targest in the
+    //! future.
+
+    use core::{
+        cell::UnsafeCell,
+        future::Future,
+        mem,
+        sync::atomic::Ordering,
+        task::{Poll, Waker},
+    };
+
+    use embassy_sync::waitqueue::AtomicWaker;
+    use zephyr_sys::{
+        device, gpio_add_callback, gpio_callback, gpio_init_callback, gpio_pin_interrupt_configure,
+        gpio_pin_interrupt_configure_dt, gpio_port_pins_t, GPIO_INT_LEVEL_HIGH, GPIO_INT_LEVEL_LOW,
+        ZR_GPIO_INT_MODE_DISABLE_ONLY,
+    };
+
+    use crate::sync::atomic::{AtomicBool, AtomicU32};
+
+    use super::{GpioPin, GpioToken};
+
+    pub(crate) struct GpioStatic {
+        /// The wakers for each of the gpios.
+        wakers: [AtomicWaker; 32],
+        /// Indicates when an interrupt has fired.  Used to definitively indicate the event has
+        /// happened, so we can wake.
+        fired: AtomicU32,
+        /// Have we been initialized?
+        installed: AtomicBool,
+        /// The data for the callback itself.
+        callback: UnsafeCell<gpio_callback>,
+    }
+
+    unsafe impl Sync for GpioStatic {}
+
+    impl GpioStatic {
+        pub(crate) const fn new() -> Self {
+            Self {
+                wakers: [const { AtomicWaker::new() }; 32],
+                fired: AtomicU32::new(0),
+                installed: AtomicBool::new(false),
+                // SAFETY: `installed` will tell us this need to be installed.
+                callback: unsafe { mem::zeroed() },
+            }
+        }
+
+        /// Ensure that the callback has been installed.
+        pub(super) fn fast_install(&self, port: *const device) {
+            if !self.installed.load(Ordering::Acquire) {
+                self.install(port);
+            }
+        }
+
+        fn install(&self, port: *const device) {
+            critical_section::with(|_| {
+                if !self.installed.load(Ordering::Acquire) {
+                    let cb = self.callback.get();
+                    // SAFETY: We're in a critical section, so there should be no concurrent use,
+                    // and there should not be any calls from the driver.
+                    unsafe {
+                        gpio_init_callback(cb, Some(Self::callback_handler), 0);
+                        gpio_add_callback(port, cb);
+                    }
+
+                    self.installed.store(true, Ordering::Release);
+                }
+            })
+        }
+
+        /// Register (replacing) a given callback.
+        pub(super) fn register(&self, pin: u8, waker: &Waker) {
+            self.wakers[pin as usize].register(waker);
+
+            // SAFETY: Inherently unsafe, due to how the Zephyr API is defined.
+            // The API appears to assume coherent memory, which although untrue, probably is "close
+            // enough" on the supported targets.
+            // The main issue is to ensure that any race is resolved in the direction of getting the
+            // callback more than needed, rather than missing.  In the context here, ensure the
+            // waker is registered (which does use an atomic), before enabling the pin in the
+            // callback structure.
+            //
+            // If it seems that wakes are getting missed, it might be the case that this needs some
+            // kind of memory barrier.
+            let cb = self.callback.get();
+            unsafe {
+                (*cb).pin_mask |= 1 << pin;
+            }
+        }
+
+        extern "C" fn callback_handler(
+            port: *const device,
+            cb: *mut gpio_callback,
+            mut pins: gpio_port_pins_t,
+        ) {
+            let data = unsafe {
+                cb.cast::<u8>()
+                    .sub(mem::offset_of!(Self, callback))
+                    .cast::<Self>()
+            };
+
+            // For each pin we are informed of.
+            while pins > 0 {
+                let pin = pins.trailing_zeros();
+
+                pins &= !(1 << pin);
+
+                // SAFETY: Handling this correctly is a bit tricky, especially with the
+                // un-coordinated 'pin-mask' value.
+                //
+                // For level-triggered interrupts, not disabling this will result in an interrupt
+                // storm.
+                unsafe {
+                    // Disable the actual interrupt from the controller.
+                    gpio_pin_interrupt_configure(port, pin as u8, ZR_GPIO_INT_MODE_DISABLE_ONLY);
+
+                    // Remove the callback bit.  Unclear if this is actually useful.
+                    (*cb).pin_mask &= !(1 << pin);
+
+                    // Indicate that we have fired.
+                    // AcqRel is sufficient for ordering across a single atomic.
+                    (*data).fired.fetch_or(1 << pin, Ordering::AcqRel);
+
+                    // After the interrupt is off, wake the handler.
+                    (*data).wakers[pin as usize].wake();
+                }
+            }
+        }
+
+        /// Check if we have fired for a given pin.  Clears the status.
+        pub(crate) fn has_fired(&self, pin: u8) -> bool {
+            let value = self.fired.fetch_and(!(1 << pin), Ordering::AcqRel);
+            value & (1 << pin) != 0
+        }
+    }
+
+    impl GpioPin {
+        /// Asynchronously wait for a gpio pin to become high.
+        ///
+        /// # Safety
+        ///
+        /// The `_token` enforces single use of gpios.  Note that this makes it impossible to wait for
+        /// more than one GPIO.
+        ///
+        pub unsafe fn wait_for_high(
+            &mut self,
+            _token: &mut GpioToken,
+        ) -> impl Future<Output = ()> + use<'_> {
+            GpioWait::new(self, 1)
+        }
+
+        /// Asynchronously wait for a gpio pin to become low.
+        ///
+        /// # Safety
+        ///
+        /// The `_token` enforces single use of gpios.  Note that this makes it impossible to wait
+        /// for more than one GPIO.
+        pub unsafe fn wait_for_low(
+            &mut self,
+            _token: &mut GpioToken,
+        ) -> impl Future<Output = ()> + use<'_> {
+            GpioWait::new(self, 0)
+        }
+    }
+
+    /// A future that waits for a gpio to become high.
+    pub struct GpioWait<'a> {
+        pin: &'a mut GpioPin,
+        level: u8,
+    }
+
+    impl<'a> GpioWait<'a> {
+        fn new(pin: &'a mut GpioPin, level: u8) -> Self {
+            Self { pin, level }
+        }
+    }
+
+    impl<'a> Future for GpioWait<'a> {
+        type Output = ();
+
+        fn poll(
+            self: core::pin::Pin<&mut Self>,
+            cx: &mut core::task::Context<'_>,
+        ) -> core::task::Poll<Self::Output> {
+            self.pin.data.fast_install(self.pin.pin.port);
+
+            // Early detection of the event.  Also clears.
+            // This should be non-racy as long as only one task at a time waits on the gpio.
+            if self.pin.data.has_fired(self.pin.pin.pin) {
+                return Poll::Ready(());
+            }
+
+            self.pin.data.register(self.pin.pin.pin, cx.waker());
+
+            let mode = match self.level {
+                0 => GPIO_INT_LEVEL_LOW,
+                1 => GPIO_INT_LEVEL_HIGH,
+                _ => unreachable!(),
+            };
+
+            unsafe {
+                gpio_pin_interrupt_configure_dt(&self.pin.pin, mode);
+
+                // Before sleeping, check if it fired, to avoid having to pend if it already
+                // happened.
+                if self.pin.data.has_fired(self.pin.pin.pin) {
+                    return Poll::Ready(());
+                }
+            }
+
+            Poll::Pending
+        }
+    }
+}
+
+#[cfg(not(feature = "async-drivers"))]
+mod async_io {
+    pub(crate) struct GpioStatic;
+
+    impl GpioStatic {
+        pub(crate) const fn new() -> Self {
+            Self
+        }
+    }
+}
+
+pub(crate) use async_io::*;
+
 /// Global instance to help make gpio in Rust slightly safer.
 ///
 /// # Safety
@@ -47,6 +280,8 @@ pub struct Gpio {
     /// The underlying device itself.
     #[allow(dead_code)]
     pub(crate) device: *const raw::device,
+    /// Our associated data, used for callbacks.
+    pub(crate) data: &'static GpioStatic,
 }
 
 // SAFETY: Gpio's can be shared with other threads.  Safety is maintained by the Token.
@@ -57,11 +292,15 @@ impl Gpio {
     ///
     /// TODO: Guarantee single instancing.
     #[allow(dead_code)]
-    pub(crate) unsafe fn new(unique: &Unique, device: *const raw::device) -> Option<Gpio> {
+    pub(crate) unsafe fn new(
+        unique: &Unique,
+        data: &'static GpioStatic,
+        device: *const raw::device,
+    ) -> Option<Gpio> {
         if !unique.once() {
             return None;
         }
-        Some(Gpio { device })
+        Some(Gpio { device, data })
     }
 
     /// Verify that the device is ready for use.  At a minimum, this means the device has been
@@ -79,6 +318,7 @@ impl Gpio {
 #[allow(dead_code)]
 pub struct GpioPin {
     pub(crate) pin: raw::gpio_dt_spec,
+    pub(crate) data: &'static GpioStatic,
 }
 
 // SAFETY: GpioPin's can be shared with other threads.  Safety is maintained by the Token.
@@ -89,7 +329,9 @@ impl GpioPin {
     #[allow(dead_code)]
     pub(crate) unsafe fn new(
         unique: &Unique,
+        _static: &NoStatic,
         device: *const raw::device,
+        device_static: &'static GpioStatic,
         pin: u32,
         dt_flags: u32,
     ) -> Option<GpioPin> {
@@ -102,6 +344,7 @@ impl GpioPin {
                 pin: pin as raw::gpio_pin_t,
                 dt_flags: dt_flags as raw::gpio_dt_flags_t,
             },
+            data: device_static,
         })
     }
 
@@ -115,6 +358,7 @@ impl GpioPin {
     pub fn get_gpio(&self) -> Gpio {
         Gpio {
             device: self.pin.port,
+            data: self.data,
         }
     }