Merge #455

455: simple_playback api from nrf sdk r=Dirbaio a=jacobrosenthal

Port of the nrf_drv_pwm_simple_playback call from the nordic sdk that allows you to set up a sequence to play across leds with no interaction necessary using the 'shorts' registers to trigger looping sequences



Co-authored-by: Jacob Rosenthal <[email protected]>

2 files changed, 392 insertions, 51 deletions

diff --git a/embassy-nrf/src/pwm.rs b/embassy-nrf/src/pwm.rs
index 5e996e882..08e9add0e 100644
--- a/embassy-nrf/src/pwm.rs
+++ b/embassy-nrf/src/pwm.rs
@@ -1,16 +1,299 @@
 #![macro_use]
 
-use core::cell::UnsafeCell;
 use core::marker::PhantomData;
 use core::sync::atomic::{compiler_fence, Ordering};
 use embassy::util::Unborrow;
 use embassy_hal_common::unborrow;
 
 use crate::gpio::sealed::Pin as _;
-use crate::gpio::OptionalPin as GpioOptionalPin;
+use crate::gpio::{AnyPin, OptionalPin as GpioOptionalPin};
 use crate::interrupt::Interrupt;
 use crate::pac;
+use crate::util::slice_in_ram_or;
 
+/// SimplePwm is the traditional pwm interface you're probably used to, allowing
+/// to simply set a duty cycle across up to four channels.
+pub struct SimplePwm<'d, T: Instance> {
+    phantom: PhantomData<&'d mut T>,
+    duty: [u16; 4],
+    ch0: Option<AnyPin>,
+    ch1: Option<AnyPin>,
+    ch2: Option<AnyPin>,
+    ch3: Option<AnyPin>,
+}
+
+/// SequencePwm allows you to offload the updating of a sequence of duty cycles
+/// to up to four channels, as well as repeat that sequence n times.
+pub struct SequencePwm<'d, T: Instance> {
+    phantom: PhantomData<&'d mut T>,
+    ch0: Option<AnyPin>,
+    ch1: Option<AnyPin>,
+    ch2: Option<AnyPin>,
+    ch3: Option<AnyPin>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[non_exhaustive]
+pub enum Error {
+    /// Max Sequence size is 32767
+    SequenceTooLong,
+    /// Min Sequence count is 1
+    SequenceTimesAtLeastOne,
+    /// EasyDMA can only read from data memory, read only buffers in flash will fail.
+    DMABufferNotInDataMemory,
+}
+
+impl<'d, T: Instance> SequencePwm<'d, T> {
+    /// Creates the interface to a `SequencePwm`.
+    ///
+    /// Must be started by calling `start`
+    ///
+    /// # Safety
+    ///
+    /// The returned API is safe unless you use `mem::forget` (or similar safe
+    /// mechanisms) on stack allocated buffers which which have been passed to
+    /// [`new()`](SequencePwm::new).
+    #[allow(unused_unsafe)]
+    pub fn new<'a>(
+        _pwm: impl Unborrow<Target = T> + 'd,
+        ch0: impl Unborrow<Target = impl GpioOptionalPin> + 'd,
+        ch1: impl Unborrow<Target = impl GpioOptionalPin> + 'd,
+        ch2: impl Unborrow<Target = impl GpioOptionalPin> + 'd,
+        ch3: impl Unborrow<Target = impl GpioOptionalPin> + 'd,
+        config: SequenceConfig,
+        sequence: &'a [u16],
+    ) -> Result<Self, Error> {
+        slice_in_ram_or(sequence, Error::DMABufferNotInDataMemory)?;
+
+        if sequence.len() > 32767 {
+            return Err(Error::SequenceTooLong);
+        }
+
+        unborrow!(ch0, ch1, ch2, ch3);
+
+        let r = T::regs();
+
+        if let Some(pin) = ch0.pin_mut() {
+            pin.set_low();
+            pin.conf().write(|w| w.dir().output());
+        }
+        if let Some(pin) = ch1.pin_mut() {
+            pin.set_low();
+            pin.conf().write(|w| w.dir().output());
+        }
+        if let Some(pin) = ch2.pin_mut() {
+            pin.set_low();
+            pin.conf().write(|w| w.dir().output());
+        }
+        if let Some(pin) = ch3.pin_mut() {
+            pin.set_low();
+            pin.conf().write(|w| w.dir().output());
+        }
+
+        // if NoPin provided writes disconnected (top bit 1) 0x80000000 else
+        // writes pin number ex 13 (0x0D) which is connected (top bit 0)
+        r.psel.out[0].write(|w| unsafe { w.bits(ch0.psel_bits()) });
+        r.psel.out[1].write(|w| unsafe { w.bits(ch1.psel_bits()) });
+        r.psel.out[2].write(|w| unsafe { w.bits(ch2.psel_bits()) });
+        r.psel.out[3].write(|w| unsafe { w.bits(ch3.psel_bits()) });
+
+        // Disable all interrupts
+        r.intenclr.write(|w| unsafe { w.bits(0xFFFF_FFFF) });
+        r.shorts.reset();
+
+        // Enable
+        r.enable.write(|w| w.enable().enabled());
+
+        r.seq0
+            .ptr
+            .write(|w| unsafe { w.bits(sequence.as_ptr() as u32) });
+        r.seq0
+            .cnt
+            .write(|w| unsafe { w.bits(sequence.len() as u32) });
+        r.seq0.refresh.write(|w| unsafe { w.bits(config.refresh) });
+        r.seq0
+            .enddelay
+            .write(|w| unsafe { w.bits(config.end_delay) });
+
+        r.seq1
+            .ptr
+            .write(|w| unsafe { w.bits(sequence.as_ptr() as u32) });
+        r.seq1
+            .cnt
+            .write(|w| unsafe { w.bits(sequence.len() as u32) });
+        r.seq1.refresh.write(|w| unsafe { w.bits(config.refresh) });
+        r.seq1
+            .enddelay
+            .write(|w| unsafe { w.bits(config.end_delay) });
+
+        r.decoder.write(|w| {
+            w.load().bits(config.sequence_load as u8);
+            w.mode().refresh_count()
+        });
+
+        r.mode.write(|w| match config.counter_mode {
+            CounterMode::UpAndDown => w.updown().up_and_down(),
+            CounterMode::Up => w.updown().up(),
+        });
+        r.prescaler
+            .write(|w| w.prescaler().bits(config.prescaler as u8));
+        r.countertop
+            .write(|w| unsafe { w.countertop().bits(config.top) });
+
+        Ok(Self {
+            phantom: PhantomData,
+            ch0: ch0.degrade_optional(),
+            ch1: ch1.degrade_optional(),
+            ch2: ch2.degrade_optional(),
+            ch3: ch3.degrade_optional(),
+        })
+    }
+
+    /// Start or restart playback
+    #[inline(always)]
+    pub fn start(&self, times: SequenceMode) -> Result<(), Error> {
+        if let SequenceMode::Times(0) = times {
+            return Err(Error::SequenceTimesAtLeastOne);
+        }
+        let r = T::regs();
+
+        self.stop();
+
+        r.enable.write(|w| w.enable().enabled());
+
+        // defensive before seqstart
+        compiler_fence(Ordering::SeqCst);
+
+        match times {
+            // just the one time, no loop count
+            SequenceMode::Times(1) => {
+                r.loop_.write(|w| w.cnt().disabled());
+                // tasks_seqstart() doesn't exist in all svds so write its bit instead
+                r.tasks_seqstart[0].write(|w| unsafe { w.bits(0x01) });
+            }
+            // loop count is how many times to play BOTH sequences
+            // 2 total  (1 x 2)
+            // 3 total, (2 x 2) - 1
+            SequenceMode::Times(n) => {
+                let odd = n & 1 == 1;
+                let times = if odd { (n / 2) + 1 } else { n / 2 };
+
+                r.loop_.write(|w| unsafe { w.cnt().bits(times) });
+
+                // we can subtract 1 by starting at seq1 instead of seq0
+                if odd {
+                    // tasks_seqstart() doesn't exist in all svds so write its bit instead
+                    r.tasks_seqstart[1].write(|w| unsafe { w.bits(0x01) });
+                } else {
+                    // tasks_seqstart() doesn't exist in all svds so write its bit instead
+                    r.tasks_seqstart[0].write(|w| unsafe { w.bits(0x01) });
+                }
+            }
+            // to play infinitely, repeat the sequence one time, then have loops done self trigger seq0 again
+            SequenceMode::Infinite => {
+                r.loop_.write(|w| unsafe { w.cnt().bits(0x1) });
+                r.shorts.write(|w| w.loopsdone_seqstart0().enabled());
+
+                // tasks_seqstart() doesn't exist in all svds so write its bit instead
+                r.tasks_seqstart[0].write(|w| unsafe { w.bits(0x01) });
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Stop playback.
+    #[inline(always)]
+    pub fn stop(&self) {
+        let r = T::regs();
+
+        r.shorts.reset();
+
+        compiler_fence(Ordering::SeqCst);
+
+        // tasks_stop() doesn't exist in all svds so write its bit instead
+        r.tasks_stop.write(|w| unsafe { w.bits(0x01) });
+    }
+
+    /// Disables the PWM generator.
+    #[inline(always)]
+    pub fn disable(&self) {
+        let r = T::regs();
+        r.enable.write(|w| w.enable().disabled());
+    }
+}
+
+impl<'a, T: Instance> Drop for SequencePwm<'a, T> {
+    fn drop(&mut self) {
+        let r = T::regs();
+
+        self.stop();
+        self.disable();
+
+        if let Some(pin) = &self.ch0 {
+            pin.set_low();
+            pin.conf().write(|w| w);
+            r.psel.out[0].write(|w| unsafe { w.bits(0x80000000) });
+        }
+        if let Some(pin) = &self.ch1 {
+            pin.set_low();
+            pin.conf().write(|w| w);
+            r.psel.out[1].write(|w| unsafe { w.bits(0x80000000) });
+        }
+        if let Some(pin) = &self.ch2 {
+            pin.set_low();
+            pin.conf().write(|w| w);
+            r.psel.out[2].write(|w| unsafe { w.bits(0x80000000) });
+        }
+        if let Some(pin) = &self.ch3 {
+            pin.set_low();
+            pin.conf().write(|w| w);
+            r.psel.out[3].write(|w| unsafe { w.bits(0x80000000) });
+        }
+    }
+}
+
+/// Configure an infinite looping sequence for `SequencePwm`
+#[non_exhaustive]
+pub struct SequenceConfig {
+    /// Selects up mode or up-and-down mode for the counter
+    pub counter_mode: CounterMode,
+    /// Top value to be compared against buffer values
+    pub top: u16,
+    /// Configuration for PWM_CLK
+    pub prescaler: Prescaler,
+    /// How a sequence is read from RAM and is spread to the compare register
+    pub sequence_load: SequenceLoad,
+    /// Number of PWM periods to delay between each sequence sample
+    pub refresh: u32,
+    /// Number of PWM periods after the sequence ends before starting the next sequence
+    pub end_delay: u32,
+}
+
+impl Default for SequenceConfig {
+    fn default() -> SequenceConfig {
+        SequenceConfig {
+            counter_mode: CounterMode::Up,
+            top: 1000,
+            prescaler: Prescaler::Div16,
+            sequence_load: SequenceLoad::Common,
+            refresh: 0,
+            end_delay: 0,
+        }
+    }
+}
+
+/// How many times to run the sequence
+#[derive(Debug, Eq, PartialEq, Clone, Copy)]
+pub enum SequenceMode {
+    /// Run sequence n Times total
+    Times(u16),
+    /// Repeat until `stop` is called.
+    Infinite,
+}
+
+/// PWM Base clock is system clock (16MHz) divided by prescaler
 #[derive(Debug, Eq, PartialEq, Clone, Copy)]
 pub enum Prescaler {
     Div1,
@@ -23,20 +306,42 @@ pub enum Prescaler {
     Div128,
 }
 
-/// Interface to the UARTE peripheral
-pub struct Pwm<'d, T: Instance> {
-    phantom: PhantomData<&'d mut T>,
+/// How the sequence values are distributed across the channels
+#[derive(Debug, Eq, PartialEq, Clone, Copy)]
+pub enum SequenceLoad {
+    /// Provided sequence will be used across all channels
+    Common,
+    /// Provided sequence contains grouped values for each channel ex:
+    /// [ch0_0_and_ch1_0, ch2_0_and_ch3_0, ... ch0_n_and_ch1_n, ch2_n_and_ch3_n]
+    Grouped,
+    /// Provided sequence contains individual values for each channel ex:
+    /// [ch0_0, ch1_0, ch2_0, ch3_0... ch0_n, ch1_n, ch2_n, ch3_n]
+    Individual,
+    /// Similar to Individual mode, but only three channels are used. The fourth
+    /// value is loaded into the pulse generator counter as its top value.
+    Waveform,
 }
 
-impl<'d, T: Instance> Pwm<'d, T> {
-    /// Creates the interface to a UARTE instance.
-    /// Sets the baud rate, parity and assigns the pins to the UARTE peripheral.
+/// Selects up mode or up-and-down mode for the counter
+#[derive(Debug, Eq, PartialEq, Clone, Copy)]
+pub enum CounterMode {
+    /// Up counter (edge-aligned PWM duty cycle)
+    Up,
+    /// Up and down counter (center-aligned PWM duty cycle)
+    UpAndDown,
+}
+
+impl<'d, T: Instance> SimplePwm<'d, T> {
+    /// Creates the interface to a `SimplePwm`
+    ///
+    /// Defaults the freq to 1Mhz, max_duty 1000, duty 0, up mode, and pins low.
+    /// Must be started by calling `set_duty`
     ///
     /// # Safety
     ///
-    /// The returned API is safe unless you use `mem::forget` (or similar safe mechanisms)
-    /// on stack allocated buffers which which have been passed to [`send()`](Pwm::send)
-    /// or [`receive`](Pwm::receive).
+    /// The returned API is safe unless you use `mem::forget` (or similar safe
+    /// mechanisms) on stack allocated buffers which which have been passed to
+    /// [`new()`](SimplePwm::new).
     #[allow(unused_unsafe)]
     pub fn new(
         _pwm: impl Unborrow<Target = T> + 'd,
@@ -48,7 +353,6 @@ impl<'d, T: Instance> Pwm<'d, T> {
         unborrow!(ch0, ch1, ch2, ch3);
 
         let r = T::regs();
-        let s = T::state();
 
         if let Some(pin) = ch0.pin_mut() {
             pin.set_low();
@@ -66,22 +370,36 @@ impl<'d, T: Instance> Pwm<'d, T> {
             pin.set_low();
             pin.conf().write(|w| w.dir().output());
         }
+
+        // if NoPin provided writes disconnected (top bit 1) 0x80000000 else
+        // writes pin number ex 13 (0x0D) which is connected (top bit 0)
         r.psel.out[0].write(|w| unsafe { w.bits(ch0.psel_bits()) });
         r.psel.out[1].write(|w| unsafe { w.bits(ch1.psel_bits()) });
         r.psel.out[2].write(|w| unsafe { w.bits(ch2.psel_bits()) });
         r.psel.out[3].write(|w| unsafe { w.bits(ch3.psel_bits()) });
 
+        let pwm = Self {
+            phantom: PhantomData,
+            ch0: ch0.degrade_optional(),
+            ch1: ch1.degrade_optional(),
+            ch2: ch2.degrade_optional(),
+            ch3: ch3.degrade_optional(),
+            duty: [0; 4],
+        };
+
         // Disable all interrupts
         r.intenclr.write(|w| unsafe { w.bits(0xFFFF_FFFF) });
+        r.shorts.reset();
 
         // Enable
         r.enable.write(|w| w.enable().enabled());
 
         r.seq0
             .ptr
-            .write(|w| unsafe { w.bits(&s.duty as *const _ as u32) });
+            .write(|w| unsafe { w.bits(&pwm.duty as *const _ as u32) });
+
         r.seq0.cnt.write(|w| unsafe { w.bits(4) });
-        r.seq0.refresh.write(|w| unsafe { w.bits(32) });
+        r.seq0.refresh.write(|w| unsafe { w.bits(0) });
         r.seq0.enddelay.write(|w| unsafe { w.bits(0) });
 
         r.decoder.write(|w| {
@@ -89,14 +407,24 @@ impl<'d, T: Instance> Pwm<'d, T> {
             w.mode().refresh_count()
         });
         r.mode.write(|w| w.updown().up());
-        r.prescaler.write(|w| w.prescaler().div_1());
-        r.countertop
-            .write(|w| unsafe { w.countertop().bits(32767) });
+        r.prescaler.write(|w| w.prescaler().div_16());
+        r.countertop.write(|w| unsafe { w.countertop().bits(1000) });
         r.loop_.write(|w| w.cnt().disabled());
 
-        Self {
-            phantom: PhantomData,
-        }
+        pwm
+    }
+
+    /// Stop playback
+    #[inline(always)]
+    pub fn stop(&self) {
+        let r = T::regs();
+
+        r.shorts.reset();
+
+        compiler_fence(Ordering::SeqCst);
+
+        // tasks_stop() doesn't exist in all svds so write its bit instead
+        r.tasks_stop.write(|w| unsafe { w.bits(0x01) });
     }
 
     /// Enables the PWM generator.
@@ -114,12 +442,24 @@ impl<'d, T: Instance> Pwm<'d, T> {
     }
 
     /// Sets duty cycle (15 bit) for a PWM channel.
-    pub fn set_duty(&self, channel: usize, duty: u16) {
-        let s = T::state();
-        unsafe { (*s.duty.get())[channel] = duty & 0x7FFF };
+    pub fn set_duty(&mut self, channel: usize, duty: u16) {
+        let r = T::regs();
 
+        self.duty[channel] = duty & 0x7FFF;
+
+        r.seq0
+            .ptr
+            .write(|w| unsafe { w.bits(&self.duty as *const _ as u32) });
+
+        // defensive before seqstart
         compiler_fence(Ordering::SeqCst);
-        T::regs().tasks_seqstart[0].write(|w| unsafe { w.bits(1) });
+
+        // tasks_seqstart() doesn't exist in all svds so write its bit instead
+        r.tasks_seqstart[0].write(|w| unsafe { w.bits(1) });
+
+        // defensive wait until waveform is loaded after seqstart
+        while r.events_seqend[0].read().bits() == 0 {}
+        r.events_seqend[0].write(|w| w);
     }
 
     /// Sets the PWM clock prescaler.
@@ -128,7 +468,7 @@ impl<'d, T: Instance> Pwm<'d, T> {
         T::regs().prescaler.write(|w| w.prescaler().bits(div as u8));
     }
 
-    /// Sets the PWM clock prescaler.
+    /// Gets the PWM clock prescaler.
     #[inline(always)]
     pub fn prescaler(&self) -> Prescaler {
         match T::regs().prescaler.read().prescaler().bits() {
@@ -175,36 +515,41 @@ impl<'d, T: Instance> Pwm<'d, T> {
     }
 }
 
-impl<'a, T: Instance> Drop for Pwm<'a, T> {
+impl<'a, T: Instance> Drop for SimplePwm<'a, T> {
     fn drop(&mut self) {
         let r = T::regs();
-        r.enable.write(|w| w.enable().disabled());
 
-        info!("pwm drop: done");
+        self.stop();
+        self.disable();
 
-        // TODO: disable pins
+        if let Some(pin) = &self.ch0 {
+            pin.set_low();
+            pin.conf().write(|w| w);
+            r.psel.out[0].write(|w| unsafe { w.bits(0x80000000) });
+        }
+        if let Some(pin) = &self.ch1 {
+            pin.set_low();
+            pin.conf().write(|w| w);
+            r.psel.out[1].write(|w| unsafe { w.bits(0x80000000) });
+        }
+        if let Some(pin) = &self.ch2 {
+            pin.set_low();
+            pin.conf().write(|w| w);
+            r.psel.out[2].write(|w| unsafe { w.bits(0x80000000) });
+        }
+        if let Some(pin) = &self.ch3 {
+            pin.set_low();
+            pin.conf().write(|w| w);
+            r.psel.out[3].write(|w| unsafe { w.bits(0x80000000) });
+        }
     }
 }
 
 pub(crate) mod sealed {
     use super::*;
 
-    pub struct State {
-        pub duty: UnsafeCell<[u16; 4]>,
-    }
-    unsafe impl Sync for State {}
-
-    impl State {
-        pub const fn new() -> Self {
-            Self {
-                duty: UnsafeCell::new([0; 4]),
-            }
-        }
-    }
-
     pub trait Instance {
         fn regs() -> &'static pac::pwm0::RegisterBlock;
-        fn state() -> &'static State;
     }
 }
 
@@ -218,10 +563,6 @@ macro_rules! impl_pwm {
             fn regs() -> &'static pac::pwm0::RegisterBlock {
                 unsafe { &*pac::$pac_type::ptr() }
             }
-            fn state() -> &'static crate::pwm::sealed::State {
-                static STATE: crate::pwm::sealed::State = crate::pwm::sealed::State::new();
-                &STATE
-            }
         }
         impl crate::pwm::Instance for peripherals::$type {
             type Interrupt = crate::interrupt::$irq;
diff --git a/embassy-nrf/src/util.rs b/embassy-nrf/src/util.rs
index 344fb01f9..2fd0bc5a8 100644
--- a/embassy-nrf/src/util.rs
+++ b/embassy-nrf/src/util.rs
@@ -2,15 +2,15 @@ const SRAM_LOWER: usize = 0x2000_0000;
 const SRAM_UPPER: usize = 0x3000_0000;
 
 /// Does this slice reside entirely within RAM?
-pub(crate) fn slice_in_ram(slice: &[u8]) -> bool {
+pub(crate) fn slice_in_ram<T>(slice: &[T]) -> bool {
     let ptr = slice.as_ptr() as usize;
-    ptr >= SRAM_LOWER && (ptr + slice.len()) < SRAM_UPPER
+    ptr >= SRAM_LOWER && (ptr + slice.len() * core::mem::size_of::<T>()) < SRAM_UPPER
 }
 
 /// Return an error if slice is not in RAM.
 #[cfg(not(feature = "nrf51"))]
-pub(crate) fn slice_in_ram_or<T>(slice: &[u8], err: T) -> Result<(), T> {
-    if slice.len() == 0 || slice_in_ram(slice) {
+pub(crate) fn slice_in_ram_or<T, E>(slice: &[T], err: E) -> Result<(), E> {
+    if slice.is_empty() || slice_in_ram(slice) {
         Ok(())
     } else {
         Err(err)