max/embassy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

stm32: add some docs.

Browse Source
This commit is contained in:
Dario Nieuwenhuis
2023-12-17 22:09:14 +01:00
parent a2d4bab2f8
commit 80c9d04bbd
37 changed files with 544 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
embassy-stm32/src/dma/bdma.rs
View File

@ -1,4 +1,4 @@
#![macro_use]
//! Basic Direct Memory Acccess (BDMA)
use core::future::Future;
use core::pin::Pin;
@ -17,6 +17,7 @@ use crate::interrupt::Priority;
use crate::pac;
use crate::pac::bdma::{regs, vals};
/// BDMA transfer options.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[non_exhaustive]
@ -140,13 +141,17 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::bdma::Dma, channel_num: usize, index
STATE.ch_wakers[index].wake();
}
/// DMA request type alias.
#[cfg(any(bdma_v2, dmamux))]
pub type Request = u8;
/// DMA request type alias.
#[cfg(not(any(bdma_v2, dmamux)))]
pub type Request = ();
/// DMA channel.
#[cfg(dmamux)]
pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
/// DMA channel.
#[cfg(not(dmamux))]
pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
@ -161,12 +166,14 @@ pub(crate) mod sealed {
}
}
/// DMA transfer.
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Transfer<'a, C: Channel> {
channel: PeripheralRef<'a, C>,
}
impl<'a, C: Channel> Transfer<'a, C> {
/// Create a new read DMA transfer (peripheral to memory).
pub unsafe fn new_read<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -177,6 +184,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
Self::new_read_raw(channel, request, peri_addr, buf, options)
}
/// Create a new read DMA transfer (peripheral to memory), using raw pointers.
pub unsafe fn new_read_raw<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -202,6 +210,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
)
}
/// Create a new write DMA transfer (memory to peripheral).
pub unsafe fn new_write<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -212,6 +221,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
Self::new_write_raw(channel, request, buf, peri_addr, options)
}
/// Create a new write DMA transfer (memory to peripheral), using raw pointers.
pub unsafe fn new_write_raw<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -237,6 +247,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
)
}
/// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
pub unsafe fn new_write_repeated<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -321,6 +332,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
});
}
/// Request the transfer to stop.
///
/// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
pub fn request_stop(&mut self) {
let ch = self.channel.regs().ch(self.channel.num());
@ -331,6 +345,10 @@ impl<'a, C: Channel> Transfer<'a, C> {
});
}
/// Return whether this transfer is still running.
///
/// If this returns `false`, it can be because either the transfer finished, or
/// it was requested to stop early with [`request_stop`](Self::request_stop).
pub fn is_running(&mut self) -> bool {
let ch = self.channel.regs().ch(self.channel.num());
let en = ch.cr().read().en();
@ -339,13 +357,15 @@ impl<'a, C: Channel> Transfer<'a, C> {
en && (circular || !tcif)
}
/// Gets the total remaining transfers for the channel
/// Note: this will be zero for transfers that completed without cancellation.
/// Get the total remaining transfers for the channel.
///
/// This will be zero for transfers that completed instead of being canceled with [`request_stop`](Self::request_stop).
pub fn get_remaining_transfers(&self) -> u16 {
let ch = self.channel.regs().ch(self.channel.num());
ch.ndtr().read().ndt()
}
/// Blocking wait until the transfer finishes.
pub fn blocking_wait(mut self) {
while self.is_running() {}
self.request_stop();
@ -411,6 +431,7 @@ impl<'a, C: Channel> DmaCtrl for DmaCtrlImpl<'a, C> {
}
}
/// Ringbuffer for reading data using DMA circular mode.
pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
cr: regs::Cr,
channel: PeripheralRef<'a, C>,
@ -418,7 +439,8 @@ pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
}
impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
pub unsafe fn new_read(
/// Create a new ring buffer.
pub unsafe fn new(
channel: impl Peripheral<P = C> + 'a,
_request: Request,
peri_addr: *mut W,
@ -473,11 +495,15 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
this
}
/// Start the ring buffer operation.
///
/// You must call this after creating it for it to work.
pub fn start(&mut self) {
let ch = self.channel.regs().ch(self.channel.num());
ch.cr().write_value(self.cr)
}
/// Clear all data in the ring buffer.
pub fn clear(&mut self) {
self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
}
@ -509,10 +535,11 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
}
/// The capacity of the ringbuffer.
pub const fn cap(&self) -> usize {
pub const fn capacity(&self) -> usize {
self.ringbuf.cap()
}
/// Set a waker to be woken when at least one byte is received.
pub fn set_waker(&mut self, waker: &Waker) {
DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
}
@ -526,6 +553,9 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
});
}
/// Request DMA to stop.
///
/// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
pub fn request_stop(&mut self) {
let ch = self.channel.regs().ch(self.channel.num());
@ -539,6 +569,10 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
});
}
/// Return whether DMA is still running.
///
/// If this returns `false`, it can be because either the transfer finished, or
/// it was requested to stop early with [`request_stop`](Self::request_stop).
pub fn is_running(&mut self) -> bool {
let ch = self.channel.regs().ch(self.channel.num());
ch.cr().read().en()
@ -555,6 +589,7 @@ impl<'a, C: Channel, W: Word> Drop for ReadableRingBuffer<'a, C, W> {
}
}
/// Ringbuffer for writing data using DMA circular mode.
pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
cr: regs::Cr,
channel: PeripheralRef<'a, C>,
@ -562,7 +597,8 @@ pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
}
impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
pub unsafe fn new_write(
/// Create a new ring buffer.
pub unsafe fn new(
channel: impl Peripheral<P = C> + 'a,
_request: Request,
peri_addr: *mut W,
@ -617,11 +653,15 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
this
}
/// Start the ring buffer operation.
///
/// You must call this after creating it for it to work.
pub fn start(&mut self) {
let ch = self.channel.regs().ch(self.channel.num());
ch.cr().write_value(self.cr)
}
/// Clear all data in the ring buffer.
pub fn clear(&mut self) {
self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
}
@ -640,10 +680,11 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
}
/// The capacity of the ringbuffer.
pub const fn cap(&self) -> usize {
pub const fn capacity(&self) -> usize {
self.ringbuf.cap()
}
/// Set a waker to be woken when at least one byte is sent.
pub fn set_waker(&mut self, waker: &Waker) {
DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
}
@ -657,6 +698,9 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
});
}
/// Request DMA to stop.
///
/// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
pub fn request_stop(&mut self) {
let ch = self.channel.regs().ch(self.channel.num());
@ -670,6 +714,10 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
});
}
/// Return whether DMA is still running.
///
/// If this returns `false`, it can be because either the transfer finished, or
/// it was requested to stop early with [`request_stop`](Self::request_stop).
pub fn is_running(&mut self) -> bool {
let ch = self.channel.regs().ch(self.channel.num());
ch.cr().read().en()

79
embassy-stm32/src/dma/dma.rs
View File

@ -16,6 +16,7 @@ use crate::interrupt::Priority;
use crate::pac::dma::{regs, vals};
use crate::{interrupt, pac};
/// DMA transfer options.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[non_exhaustive]
@ -69,6 +70,7 @@ impl From<Dir> for vals::Dir {
}
}
/// DMA transfer burst setting.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum Burst {
@ -93,6 +95,7 @@ impl From<Burst> for vals::Burst {
}
}
/// DMA flow control setting.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum FlowControl {
@ -111,6 +114,7 @@ impl From<FlowControl> for vals::Pfctrl {
}
}
/// DMA FIFO threshold.
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum FifoThreshold {
@ -208,13 +212,17 @@ pub(crate) unsafe fn on_irq_inner(dma: pac::dma::Dma, channel_num: usize, index:
STATE.ch_wakers[index].wake();
}
/// DMA request type alias. (also known as DMA channel number in some chips)
#[cfg(any(dma_v2, dmamux))]
pub type Request = u8;
/// DMA request type alias. (also known as DMA channel number in some chips)
#[cfg(not(any(dma_v2, dmamux)))]
pub type Request = ();
/// DMA channel.
#[cfg(dmamux)]
pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static + super::dmamux::MuxChannel {}
/// DMA channel.
#[cfg(not(dmamux))]
pub trait Channel: sealed::Channel + Peripheral<P = Self> + 'static {}
@ -229,12 +237,14 @@ pub(crate) mod sealed {
}
}
/// DMA transfer.
#[must_use = "futures do nothing unless you `.await` or poll them"]
pub struct Transfer<'a, C: Channel> {
channel: PeripheralRef<'a, C>,
}
impl<'a, C: Channel> Transfer<'a, C> {
/// Create a new read DMA transfer (peripheral to memory).
pub unsafe fn new_read<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -245,6 +255,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
Self::new_read_raw(channel, request, peri_addr, buf, options)
}
/// Create a new read DMA transfer (peripheral to memory), using raw pointers.
pub unsafe fn new_read_raw<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -270,6 +281,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
)
}
/// Create a new write DMA transfer (memory to peripheral).
pub unsafe fn new_write<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -280,6 +292,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
Self::new_write_raw(channel, request, buf, peri_addr, options)
}
/// Create a new write DMA transfer (memory to peripheral), using raw pointers.
pub unsafe fn new_write_raw<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -305,6 +318,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
)
}
/// Create a new write DMA transfer (memory to peripheral), writing the same value repeatedly.
pub unsafe fn new_write_repeated<W: Word>(
channel: impl Peripheral<P = C> + 'a,
request: Request,
@ -407,6 +421,9 @@ impl<'a, C: Channel> Transfer<'a, C> {
});
}
/// Request the transfer to stop.
///
/// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
pub fn request_stop(&mut self) {
let ch = self.channel.regs().st(self.channel.num());
@ -417,6 +434,10 @@ impl<'a, C: Channel> Transfer<'a, C> {
});
}
/// Return whether this transfer is still running.
///
/// If this returns `false`, it can be because either the transfer finished, or
/// it was requested to stop early with [`request_stop`](Self::request_stop).
pub fn is_running(&mut self) -> bool {
let ch = self.channel.regs().st(self.channel.num());
ch.cr().read().en()
@ -429,6 +450,7 @@ impl<'a, C: Channel> Transfer<'a, C> {
ch.ndtr().read().ndt()
}
/// Blocking wait until the transfer finishes.
pub fn blocking_wait(mut self) {
while self.is_running() {}
@ -465,12 +487,14 @@ impl<'a, C: Channel> Future for Transfer<'a, C> {
// ==================================
/// Double-buffered DMA transfer.
pub struct DoubleBuffered<'a, C: Channel, W: Word> {
channel: PeripheralRef<'a, C>,
_phantom: PhantomData<W>,
}
impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
/// Create a new read DMA transfer (peripheral to memory).
pub unsafe fn new_read(
channel: impl Peripheral<P = C> + 'a,
_request: Request,
@ -554,25 +578,36 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
});
}
/// Set the first buffer address.
///
/// You may call this while DMA is transferring the other buffer.
pub unsafe fn set_buffer0(&mut self, buffer: *mut W) {
let ch = self.channel.regs().st(self.channel.num());
ch.m0ar().write_value(buffer as _);
}
/// Set the second buffer address.
///
/// You may call this while DMA is transferring the other buffer.
pub unsafe fn set_buffer1(&mut self, buffer: *mut W) {
let ch = self.channel.regs().st(self.channel.num());
ch.m1ar().write_value(buffer as _);
}
/// Returh whether buffer0 is accessible (i.e. whether DMA is transferring buffer1 now)
pub fn is_buffer0_accessible(&mut self) -> bool {
let ch = self.channel.regs().st(self.channel.num());
ch.cr().read().ct() == vals::Ct::MEMORY1
}
/// Set a waker to be woken when one of the buffers is being transferred.
pub fn set_waker(&mut self, waker: &Waker) {
STATE.ch_wakers[self.channel.index()].register(waker);
}
/// Request the transfer to stop.
///
/// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
pub fn request_stop(&mut self) {
let ch = self.channel.regs().st(self.channel.num());
@ -583,6 +618,10 @@ impl<'a, C: Channel, W: Word> DoubleBuffered<'a, C, W> {
});
}
/// Return whether this transfer is still running.
///
/// If this returns `false`, it can be because either the transfer finished, or
/// it was requested to stop early with [`request_stop`](Self::request_stop).
pub fn is_running(&mut self) -> bool {
let ch = self.channel.regs().st(self.channel.num());
ch.cr().read().en()
@ -629,6 +668,7 @@ impl<'a, C: Channel> DmaCtrl for DmaCtrlImpl<'a, C> {
}
}
/// Ringbuffer for receiving data using DMA circular mode.
pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
cr: regs::Cr,
channel: PeripheralRef<'a, C>,
@ -636,7 +676,8 @@ pub struct ReadableRingBuffer<'a, C: Channel, W: Word> {
}
impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
pub unsafe fn new_read(
/// Create a new ring buffer.
pub unsafe fn new(
channel: impl Peripheral<P = C> + 'a,
_request: Request,
peri_addr: *mut W,
@ -706,11 +747,15 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
this
}
/// Start the ring buffer operation.
///
/// You must call this after creating it for it to work.
pub fn start(&mut self) {
let ch = self.channel.regs().st(self.channel.num());
ch.cr().write_value(self.cr);
}
/// Clear all data in the ring buffer.
pub fn clear(&mut self) {
self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
}
@ -741,11 +786,12 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
.await
}
// The capacity of the ringbuffer
pub const fn cap(&self) -> usize {
/// The capacity of the ringbuffer
pub const fn capacity(&self) -> usize {
self.ringbuf.cap()
}
/// Set a waker to be woken when at least one byte is received.
pub fn set_waker(&mut self, waker: &Waker) {
DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
}
@ -763,6 +809,9 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
});
}
/// Request DMA to stop.
///
/// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
pub fn request_stop(&mut self) {
let ch = self.channel.regs().st(self.channel.num());
@ -774,6 +823,10 @@ impl<'a, C: Channel, W: Word> ReadableRingBuffer<'a, C, W> {
});
}
/// Return whether DMA is still running.
///
/// If this returns `false`, it can be because either the transfer finished, or
/// it was requested to stop early with [`request_stop`](Self::request_stop).
pub fn is_running(&mut self) -> bool {
let ch = self.channel.regs().st(self.channel.num());
ch.cr().read().en()
@ -790,6 +843,7 @@ impl<'a, C: Channel, W: Word> Drop for ReadableRingBuffer<'a, C, W> {
}
}
/// Ringbuffer for writing data using DMA circular mode.
pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
cr: regs::Cr,
channel: PeripheralRef<'a, C>,
@ -797,7 +851,8 @@ pub struct WritableRingBuffer<'a, C: Channel, W: Word> {
}
impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
pub unsafe fn new_write(
/// Create a new ring buffer.
pub unsafe fn new(
channel: impl Peripheral<P = C> + 'a,
_request: Request,
peri_addr: *mut W,
@ -867,11 +922,15 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
this
}
/// Start the ring buffer operation.
///
/// You must call this after creating it for it to work.
pub fn start(&mut self) {
let ch = self.channel.regs().st(self.channel.num());
ch.cr().write_value(self.cr);
}
/// Clear all data in the ring buffer.
pub fn clear(&mut self) {
self.ringbuf.clear(&mut DmaCtrlImpl(self.channel.reborrow()));
}
@ -889,11 +948,12 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
.await
}
// The capacity of the ringbuffer
pub const fn cap(&self) -> usize {
/// The capacity of the ringbuffer
pub const fn capacity(&self) -> usize {
self.ringbuf.cap()
}
/// Set a waker to be woken when at least one byte is received.
pub fn set_waker(&mut self, waker: &Waker) {
DmaCtrlImpl(self.channel.reborrow()).set_waker(waker);
}
@ -911,6 +971,9 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
});
}
/// Request DMA to stop.
///
/// This doesn't immediately stop the transfer, you have to wait until [`is_running`](Self::is_running) returns false.
pub fn request_stop(&mut self) {
let ch = self.channel.regs().st(self.channel.num());
@ -922,6 +985,10 @@ impl<'a, C: Channel, W: Word> WritableRingBuffer<'a, C, W> {
});
}
/// Return whether DMA is still running.
///
/// If this returns `false`, it can be because either the transfer finished, or
/// it was requested to stop early with [`request_stop`](Self::request_stop).
pub fn is_running(&mut self) -> bool {
let ch = self.channel.regs().st(self.channel.num());
ch.cr().read().en()

4
embassy-stm32/src/dma/dmamux.rs
View File

@ -22,11 +22,15 @@ pub(crate) mod dmamux_sealed {
}
}
/// DMAMUX1 instance.
pub struct DMAMUX1;
/// DMAMUX2 instance.
#[cfg(stm32h7)]
pub struct DMAMUX2;
/// DMAMUX channel trait.
pub trait MuxChannel: dmamux_sealed::MuxChannel {
/// DMAMUX instance this channel is on.
type Mux;
}

