stm32: initial support for alternative ringbuffer implementation

5 files changed, 751 insertions, 0 deletions

diff --git a/embassy-stm32/src/dma/ringbuffer/mod.rs b/embassy-stm32/src/dma/ringbuffer/mod.rs
new file mode 100644
index 000000000..10a9ff975
--- /dev/null
+++ b/embassy-stm32/src/dma/ringbuffer/mod.rs
@@ -0,0 +1,293 @@
+#![cfg_attr(gpdma, allow(unused))]
+
+use core::future::poll_fn;
+use core::task::{Poll, Waker};
+
+use crate::dma::word::Word;
+
+pub trait DmaCtrl {
+    /// Get the NDTR register value, i.e. the space left in the underlying
+    /// buffer until the dma writer wraps.
+    fn get_remaining_transfers(&self) -> usize;
+
+    /// Reset the transfer completed counter to 0 and return the value just prior to the reset.
+    fn reset_complete_count(&mut self) -> usize;
+
+    /// Set the waker for a running poll_fn
+    fn set_waker(&mut self, waker: &Waker);
+}
+
+#[derive(Debug, PartialEq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct OverrunError;
+
+#[derive(Debug, Clone, Copy, Default)]
+struct DmaIndex {
+    completion_count: usize,
+    pos: usize,
+}
+
+fn pos(cap: usize, dma: &impl DmaCtrl) -> usize {
+    cap - dma.get_remaining_transfers()
+}
+
+impl DmaIndex {
+    fn reset(&mut self) {
+        self.pos = 0;
+        self.completion_count = 0;
+    }
+
+    fn as_index(&self, cap: usize, offset: usize) -> usize {
+        (self.pos + offset) % cap
+    }
+
+    fn dma_sync(&mut self, cap: usize, dma: &mut impl DmaCtrl) {
+        let fst_pos = pos(cap, dma);
+        let fst_count = dma.reset_complete_count();
+        let pos = pos(cap, dma);
+
+        let wrap_count = if pos >= fst_pos {
+            fst_count
+        } else {
+            fst_count + dma.reset_complete_count()
+        };
+
+        self.pos = pos;
+        self.completion_count += wrap_count;
+    }
+
+    fn advance(&mut self, cap: usize, steps: usize) {
+        let next = self.pos + steps;
+        self.completion_count += next / cap;
+        self.pos = next % cap;
+    }
+
+    fn normalize(lhs: &mut DmaIndex, rhs: &mut DmaIndex) {
+        let min_count = lhs.completion_count.min(rhs.completion_count);
+        lhs.completion_count -= min_count;
+        rhs.completion_count -= min_count;
+    }
+
+    fn diff(&mut self, cap: usize, rhs: &mut DmaIndex) -> isize {
+        Self::normalize(self, rhs);
+        (self.completion_count * cap + self.pos) as isize - (rhs.completion_count * cap + rhs.pos) as isize
+    }
+}
+
+pub struct ReadableDmaRingBuffer<'a, W: Word> {
+    dma_buf: &'a mut [W],
+    write_index: DmaIndex,
+    read_index: DmaIndex,
+}
+
+impl<'a, W: Word> ReadableDmaRingBuffer<'a, W> {
+    /// Construct an empty buffer.
+    pub fn new(dma_buf: &'a mut [W]) -> Self {
+        Self {
+            dma_buf,
+            write_index: Default::default(),
+            read_index: Default::default(),
+        }
+    }
+
+    /// Reset the ring buffer to its initial state
+    pub fn clear(&mut self, dma: &mut impl DmaCtrl) {
+        dma.reset_complete_count();
+        self.write_index.reset();
+        self.update_dma_index(dma);
+        self.read_index = self.write_index;
+    }
+
+    /// The capacity of the ringbuffer
+    pub const fn cap(&self) -> usize {
+        self.dma_buf.len()
+    }
+
+    /// Read elements from the ring buffer
+    /// Return a tuple of the length read and the length remaining in the buffer
+    /// If not all of the elements were read, then there will be some elements in the buffer remaining
+    /// The length remaining is the capacity, ring_buf.len(), less the elements remaining after the read
+    /// OverrunError is returned if the portion to be read was overwritten by the DMA controller.
+    pub fn read(&mut self, dma: &mut impl DmaCtrl, buf: &mut [W]) -> Result<(usize, usize), OverrunError> {
+        let readable = self.margin(dma)?.min(buf.len());
+        for i in 0..readable {
+            buf[i] = self.read_buf(i);
+        }
+        let available = self.margin(dma)?;
+        self.read_index.advance(self.cap(), readable);
+        Ok((readable, available - readable))
+    }
+
+    /// Read an exact number of elements from the ringbuffer.
+    ///
+    /// Returns the remaining number of elements available for immediate reading.
+    /// OverrunError is returned if the portion to be read was overwritten by the DMA controller.
+    ///
+    /// Async/Wake Behavior:
+    /// The underlying DMA peripheral only can wake us when its buffer pointer has reached the halfway point,
+    /// and when it wraps around. This means that when called with a buffer of length 'M', when this
+    /// ring buffer was created with a buffer of size 'N':
+    /// - If M equals N/2 or N/2 divides evenly into M, this function will return every N/2 elements read on the DMA source.
+    /// - Otherwise, this function may need up to N/2 extra elements to arrive before returning.
+    pub async fn read_exact(&mut self, dma: &mut impl DmaCtrl, buffer: &mut [W]) -> Result<usize, OverrunError> {
+        let mut read_data = 0;
+        let buffer_len = buffer.len();
+
+        poll_fn(|cx| {
+            dma.set_waker(cx.waker());
+
+            match self.read(dma, &mut buffer[read_data..buffer_len]) {
+                Ok((len, remaining)) => {
+                    read_data += len;
+                    if read_data == buffer_len {
+                        Poll::Ready(Ok(remaining))
+                    } else {
+                        Poll::Pending
+                    }
+                }
+                Err(e) => Poll::Ready(Err(e)),
+            }
+        })
+        .await
+    }
+
+    fn update_dma_index(&mut self, dma: &mut impl DmaCtrl) {
+        self.write_index.dma_sync(self.cap(), dma)
+    }
+
+    fn read_buf(&self, offset: usize) -> W {
+        unsafe {
+            core::ptr::read_volatile(
+                self.dma_buf
+                    .as_ptr()
+                    .offset(self.read_index.as_index(self.cap(), offset) as isize),
+            )
+        }
+    }
+
+    /// Returns available dma samples
+    fn margin(&mut self, dma: &mut impl DmaCtrl) -> Result<usize, OverrunError> {
+        self.update_dma_index(dma);
+
+        let diff: usize = self
+            .write_index
+            .diff(self.cap(), &mut self.read_index)
+            .try_into()
+            .unwrap();
+
+        if diff > self.cap() {
+            Err(OverrunError)
+        } else {
+            Ok(diff)
+        }
+    }
+}
+
+pub struct WritableDmaRingBuffer<'a, W: Word> {
+    dma_buf: &'a mut [W],
+    read_index: DmaIndex,
+    write_index: DmaIndex,
+}
+
+impl<'a, W: Word> WritableDmaRingBuffer<'a, W> {
+    /// Construct a ringbuffer filled with the given buffer data.
+    pub fn new(dma_buf: &'a mut [W]) -> Self {
+        let len = dma_buf.len();
+        Self {
+            dma_buf,
+            read_index: Default::default(),
+            write_index: DmaIndex {
+                completion_count: 0,
+                pos: len,
+            },
+        }
+    }
+
+    /// Reset the ring buffer to its initial state. The buffer after the reset will be full.
+    pub fn clear(&mut self, dma: &mut impl DmaCtrl) {
+        dma.reset_complete_count();
+        self.read_index.reset();
+        self.update_dma_index(dma);
+        self.write_index = self.read_index;
+        self.write_index.advance(self.cap(), self.cap());
+    }
+
+    /// Get the capacity of the ringbuffer.
+    pub const fn cap(&self) -> usize {
+        self.dma_buf.len()
+    }
+
+    /// Append data to the ring buffer.
+    /// Returns a tuple of the data written and the remaining write capacity in the buffer.
+    pub fn write(&mut self, dma: &mut impl DmaCtrl, buf: &[W]) -> Result<(usize, usize), OverrunError> {
+        let writable = self.margin(dma)?.min(buf.len());
+        for i in 0..writable {
+            self.write_buf(i, buf[i]);
+        }
+        let available = self.margin(dma)?;
+        self.write_index.advance(self.cap(), writable);
+        Ok((writable, available - writable))
+    }
+
+    /// Write elements directly to the buffer.
+    pub fn write_immediate(&mut self, buf: &[W]) -> Result<(usize, usize), OverrunError> {
+        for (i, data) in buf.iter().enumerate() {
+            self.write_buf(i, *data)
+        }
+        let written = buf.len().min(self.cap());
+        Ok((written, self.cap() - written))
+    }
+
+    /// Write an exact number of elements to the ringbuffer.
+    pub async fn write_exact(&mut self, dma: &mut impl DmaCtrl, buffer: &[W]) -> Result<usize, OverrunError> {
+        let mut written_data = 0;
+        let buffer_len = buffer.len();
+
+        poll_fn(|cx| {
+            dma.set_waker(cx.waker());
+
+            match self.write(dma, &buffer[written_data..buffer_len]) {
+                Ok((len, remaining)) => {
+                    written_data += len;
+                    if written_data == buffer_len {
+                        Poll::Ready(Ok(remaining))
+                    } else {
+                        Poll::Pending
+                    }
+                }
+                Err(e) => Poll::Ready(Err(e)),
+            }
+        })
+        .await
+    }
+
+    fn update_dma_index(&mut self, dma: &mut impl DmaCtrl) {
+        self.read_index.dma_sync(self.cap(), dma);
+    }
+
+    fn write_buf(&mut self, offset: usize, value: W) {
+        unsafe {
+            core::ptr::write_volatile(
+                self.dma_buf
+                    .as_mut_ptr()
+                    .offset(self.write_index.as_index(self.cap(), offset) as isize),
+                value,
+            )
+        }
+    }
+
+    fn margin(&mut self, dma: &mut impl DmaCtrl) -> Result<usize, OverrunError> {
+        self.update_dma_index(dma);
+
+        let diff = self.write_index.diff(self.cap(), &mut self.read_index);
+
+        if diff < 0 {
+            Err(OverrunError)
+        } else {
+            Ok(self.cap().saturating_sub(diff as usize))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;
diff --git a/embassy-stm32/src/dma/ringbuffer/tests/mod.rs b/embassy-stm32/src/dma/ringbuffer/tests/mod.rs
new file mode 100644
index 000000000..9768e1df8
--- /dev/null
+++ b/embassy-stm32/src/dma/ringbuffer/tests/mod.rs
@@ -0,0 +1,165 @@
+use std::{cell, vec};
+
+use super::*;
+
+#[allow(dead_code)]
+#[derive(PartialEq, Debug)]
+enum TestCircularTransferRequest {
+    ResetCompleteCount(usize),
+    PositionRequest(usize),
+}
+
+struct TestCircularTransfer {
+    len: usize,
+    requests: cell::RefCell<vec::Vec<TestCircularTransferRequest>>,
+}
+
+impl DmaCtrl for TestCircularTransfer {
+    fn get_remaining_transfers(&self) -> usize {
+        match self.requests.borrow_mut().pop().unwrap() {
+            TestCircularTransferRequest::PositionRequest(pos) => {
+                let len = self.len;
+
+                assert!(len >= pos);
+
+                len - pos
+            }
+            _ => unreachable!(),
+        }
+    }
+
+    fn reset_complete_count(&mut self) -> usize {
+        match self.requests.get_mut().pop().unwrap() {
+            TestCircularTransferRequest::ResetCompleteCount(complete_count) => complete_count,
+            _ => unreachable!(),
+        }
+    }
+
+    fn set_waker(&mut self, _waker: &Waker) {}
+}
+
+impl TestCircularTransfer {
+    pub fn new(len: usize) -> Self {
+        Self {
+            requests: cell::RefCell::new(vec![]),
+            len,
+        }
+    }
+
+    pub fn setup(&self, mut requests: vec::Vec<TestCircularTransferRequest>) {
+        requests.reverse();
+        self.requests.replace(requests);
+    }
+}
+
+const CAP: usize = 16;
+
+#[test]
+fn dma_index_dma_sync_syncs_position_to_last_read_if_sync_takes_place_on_same_dma_cycle() {
+    let mut dma = TestCircularTransfer::new(CAP);
+    dma.setup(vec![
+        TestCircularTransferRequest::PositionRequest(4),
+        TestCircularTransferRequest::ResetCompleteCount(0),
+        TestCircularTransferRequest::PositionRequest(7),
+    ]);
+    let mut index = DmaIndex::default();
+    index.dma_sync(CAP, &mut dma);
+    assert_eq!(index.completion_count, 0);
+    assert_eq!(index.pos, 7);
+}
+
+#[test]
+fn dma_index_dma_sync_updates_completion_count_properly_if_sync_takes_place_on_same_dma_cycle() {
+    let mut dma = TestCircularTransfer::new(CAP);
+    dma.setup(vec![
+        TestCircularTransferRequest::PositionRequest(4),
+        TestCircularTransferRequest::ResetCompleteCount(2),
+        TestCircularTransferRequest::PositionRequest(7),
+    ]);
+    let mut index = DmaIndex::default();
+    index.completion_count = 1;
+    index.dma_sync(CAP, &mut dma);
+    assert_eq!(index.completion_count, 3);
+    assert_eq!(index.pos, 7);
+}
+
+#[test]
+fn dma_index_dma_sync_syncs_to_last_position_if_reads_occur_on_different_dma_cycles() {
+    let mut dma = TestCircularTransfer::new(CAP);
+    dma.setup(vec![
+        TestCircularTransferRequest::PositionRequest(10),
+        TestCircularTransferRequest::ResetCompleteCount(1),
+        TestCircularTransferRequest::PositionRequest(5),
+        TestCircularTransferRequest::ResetCompleteCount(0),
+    ]);
+    let mut index = DmaIndex::default();
+    index.dma_sync(CAP, &mut dma);
+    assert_eq!(index.completion_count, 1);
+    assert_eq!(index.pos, 5);
+}
+
+#[test]
+fn dma_index_dma_sync_detects_new_cycle_if_later_position_is_less_than_first_and_first_completion_count_occurs_on_first_cycle(
+) {
+    let mut dma = TestCircularTransfer::new(CAP);
+    dma.setup(vec![
+        TestCircularTransferRequest::PositionRequest(10),
+        TestCircularTransferRequest::ResetCompleteCount(1),
+        TestCircularTransferRequest::PositionRequest(5),
+        TestCircularTransferRequest::ResetCompleteCount(1),
+    ]);
+    let mut index = DmaIndex::default();
+    index.completion_count = 1;
+    index.dma_sync(CAP, &mut dma);
+    assert_eq!(index.completion_count, 3);
+    assert_eq!(index.pos, 5);
+}
+
+#[test]
+fn dma_index_dma_sync_detects_new_cycle_if_later_position_is_less_than_first_and_first_completion_count_occurs_on_later_cycle(
+) {
+    let mut dma = TestCircularTransfer::new(CAP);
+    dma.setup(vec![
+        TestCircularTransferRequest::PositionRequest(10),
+        TestCircularTransferRequest::ResetCompleteCount(2),
+        TestCircularTransferRequest::PositionRequest(5),
+        TestCircularTransferRequest::ResetCompleteCount(0),
+    ]);
+    let mut index = DmaIndex::default();
+    index.completion_count = 1;
+    index.dma_sync(CAP, &mut dma);
+    assert_eq!(index.completion_count, 3);
+    assert_eq!(index.pos, 5);
+}
+
+#[test]
+fn dma_index_as_index_returns_index_mod_cap_by_default() {
+    let index = DmaIndex::default();
+    assert_eq!(index.as_index(CAP, 0), 0);
+    assert_eq!(index.as_index(CAP, 1), 1);
+    assert_eq!(index.as_index(CAP, 2), 2);
+    assert_eq!(index.as_index(CAP, 3), 3);
+    assert_eq!(index.as_index(CAP, 4), 4);
+    assert_eq!(index.as_index(CAP, CAP), 0);
+    assert_eq!(index.as_index(CAP, CAP + 1), 1);
+}
+
+#[test]
+fn dma_index_advancing_increases_as_index() {
+    let mut index = DmaIndex::default();
+    assert_eq!(index.as_index(CAP, 0), 0);
+    index.advance(CAP, 1);
+    assert_eq!(index.as_index(CAP, 0), 1);
+    index.advance(CAP, 1);
+    assert_eq!(index.as_index(CAP, 0), 2);
+    index.advance(CAP, 1);
+    assert_eq!(index.as_index(CAP, 0), 3);
+    index.advance(CAP, 1);
+    assert_eq!(index.as_index(CAP, 0), 4);
+    index.advance(CAP, CAP - 4);
+    assert_eq!(index.as_index(CAP, 0), 0);
+    index.advance(CAP, 1);
+    assert_eq!(index.as_index(CAP, 0), 1);
+}
+
+mod prop_test;
diff --git a/embassy-stm32/src/dma/ringbuffer/tests/prop_test/mod.rs b/embassy-stm32/src/dma/ringbuffer/tests/prop_test/mod.rs
new file mode 100644
index 000000000..661fb1728
--- /dev/null
+++ b/embassy-stm32/src/dma/ringbuffer/tests/prop_test/mod.rs
@@ -0,0 +1,50 @@
+use std::task::Waker;
+
+use proptest::prop_oneof;
+use proptest::strategy::{self, BoxedStrategy, Strategy as _};
+use proptest_state_machine::{prop_state_machine, ReferenceStateMachine, StateMachineTest};
+
+use super::*;
+
+const CAP: usize = 128;
+
+#[derive(Debug, Default)]
+struct DmaMock {
+    pos: usize,
+    wraps: usize,
+}
+
+impl DmaMock {
+    pub fn advance(&mut self, steps: usize) {
+        let next = self.pos + steps;
+        self.pos = next % CAP;
+        self.wraps += next / CAP;
+    }
+}
+
+impl DmaCtrl for DmaMock {
+    fn get_remaining_transfers(&self) -> usize {
+        CAP - self.pos
+    }
+
+    fn reset_complete_count(&mut self) -> usize {
+        core::mem::replace(&mut self.wraps, 0)
+    }
+
+    fn set_waker(&mut self, _waker: &Waker) {}
+}
+
+#[derive(Debug, Clone)]
+enum Status {
+    Available(usize),
+    Failed,
+}
+
+impl Status {
+    pub fn new(capacity: usize) -> Self {
+        Self::Available(capacity)
+    }
+}
+
+mod reader;
+mod writer;
diff --git a/embassy-stm32/src/dma/ringbuffer/tests/prop_test/reader.rs b/embassy-stm32/src/dma/ringbuffer/tests/prop_test/reader.rs
new file mode 100644
index 000000000..6555ebfb0
--- /dev/null
+++ b/embassy-stm32/src/dma/ringbuffer/tests/prop_test/reader.rs
@@ -0,0 +1,122 @@
+use core::fmt::Debug;
+
+use super::*;
+
+#[derive(Debug, Clone)]
+enum ReaderTransition {
+    Write(usize),
+    Clear,
+    ReadUpTo(usize),
+}
+
+struct ReaderSM;
+
+impl ReferenceStateMachine for ReaderSM {
+    type State = Status;
+    type Transition = ReaderTransition;
+
+    fn init_state() -> BoxedStrategy<Self::State> {
+        strategy::Just(Status::new(0)).boxed()
+    }
+
+    fn transitions(_state: &Self::State) -> BoxedStrategy<Self::Transition> {
+        prop_oneof![
+            (1..50_usize).prop_map(ReaderTransition::Write),
+            (1..50_usize).prop_map(ReaderTransition::ReadUpTo),
+            strategy::Just(ReaderTransition::Clear),
+        ]
+        .boxed()
+    }
+
+    fn apply(status: Self::State, transition: &Self::Transition) -> Self::State {
+        match (status, transition) {
+            (_, ReaderTransition::Clear) => Status::Available(0),
+            (Status::Available(x), ReaderTransition::Write(y)) => {
+                if x + y > CAP {
+                    Status::Failed
+                } else {
+                    Status::Available(x + y)
+                }
+            }
+            (Status::Available(x), ReaderTransition::ReadUpTo(y)) => Status::Available(x.saturating_sub(*y)),
+            (Status::Failed, _) => Status::Failed,
+        }
+    }
+}
+
+struct ReaderSut {
+    status: Status,
+    buffer: *mut [u8],
+    producer: DmaMock,
+    consumer: ReadableDmaRingBuffer<'static, u8>,
+}
+
+impl Debug for ReaderSut {
+    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+        <DmaMock as Debug>::fmt(&self.producer, f)
+    }
+}
+
+struct ReaderTest;
+
+impl StateMachineTest for ReaderTest {
+    type SystemUnderTest = ReaderSut;
+    type Reference = ReaderSM;
+
+    fn init_test(ref_status: &<Self::Reference as ReferenceStateMachine>::State) -> Self::SystemUnderTest {
+        let buffer = Box::into_raw(Box::new([0; CAP]));
+        ReaderSut {
+            status: ref_status.clone(),
+            buffer,
+            producer: DmaMock::default(),
+            consumer: ReadableDmaRingBuffer::new(unsafe { &mut *buffer }),
+        }
+    }
+
+    fn teardown(state: Self::SystemUnderTest) {
+        unsafe {
+            let _ = Box::from_raw(state.buffer);
+        };
+    }
+
+    fn apply(
+        mut sut: Self::SystemUnderTest,
+        ref_state: &<Self::Reference as ReferenceStateMachine>::State,
+        transition: <Self::Reference as ReferenceStateMachine>::Transition,
+    ) -> Self::SystemUnderTest {
+        match transition {
+            ReaderTransition::Write(x) => sut.producer.advance(x),
+            ReaderTransition::Clear => {
+                sut.consumer.clear(&mut sut.producer);
+            }
+            ReaderTransition::ReadUpTo(x) => {
+                let status = sut.status;
+                let ReaderSut {
+                    ref mut producer,
+                    ref mut consumer,
+                    ..
+                } = sut;
+                let mut buf = vec![0; x];
+                let res = consumer.read(producer, &mut buf);
+                match status {
+                    Status::Available(n) => {
+                        let readable = x.min(n);
+
+                        assert_eq!(res.unwrap().0, readable);
+                    }
+                    Status::Failed => assert!(res.is_err()),
+                }
+            }
+        }
+
+        ReaderSut {
+            status: ref_state.clone(),
+            ..sut
+        }
+    }
+}
+
+prop_state_machine! {
+    #[test]
+    fn reader_state_test(sequential 1..20 => ReaderTest);
+}
diff --git a/embassy-stm32/src/dma/ringbuffer/tests/prop_test/writer.rs b/embassy-stm32/src/dma/ringbuffer/tests/prop_test/writer.rs
new file mode 100644
index 000000000..15f54c672
--- /dev/null
+++ b/embassy-stm32/src/dma/ringbuffer/tests/prop_test/writer.rs
@@ -0,0 +1,121 @@
+use core::fmt::Debug;
+
+use super::*;
+
+#[derive(Debug, Clone)]
+enum WriterTransition {
+    Read(usize),
+    WriteUpTo(usize),
+    Clear,
+}
+
+struct WriterSM;
+
+impl ReferenceStateMachine for WriterSM {
+    type State = Status;
+    type Transition = WriterTransition;
+
+    fn init_state() -> BoxedStrategy<Self::State> {
+        strategy::Just(Status::new(CAP)).boxed()
+    }
+
+    fn transitions(_state: &Self::State) -> BoxedStrategy<Self::Transition> {
+        prop_oneof![
+            (1..50_usize).prop_map(WriterTransition::Read),
+            (1..50_usize).prop_map(WriterTransition::WriteUpTo),
+            strategy::Just(WriterTransition::Clear),
+        ]
+        .boxed()
+    }
+
+    fn apply(status: Self::State, transition: &Self::Transition) -> Self::State {
+        match (status, transition) {
+            (_, WriterTransition::Clear) => Status::Available(CAP),
+            (Status::Available(x), WriterTransition::Read(y)) => {
+                if x < *y {
+                    Status::Failed
+                } else {
+                    Status::Available(x - y)
+                }
+            }
+            (Status::Available(x), WriterTransition::WriteUpTo(y)) => Status::Available((x + *y).min(CAP)),
+            (Status::Failed, _) => Status::Failed,
+        }
+    }
+}
+
+struct WriterSut {
+    status: Status,
+    buffer: *mut [u8],
+    producer: WritableDmaRingBuffer<'static, u8>,
+    consumer: DmaMock,
+}
+
+impl Debug for WriterSut {
+    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+        <DmaMock as Debug>::fmt(&self.consumer, f)
+    }
+}
+
+struct WriterTest;
+
+impl StateMachineTest for WriterTest {
+    type SystemUnderTest = WriterSut;
+    type Reference = WriterSM;
+
+    fn init_test(ref_status: &<Self::Reference as ReferenceStateMachine>::State) -> Self::SystemUnderTest {
+        let buffer = Box::into_raw(Box::new([0; CAP]));
+        WriterSut {
+            status: ref_status.clone(),
+            buffer,
+            producer: WritableDmaRingBuffer::new(unsafe { &mut *buffer }),
+            consumer: DmaMock::default(),
+        }
+    }
+
+    fn teardown(state: Self::SystemUnderTest) {
+        unsafe {
+            let _ = Box::from_raw(state.buffer);
+        };
+    }
+
+    fn apply(
+        mut sut: Self::SystemUnderTest,
+        ref_status: &<Self::Reference as ReferenceStateMachine>::State,
+        transition: <Self::Reference as ReferenceStateMachine>::Transition,
+    ) -> Self::SystemUnderTest {
+        match transition {
+            WriterTransition::Read(x) => sut.consumer.advance(x),
+            WriterTransition::Clear => {
+                sut.producer.clear(&mut sut.consumer);
+            }
+            WriterTransition::WriteUpTo(x) => {
+                let status = sut.status;
+                let WriterSut {
+                    ref mut producer,
+                    ref mut consumer,
+                    ..
+                } = sut;
+                let mut buf = vec![0; x];
+                let res = producer.write(consumer, &mut buf);
+                match status {
+                    Status::Available(n) => {
+                        let writable = x.min(CAP - n.min(CAP));
+                        assert_eq!(res.unwrap().0, writable);
+                    }
+                    Status::Failed => assert!(res.is_err()),
+                }
+            }
+        }
+
+        WriterSut {
+            status: ref_status.clone(),
+            ..sut
+        }
+    }
+}
+
+prop_state_machine! {
+    #[test]
+    fn writer_state_test(sequential 1..20 => WriterTest);
+}