486 lines
18 KiB
Rust
486 lines
18 KiB
Rust
#![cfg_attr(gpdma, allow(unused))]
|
|
|
|
use core::ops::Range;
|
|
use core::sync::atomic::{compiler_fence, Ordering};
|
|
|
|
use super::word::Word;
|
|
|
|
/// A "read-only" ring-buffer to be used together with the DMA controller which
|
|
/// writes in a circular way, "uncontrolled" to the buffer.
|
|
///
|
|
/// A snapshot of the ring buffer state can be attained by setting the `ndtr` field
|
|
/// to the current register value. `ndtr` describes the current position of the DMA
|
|
/// write.
|
|
///
|
|
/// # Buffer layout
|
|
///
|
|
/// ```text
|
|
/// Without wraparound: With wraparound:
|
|
///
|
|
/// + buf +--- NDTR ---+ + buf +---------- NDTR ----------+
|
|
/// | | | | | |
|
|
/// v v v v v v
|
|
/// +-----------------------------------------+ +-----------------------------------------+
|
|
/// |oooooooooooXXXXXXXXXXXXXXXXoooooooooooooo| |XXXXXXXXXXXXXooooooooooooXXXXXXXXXXXXXXXX|
|
|
/// +-----------------------------------------+ +-----------------------------------------+
|
|
/// ^ ^ ^ ^ ^ ^
|
|
/// | | | | | |
|
|
/// +- start --+ | +- end ------+ |
|
|
/// | | | |
|
|
/// +- end --------------------+ +- start ----------------+
|
|
/// ```
|
|
pub struct DmaRingBuffer<'a, W: Word> {
|
|
pub(crate) dma_buf: &'a mut [W],
|
|
start: usize,
|
|
}
|
|
|
|
#[derive(Debug, PartialEq)]
|
|
pub struct OverrunError;
|
|
|
|
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;
|
|
|
|
/// Get the transfer completed counter.
|
|
/// This counter is incremented by the dma controller when NDTR is reloaded,
|
|
/// i.e. when the writing wraps.
|
|
fn get_complete_count(&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;
|
|
}
|
|
|
|
impl<'a, W: Word> DmaRingBuffer<'a, W> {
|
|
pub fn new(dma_buf: &'a mut [W]) -> Self {
|
|
Self { dma_buf, start: 0 }
|
|
}
|
|
|
|
/// Reset the ring buffer to its initial state
|
|
pub fn clear(&mut self, mut dma: impl DmaCtrl) {
|
|
self.start = 0;
|
|
dma.reset_complete_count();
|
|
}
|
|
|
|
/// The capacity of the ringbuffer
|
|
pub const fn cap(&self) -> usize {
|
|
self.dma_buf.len()
|
|
}
|
|
|
|
/// The current position of the ringbuffer
|
|
fn pos(&self, remaining_transfers: usize) -> usize {
|
|
self.cap() - remaining_transfers
|
|
}
|
|
|
|
/// Read bytes from the ring buffer
|
|
/// Return a tuple of the length read and the length remaining in the buffer
|
|
/// If not all of the bytes were read, then there will be some bytes in the buffer remaining
|
|
/// The length remaining is the capacity, ring_buf.len(), less the bytes remaining after the read
|
|
/// OverrunError is returned if the portion to be read was overwritten by the DMA controller.
|
|
pub fn read(&mut self, mut dma: impl DmaCtrl, buf: &mut [W]) -> Result<(usize, usize), OverrunError> {
|
|
/*
|
|
This algorithm is optimistic: we assume we haven't overrun more than a full buffer and then check
|
|
after we've done our work to see we have. This is because on stm32, an interrupt is not guaranteed
|
|
to fire in the same clock cycle that a register is read, so checking get_complete_count early does
|
|
not yield relevant information.
|
|
|
|
Therefore, the only variable we really need to know is ndtr. If the dma has overrun by more than a full
|
|
buffer, we will do a bit more work than we have to, but algorithms should not be optimized for error
|
|
conditions.
|
|
|
|
After we've done our work, we confirm that we haven't overrun more than a full buffer, and also that
|
|
the dma has not overrun within the data we could have copied. We check the data we could have copied
|
|
rather than the data we actually copied because it costs nothing and confirms an error condition
|
|
earlier.
|
|
*/
|
|
let end = self.pos(dma.get_remaining_transfers());
|
|
if self.start == end && dma.get_complete_count() == 0 {
|
|
// No bytes are available in the buffer
|
|
Ok((0, self.cap()))
|
|
} else if self.start < end {
|
|
// The available, unread portion in the ring buffer DOES NOT wrap
|
|
// Copy out the bytes from the dma buffer
|
|
let len = self.copy_to(buf, self.start..end);
|
|
|
|
compiler_fence(Ordering::SeqCst);
|
|
|
|
/*
|
|
first, check if the dma has wrapped at all if it's after end
|
|
or more than once if it's before start
|
|
|
|
this is in a critical section to try to reduce mushy behavior.
|
|
it's not ideal but it's the best we can do
|
|
|
|
then, get the current position of of the dma write and check
|
|
if it's inside data we could have copied
|
|
*/
|
|
let (pos, complete_count) =
|
|
critical_section::with(|_| (self.pos(dma.get_remaining_transfers()), dma.get_complete_count()));
|
|
if (pos >= self.start && pos < end) || (complete_count > 0 && pos >= end) || complete_count > 1 {
|
|
Err(OverrunError)
|
|
} else {
|
|
self.start = (self.start + len) % self.cap();
|
|
|
|
Ok((len, self.cap() - self.start))
|
|
}
|
|
} else if self.start + buf.len() < self.cap() {
|
|
// The available, unread portion in the ring buffer DOES wrap
|
|
// The DMA writer has wrapped since we last read and is currently
|
|
// writing (or the next byte added will be) in the beginning of the ring buffer.
|
|
|
|
// The provided read buffer is not large enough to include all bytes from the tail of the dma buffer.
|
|
|
|
// Copy out from the dma buffer
|
|
let len = self.copy_to(buf, self.start..self.cap());
|
|
|
|
compiler_fence(Ordering::SeqCst);
|
|
|
|
/*
|
|
first, check if the dma has wrapped around more than once
|
|
|
|
then, get the current position of of the dma write and check
|
|
if it's inside data we could have copied
|
|
*/
|
|
let pos = self.pos(dma.get_remaining_transfers());
|
|
if pos > self.start || pos < end || dma.get_complete_count() > 1 {
|
|
Err(OverrunError)
|
|
} else {
|
|
self.start = (self.start + len) % self.cap();
|
|
|
|
Ok((len, self.start + end))
|
|
}
|
|
} else {
|
|
// The available, unread portion in the ring buffer DOES wrap
|
|
// The DMA writer has wrapped since we last read and is currently
|
|
// writing (or the next byte added will be) in the beginning of the ring buffer.
|
|
|
|
// The provided read buffer is large enough to include all bytes from the tail of the dma buffer,
|
|
// so the next read will not have any unread tail bytes in the ring buffer.
|
|
|
|
// Copy out from the dma buffer
|
|
let tail = self.copy_to(buf, self.start..self.cap());
|
|
let head = self.copy_to(&mut buf[tail..], 0..end);
|
|
|
|
compiler_fence(Ordering::SeqCst);
|
|
|
|
/*
|
|
first, check if the dma has wrapped around more than once
|
|
|
|
then, get the current position of of the dma write and check
|
|
if it's inside data we could have copied
|
|
*/
|
|
let pos = self.pos(dma.get_remaining_transfers());
|
|
if pos > self.start || pos < end || dma.reset_complete_count() > 1 {
|
|
Err(OverrunError)
|
|
} else {
|
|
self.start = head;
|
|
Ok((tail + head, self.cap() - self.start))
|
|
}
|
|
}
|
|
}
|
|
/// Copy from the dma buffer at `data_range` into `buf`
|
|
fn copy_to(&mut self, buf: &mut [W], data_range: Range<usize>) -> usize {
|
|
// Limit the number of bytes that can be copied
|
|
let length = usize::min(data_range.len(), buf.len());
|
|
|
|
// Copy from dma buffer into read buffer
|
|
// We need to do it like this instead of a simple copy_from_slice() because
|
|
// reading from a part of memory that may be simultaneously written to is unsafe
|
|
unsafe {
|
|
let dma_buf = self.dma_buf.as_ptr();
|
|
|
|
for i in 0..length {
|
|
buf[i] = core::ptr::read_volatile(dma_buf.offset((data_range.start + i) as isize));
|
|
}
|
|
}
|
|
|
|
length
|
|
}
|
|
}
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use core::array;
|
|
use std::{cell, vec};
|
|
|
|
use super::*;
|
|
|
|
#[allow(dead_code)]
|
|
#[derive(PartialEq, Debug)]
|
|
enum TestCircularTransferRequest {
|
|
GetCompleteCount(usize),
|
|
ResetCompleteCount(usize),
|
|
PositionRequest(usize),
|
|
}
|
|
|
|
struct TestCircularTransfer {
|
|
len: usize,
|
|
requests: cell::RefCell<vec::Vec<TestCircularTransferRequest>>,
|
|
}
|
|
|
|
impl DmaCtrl for &mut 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 get_complete_count(&self) -> usize {
|
|
match self.requests.borrow_mut().pop().unwrap() {
|
|
TestCircularTransferRequest::GetCompleteCount(complete_count) => complete_count,
|
|
_ => unreachable!(),
|
|
}
|
|
}
|
|
|
|
fn reset_complete_count(&mut self) -> usize {
|
|
match self.requests.get_mut().pop().unwrap() {
|
|
TestCircularTransferRequest::ResetCompleteCount(complete_count) => complete_count,
|
|
_ => unreachable!(),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl TestCircularTransfer {
|
|
pub fn new(len: usize) -> Self {
|
|
Self {
|
|
requests: cell::RefCell::new(vec![]),
|
|
len: len,
|
|
}
|
|
}
|
|
|
|
pub fn setup(&self, mut requests: vec::Vec<TestCircularTransferRequest>) {
|
|
requests.reverse();
|
|
self.requests.replace(requests);
|
|
}
|
|
}
|
|
|
|
#[test]
|
|
fn empty_and_read_not_started() {
|
|
let mut dma_buf = [0u8; 16];
|
|
let ringbuf = DmaRingBuffer::new(&mut dma_buf);
|
|
|
|
assert_eq!(0, ringbuf.start);
|
|
}
|
|
|
|
#[test]
|
|
fn can_read() {
|
|
let mut dma = TestCircularTransfer::new(16);
|
|
|
|
let mut dma_buf: [u8; 16] = array::from_fn(|idx| idx as u8); // 0, 1, ..., 15
|
|
let mut ringbuf = DmaRingBuffer::new(&mut dma_buf);
|
|
|
|
assert_eq!(0, ringbuf.start);
|
|
assert_eq!(16, ringbuf.cap());
|
|
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(8),
|
|
TestCircularTransferRequest::PositionRequest(10),
|
|
TestCircularTransferRequest::GetCompleteCount(0),
|
|
]);
|
|
let mut buf = [0; 2];
|
|
assert_eq!(2, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!([0, 1], buf);
|
|
assert_eq!(2, ringbuf.start);
|
|
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(10),
|
|
TestCircularTransferRequest::PositionRequest(12),
|
|
TestCircularTransferRequest::GetCompleteCount(0),
|
|
]);
|
|
let mut buf = [0; 2];
|
|
assert_eq!(2, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!([2, 3], buf);
|
|
assert_eq!(4, ringbuf.start);
|
|
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(12),
|
|
TestCircularTransferRequest::PositionRequest(14),
|
|
TestCircularTransferRequest::GetCompleteCount(0),
|
|
]);
|
|
let mut buf = [0; 8];
|
|
assert_eq!(8, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!([4, 5, 6, 7, 8, 9], buf[..6]);
|
|
assert_eq!(12, ringbuf.start);
|
|
}
|
|
|
|
#[test]
|
|
fn can_read_with_wrap() {
|
|
let mut dma = TestCircularTransfer::new(16);
|
|
|
|
let mut dma_buf: [u8; 16] = array::from_fn(|idx| idx as u8); // 0, 1, ..., 15
|
|
let mut ringbuf = DmaRingBuffer::new(&mut dma_buf);
|
|
|
|
assert_eq!(0, ringbuf.start);
|
|
assert_eq!(16, ringbuf.cap());
|
|
|
|
/*
|
|
Read to close to the end of the buffer
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(14),
|
|
TestCircularTransferRequest::PositionRequest(16),
|
|
TestCircularTransferRequest::GetCompleteCount(0),
|
|
]);
|
|
let mut buf = [0; 14];
|
|
assert_eq!(14, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!(14, ringbuf.start);
|
|
|
|
/*
|
|
Now, read around the buffer
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(6),
|
|
TestCircularTransferRequest::PositionRequest(8),
|
|
TestCircularTransferRequest::ResetCompleteCount(1),
|
|
]);
|
|
let mut buf = [0; 6];
|
|
assert_eq!(6, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!(4, ringbuf.start);
|
|
}
|
|
|
|
#[test]
|
|
fn can_read_when_dma_writer_is_wrapped_and_read_does_not_wrap() {
|
|
let mut dma = TestCircularTransfer::new(16);
|
|
|
|
let mut dma_buf: [u8; 16] = array::from_fn(|idx| idx as u8); // 0, 1, ..., 15
|
|
let mut ringbuf = DmaRingBuffer::new(&mut dma_buf);
|
|
|
|
assert_eq!(0, ringbuf.start);
|
|
assert_eq!(16, ringbuf.cap());
|
|
|
|
/*
|
|
Read to close to the end of the buffer
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(14),
|
|
TestCircularTransferRequest::PositionRequest(16),
|
|
TestCircularTransferRequest::GetCompleteCount(0),
|
|
]);
|
|
let mut buf = [0; 14];
|
|
assert_eq!(14, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!(14, ringbuf.start);
|
|
|
|
/*
|
|
Now, read to the end of the buffer
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(6),
|
|
TestCircularTransferRequest::PositionRequest(8),
|
|
TestCircularTransferRequest::ResetCompleteCount(1),
|
|
]);
|
|
let mut buf = [0; 2];
|
|
assert_eq!(2, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!(0, ringbuf.start);
|
|
}
|
|
|
|
#[test]
|
|
fn can_read_when_dma_writer_wraps_once_with_same_ndtr() {
|
|
let mut dma = TestCircularTransfer::new(16);
|
|
|
|
let mut dma_buf: [u8; 16] = array::from_fn(|idx| idx as u8); // 0, 1, ..., 15
|
|
let mut ringbuf = DmaRingBuffer::new(&mut dma_buf);
|
|
|
|
assert_eq!(0, ringbuf.start);
|
|
assert_eq!(16, ringbuf.cap());
|
|
|
|
/*
|
|
Read to about the middle of the buffer
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(6),
|
|
TestCircularTransferRequest::PositionRequest(6),
|
|
TestCircularTransferRequest::GetCompleteCount(0),
|
|
]);
|
|
let mut buf = [0; 6];
|
|
assert_eq!(6, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!(6, ringbuf.start);
|
|
|
|
/*
|
|
Now, wrap the DMA controller around
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(6),
|
|
TestCircularTransferRequest::GetCompleteCount(1),
|
|
TestCircularTransferRequest::PositionRequest(6),
|
|
TestCircularTransferRequest::GetCompleteCount(1),
|
|
]);
|
|
let mut buf = [0; 6];
|
|
assert_eq!(6, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!(12, ringbuf.start);
|
|
}
|
|
|
|
#[test]
|
|
fn cannot_read_when_dma_writer_overwrites_during_not_wrapping_read() {
|
|
let mut dma = TestCircularTransfer::new(16);
|
|
|
|
let mut dma_buf: [u8; 16] = array::from_fn(|idx| idx as u8); // 0, 1, ..., 15
|
|
let mut ringbuf = DmaRingBuffer::new(&mut dma_buf);
|
|
|
|
assert_eq!(0, ringbuf.start);
|
|
assert_eq!(16, ringbuf.cap());
|
|
|
|
/*
|
|
Read a few bytes
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(2),
|
|
TestCircularTransferRequest::PositionRequest(2),
|
|
TestCircularTransferRequest::GetCompleteCount(0),
|
|
]);
|
|
let mut buf = [0; 6];
|
|
assert_eq!(2, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!(2, ringbuf.start);
|
|
|
|
/*
|
|
Now, overtake the reader
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(4),
|
|
TestCircularTransferRequest::PositionRequest(6),
|
|
TestCircularTransferRequest::GetCompleteCount(1),
|
|
]);
|
|
let mut buf = [0; 6];
|
|
assert_eq!(OverrunError, ringbuf.read(&mut dma, &mut buf).unwrap_err());
|
|
}
|
|
|
|
#[test]
|
|
fn cannot_read_when_dma_writer_overwrites_during_wrapping_read() {
|
|
let mut dma = TestCircularTransfer::new(16);
|
|
|
|
let mut dma_buf: [u8; 16] = array::from_fn(|idx| idx as u8); // 0, 1, ..., 15
|
|
let mut ringbuf = DmaRingBuffer::new(&mut dma_buf);
|
|
|
|
assert_eq!(0, ringbuf.start);
|
|
assert_eq!(16, ringbuf.cap());
|
|
|
|
/*
|
|
Read to close to the end of the buffer
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(14),
|
|
TestCircularTransferRequest::PositionRequest(16),
|
|
TestCircularTransferRequest::GetCompleteCount(0),
|
|
]);
|
|
let mut buf = [0; 14];
|
|
assert_eq!(14, ringbuf.read(&mut dma, &mut buf).unwrap().0);
|
|
assert_eq!(14, ringbuf.start);
|
|
|
|
/*
|
|
Now, overtake the reader
|
|
*/
|
|
dma.setup(vec![
|
|
TestCircularTransferRequest::PositionRequest(8),
|
|
TestCircularTransferRequest::PositionRequest(10),
|
|
TestCircularTransferRequest::ResetCompleteCount(2),
|
|
]);
|
|
let mut buf = [0; 6];
|
|
assert_eq!(OverrunError, ringbuf.read(&mut dma, &mut buf).unwrap_err());
|
|
}
|
|
}
|