7
embassy-stm32/src/dma/mod.rs
View File

@ -39,6 +39,13 @@ enum Dir {
PeripheralToMemory,
}
/// "No DMA" placeholder.
///
/// You may pass this in place of a real DMA channel when creating a driver
/// to indicate it should not use DMA.
///
/// This often causes async functionality to not be available on the instance,
/// leaving only blocking functionality.
pub struct NoDma;
impl_peripheral!(NoDma);

10
embassy-stm32/src/dma/word.rs
View File

@ -1,3 +1,6 @@
//! DMA word sizes.
#[allow(missing_docs)]
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum WordSize {
@ -7,6 +10,7 @@ pub enum WordSize {
}
impl WordSize {
/// Amount of bytes of this word size.
pub fn bytes(&self) -> usize {
match self {
Self::OneByte => 1,
@ -20,8 +24,13 @@ mod sealed {
pub trait Word {}
}
/// DMA word trait.
///
/// This is implemented for u8, u16, u32, etc.
pub trait Word: sealed::Word + Default + Copy + 'static {
/// Word size
fn size() -> WordSize;
/// Amount of bits of this word size.
fn bits() -> usize;
}
@ -40,6 +49,7 @@ macro_rules! impl_word {
($T:ident, $uX:ident, $bits:literal, $size:ident) => {
#[repr(transparent)]
#[derive(Copy, Clone, Default)]
#[doc = concat!(stringify!($T), " word size")]
pub struct $T(pub $uX);
impl_word!(_, $T, $bits, $size);
};