stm32: initial support for alternative ringbuffer implementation

4 files changed, 458 insertions, 0 deletions

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);
+}