gd32e2-hal 0.26.0

//! Direct memory access: five independent channels moving data without the core.
//!
//! [`DmaExt::split`] consumes the peripheral and hands out one [`Channel`] per
//! hardware channel:
//!
//! ```ignore
//! let channels = dp.dma.split(&mut rcu);
//! let transfer = channels.ch1.write_to(usart, b"hello", Prio::Low);
//! let (ch1, usart, _) = transfer.wait();
//! ```

use core::marker::PhantomData;
use core::mem::ManuallyDrop;
use core::ptr;

use crate::adc::Adc;
use crate::pac;
use crate::rcu::{Enable, Rcu};
use crate::spi::{self, Spi};
use crate::usart::{self, Usart};

/// Channel priority when several channels contend for the bus.
///
/// Affects only arbitration latency, never the correctness of a single transfer.
#[derive(Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[allow(missing_docs)]
pub enum Prio {
    Low,
    Medium,
    High,
    UltraHigh,
}

/// Transfer direction, selecting the `DIR` bit.
pub(crate) enum Dir {
    /// Peripheral to memory.
    P2M,
    /// Memory to peripheral.
    M2P,
}

/// Width of one transferred unit, selecting `PWIDTH`/`MWIDTH`.
#[derive(Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[allow(missing_docs)]
pub enum Width {
    Bits8,
    Bits16,
    Bits32,
}

/// One DMA channel, identified by its number at the type level.
pub struct Channel<const N: u8> {
    _marker: PhantomData<()>,
}

impl<const N: u8> Channel<N> {
    #[allow(clippy::unused_self)]
    fn reg(&self) -> &pac::dma::RegisterBlock {
        // SAFETY: the block lives at a fixed address for the whole program; a
        // channel touches its own registers and its own bits of the shared ones.
        unsafe { &*pac::Dma::ptr() }
    }
}

/// The raw per-channel register operations, generated by the `channels!` macro.
pub(crate) trait ChannelOps {
    fn configure(&mut self, dir: Dir, width: Width, prio: Prio);
    fn set_paddr(&mut self, addr: u32);
    fn set_maddr(&mut self, addr: u32);
    fn set_cnt(&mut self, cnt: u16);
    fn cnt(&self) -> u16;
    fn set_enabled(&mut self, enabled: bool);
    fn is_complete(&self) -> bool;
    fn is_error(&self) -> bool;
    fn clear_flags(&mut self);
}

macro_rules! channels {
    ($($N:literal),+ $(,)?) => {
        paste::paste! { $(
            impl ChannelOps for Channel<$N> {
                /// Writes the whole of `CHxCTL` in one go: direction, width,
                /// priority, memory increment on, peripheral increment off, and
                /// M2M/circular/interrupts off.
                ///
                /// A `write`, not a `modify`, so leftover bits from an earlier use
                /// reset to zero. Must run while `CHEN` is 0.
                #[inline]
                fn configure(&mut self, dir: Dir, width: Width, prio: Prio) {
                    self.reg().[<ch $N ctl>]().write(|w| {
                        let w = w.pnaga()
                                 .fixed()
                                 .mnaga()
                                 .increment()
                                 .m2m()
                                 .disabled()
                                 .cmen()
                                 .disabled()
                                 .errie()
                                 .disabled()
                                 .htfie()
                                 .disabled()
                                 .ftfie()
                                 .disabled();
                        let w = match dir {
                            Dir::P2M => w.dir().from_peripheral(),
                            Dir::M2P => w.dir().from_memory(),
                        };
                        let w = match width {
                            Width::Bits8 => w.mwidth().bits8().pwidth().bits8(),
                            Width::Bits16 => w.mwidth().bits16().pwidth().bits16(),
                            Width::Bits32 => w.mwidth().bits32().pwidth().bits32(),
                        };
                        match prio {
                            Prio::Low => w.prio().low(),
                            Prio::Medium => w.prio().medium(),
                            Prio::High => w.prio().high(),
                            Prio::UltraHigh => w.prio().very_high(),
                        }
                    });
                }
                /// Points the channel at the peripheral data register.
                #[inline]
                fn set_paddr(&mut self, addr: u32) {
                    // SAFETY: `addr` comes from `DmaPeriph::addr`, a data register.
                    self.reg().[<ch $N paddr>]().write(|w| unsafe { w.bits(addr) });
                }
                /// Points the channel at the memory buffer.
                #[inline]
                fn set_maddr(&mut self, addr: u32) {
                    // SAFETY: `addr` comes from a `'static` buffer of the
                    // transfer's word type.
                    self.reg().[<ch $N maddr>]().write(|w| unsafe { w.bits(addr) });
                }
                /// Sets how many transfers the channel performs.
                #[inline]
                fn set_cnt(&mut self, cnt: u16) {
                    self.reg().[<ch $N cnt>]().write(|w| w.cnt().bits(cnt));
                }
                /// Transfers still outstanding; counts down as the channel runs.
                #[inline]
                fn cnt(&self) -> u16 {
                    self.reg().[<ch $N cnt>]().read().cnt().bits()
                }
                /// Starts or stops the channel.
                #[inline]
                fn set_enabled(&mut self, enabled: bool) {
                    self.reg().[<ch $N ctl>]().modify(|_, w| w.chen().bit(enabled));
                }
                /// Whether the channel has finished its last transfer.
                #[inline]
                fn is_complete(&self) -> bool {
                    self.reg().intf().read().[<ftfif $N>]().bit_is_set()
                }
                /// Whether the channel hit a bus error.
                #[inline]
                fn is_error(&self) -> bool {
                    self.reg().intf().read().[<errif $N>]().bit_is_set()
                }
                /// Clears every interrupt flag of this channel.
                #[inline]
                fn clear_flags(&mut self) {
                    self.reg().intc().write(|w| w.[<gifc $N>]().set_bit());
                }
            }
        )+ }
    };
}

channels!(0, 1, 2, 3, 4);

/// A type usable as a DMA transfer unit, mapping to its [`Width`].
///
/// Bounds the peripheral's word type so only `u8`/`u16`/`u32` qualify, and
/// carries the [`Width`] that a channel writes into `PWIDTH`/`MWIDTH`.
pub trait DmaWord {
    /// The transfer width of this type.
    const WIDTH: Width;
}

impl DmaWord for u8 {
    const WIDTH: Width = Width::Bits8;
}
impl DmaWord for u16 {
    const WIDTH: Width = Width::Bits16;
}
impl DmaWord for u32 {
    const WIDTH: Width = Width::Bits32;
}

/// Everything a channel needs from the peripheral on the other end of it.
pub trait DmaPeriph<const N: u8> {
    /// The word type this peripheral transfers, fixing `PWIDTH`/`MWIDTH`.
    type Word: DmaWord;
    /// Address of the peripheral's data register.
    fn addr(&self) -> u32;
    /// Lets the peripheral raise DMA requests on its channel.
    ///
    /// Until this is called the channel is configured but never asked to move
    /// anything, so a transfer would sit at its full count forever.
    fn enable_dma(&mut self);
    /// Stops the peripheral raising DMA requests.
    ///
    /// Called before the peripheral goes back to its owner, so it is handed over
    /// in the state it arrived in rather than still driving a dead channel.
    fn disable_dma(&mut self);
}

/// A peripheral channel `N` can read from, for peripheral-to-memory transfers.
pub trait DmaSrc<const N: u8>: DmaPeriph<N> {}

/// A peripheral channel `N` can write to, for memory-to-peripheral transfers.
pub trait DmaDst<const N: u8>: DmaPeriph<N> {}

// Request mapping, Table 8-3. Entries marked (1) apply while the SYSCFG_CFG0
// remap bit is clear (the reset state), (2) while it is set. Only (1) is
// implemented: the two are mutually exclusive at runtime, so implementing both
// would let either choice compile while one is wired. Requests with no impl yet
// are listed for completeness.
//
//   Ch0: ADC(1), TIMER16_CH0(1), TIMER16_UP(1)
//   Ch1: ADC(2), SPI/I2S0_RX, USART0_TX(1), I2C0_TX, TIMER0_CH0, TIMER2_CH2,
//        TIMER16_CH0(2), TIMER16_UP(2)
//   Ch2: SPI/I2S0_TX, USART0_RX(1), I2C0_RX, TIMER0_CH1, TIMER2_CH3, TIMER2_UP,
//        TIMER5_UP, TIMER15_CH0(1), TIMER15_UP(1)
//   Ch3: SPI1_RX, USART0_TX(2), USART1_TX, I2C1_TX, TIMER0_CH3, TIMER0_TRIG,
//        TIMER0_COM, TIMER2_CH0, TIMER2_TRIG, TIMER15_CH0(2), TIMER15_UP(2)
//   Ch4: SPI1_TX, USART0_RX(2), USART1_RX, I2C1_RX, TIMER0_CH2, TIMER0_UP,
//        TIMER14_CH0, TIMER14_UP, TIMER14_TRIG, TIMER14_COM, TIMER14_CH1
macro_rules! dma_map {
    ($($Trait:ident<$N:literal> for $Ty:ty, $W:ty, $Periph:ty, $reg:ident,
                     $ctl:ident, $den:ident, [$($gen:ident),*];)+) => {
        $(
            impl<$($gen),*> DmaPeriph<$N> for $Ty {
                type Word = $W;
                fn addr(&self) -> u32 {
                    // SAFETY: the block lives at a fixed address for the whole
                    // program, and only the register's address is taken.
                    unsafe { (*<$Periph>::ptr()).$reg().as_ptr() as u32 }
                }
                fn enable_dma(&mut self) {
                    // SAFETY: `self` owns the peripheral, and `&mut self` rules
                    // out another access to it.
                    unsafe { (*<$Periph>::ptr()).$ctl().modify(|_, w| w.$den().set_bit()) };
                }
                fn disable_dma(&mut self) {
                    // SAFETY: `self` owns the peripheral, and `&mut self` rules
                    // out another access to it.
                    unsafe { (*<$Periph>::ptr()).$ctl().modify(|_, w| w.$den().clear_bit()) };
                }
            }
            impl<$($gen),*> $Trait<$N> for $Ty {}
        )+
    };
}

dma_map! {
    DmaSrc<0> for Adc, u16, pac::Adc, rdata, ctl1, dma, [];

    DmaSrc<1> for Spi<pac::Spi0, SCK, MISO, MOSI, spi::Byte>, u8, pac::Spi0, data, ctl1, dmaren, [SCK, MISO, MOSI];
    DmaSrc<1> for Spi<pac::Spi0, SCK, MISO, MOSI, spi::Word>, u16, pac::Spi0, data, ctl1, dmaren, [SCK, MISO, MOSI];
    DmaDst<1> for Usart<pac::Usart0, TX, RX, usart::Byte>, u8, pac::Usart0, tdata, ctl2, dent, [TX, RX];
    DmaDst<1> for Usart<pac::Usart0, TX, RX, usart::Word>, u16, pac::Usart0, tdata, ctl2, dent, [TX, RX];

    DmaDst<2> for Spi<pac::Spi0, SCK, MISO, MOSI, spi::Byte>, u8, pac::Spi0, data, ctl1, dmaten, [SCK, MISO, MOSI];
    DmaDst<2> for Spi<pac::Spi0, SCK, MISO, MOSI, spi::Word>, u16, pac::Spi0, data, ctl1, dmaten, [SCK, MISO, MOSI];
    DmaSrc<2> for Usart<pac::Usart0, TX, RX, usart::Byte>, u8, pac::Usart0, rdata, ctl2, denr, [TX, RX];
    DmaSrc<2> for Usart<pac::Usart0, TX, RX, usart::Word>, u16, pac::Usart0, rdata, ctl2, denr, [TX, RX];

    DmaSrc<3> for Spi<pac::Spi1, SCK, MISO, MOSI, spi::Byte>, u8, pac::Spi1, data, ctl1, dmaren, [SCK, MISO, MOSI];
    DmaSrc<3> for Spi<pac::Spi1, SCK, MISO, MOSI, spi::Word>, u16, pac::Spi1, data, ctl1, dmaren, [SCK, MISO, MOSI];
    DmaDst<3> for Usart<pac::Usart1, TX, RX, usart::Byte>, u8, pac::Usart1, tdata, ctl2, dent, [TX, RX];
    DmaDst<3> for Usart<pac::Usart1, TX, RX, usart::Word>, u16, pac::Usart1, tdata, ctl2, dent, [TX, RX];

    DmaDst<4> for Spi<pac::Spi1, SCK, MISO, MOSI, spi::Byte>, u8, pac::Spi1, data, ctl1, dmaten, [SCK, MISO, MOSI];
    DmaDst<4> for Spi<pac::Spi1, SCK, MISO, MOSI, spi::Word>, u16, pac::Spi1, data, ctl1, dmaten, [SCK, MISO, MOSI];
    DmaSrc<4> for Usart<pac::Usart1, TX, RX, usart::Byte>, u8, pac::Usart1, rdata, ctl2, denr, [TX, RX];
    DmaSrc<4> for Usart<pac::Usart1, TX, RX, usart::Word>, u16, pac::Usart1, rdata, ctl2, denr, [TX, RX];
}

// The bound is what restricts N to the five channels that have an impl.
#[allow(private_bounds)]
impl<const N: u8> Channel<N>
where
    Channel<N>: ChannelOps,
{
    /// Starts a memory-to-peripheral transfer, moving `buf` into `periph`.
    ///
    /// All three are taken by value and come back from [`Transfer::wait`]. The
    /// transfer width follows from the peripheral's word type, so `buf` must
    /// match it.
    pub fn write_to<P: DmaDst<N>>(
        mut self,
        mut periph: P,
        buf: &'static [P::Word],
        prio: Prio,
    ) -> Transfer<N, P, &'static [P::Word]> {
        self.set_maddr(buf.as_ptr() as u32);
        self.set_paddr(periph.addr());
        self.set_cnt(buf.len() as u16);
        self.configure(Dir::M2P, <P::Word as DmaWord>::WIDTH, prio);
        self.set_enabled(true);
        periph.enable_dma();
        Transfer {
            channel: self,
            periph,
            buf,
        }
    }
    /// Starts a peripheral-to-memory transfer, filling `buf` from `periph`.
    ///
    /// All three are taken by value and come back from [`Transfer::wait`], so
    /// `buf` cannot be read before the transfer completes. The transfer width
    /// follows from the peripheral's word type, so `buf` must match it.
    pub fn read_from<P: DmaSrc<N>>(
        mut self,
        mut periph: P,
        buf: &'static mut [P::Word],
        prio: Prio,
    ) -> Transfer<N, P, &'static mut [P::Word]> {
        self.set_maddr(buf.as_mut_ptr() as u32);
        self.set_paddr(periph.addr());
        self.set_cnt(buf.len() as u16);
        self.configure(Dir::P2M, <P::Word as DmaWord>::WIDTH, prio);
        self.set_enabled(true);
        periph.enable_dma();
        Transfer {
            channel: self,
            periph,
            buf,
        }
    }
}

/// A DMA transfer in progress, started by [`Channel::write_to`] or
/// [`read_from`](Channel::read_from).
///
/// Owns the channel, the peripheral and the buffer for as long as the transfer
/// runs; [`wait`](Transfer::wait) is the only way to get them back.
///
/// Dropping instead of waiting stops the transfer and loses all three parts.
// The bounds sit on the declaration only because `Drop` demands it: a `Drop` impl
// may not require more than the type it drops.
#[allow(private_bounds)]
#[must_use = "dropping a `Transfer` stops it at once; `wait` lets it finish"]
pub struct Transfer<const N: u8, P, BUF>
where
    Channel<N>: ChannelOps,
    P: DmaPeriph<N>,
{
    channel: Channel<N>,
    periph: P,
    buf: BUF,
}

// The bound is what restricts N to the five channels that have an impl.
#[allow(private_bounds)]
impl<const N: u8, P, BUF> Transfer<N, P, BUF>
where
    Channel<N>: ChannelOps,
    P: DmaPeriph<N>,
{
    /// Blocks until the transfer completes, then returns the channel, the
    /// peripheral and the buffer.
    ///
    /// Does not check `ERRIF`: every address this API can hand a channel comes
    /// from a typed source, so a bus error is unreachable through safe code.
    pub fn wait(mut self) -> (Channel<N>, P, BUF) {
        while !self.channel.is_complete() {}
        self.periph.disable_dma();
        self.channel.set_enabled(false);
        self.channel.clear_flags();
        let transfer = ManuallyDrop::new(self);
        // SAFETY: the parts are read out rather than moved out, because a type
        // with a `Drop` impl cannot be taken apart. `ManuallyDrop` is what makes
        // the duplicated ownership sound: the originals are never dropped, never
        // used again, and go out of scope with this expression.
        unsafe {
            (
                ptr::read(&raw const transfer.channel),
                ptr::read(&raw const transfer.periph),
                ptr::read(&raw const transfer.buf),
            )
        }
    }
    /// How many transfers the channel has left, without waiting for it.
    ///
    /// Counts transfers, not bytes: at [`Width::Bits16`] a unit is two bytes on
    /// the wire. A snapshot only — the hardware keeps counting while the caller
    /// looks at it, so it serves progress reporting.
    pub fn remaining(&self) -> u16 {
        self.channel.cnt()
    }
    /// Whether the channel has raised `ERRIF`, having hit a bus error.
    ///
    /// Useful next to [`remaining`](Transfer::remaining) to tell a stalled
    /// channel from a failed one.
    pub fn is_error(&self) -> bool {
        self.channel.is_error()
    }
}

#[allow(private_bounds)]
impl<const N: u8, P, BUF> Drop for Transfer<N, P, BUF>
where
    Channel<N>: ChannelOps,
    P: DmaPeriph<N>,
{
    /// Stops the transfer where it stands, without waiting for it to finish.
    ///
    /// The tail of [`wait`](Transfer::wait) without the blocking: a running
    /// channel is cut off mid-buffer.
    fn drop(&mut self) {
        self.periph.disable_dma();
        self.channel.set_enabled(false);
        self.channel.clear_flags();
    }
}

/// The DMA channels, as handed out by [`DmaExt::split`].
#[allow(missing_docs)]
pub struct Channels {
    pub ch0: Channel<0>,
    pub ch1: Channel<1>,
    pub ch2: Channel<2>,
    pub ch3: Channel<3>,
    pub ch4: Channel<4>,
}

/// Splits the DMA peripheral into its individual channels.
pub trait DmaExt {
    /// The channels this peripheral hands out.
    type Channels;

    /// Switches the DMA clock on and hands out the channels.
    ///
    /// Consumes the peripheral, so the channels it returns are the only ones
    /// that will ever exist.
    fn split(self, rcu: &mut Rcu) -> Self::Channels;
}

impl DmaExt for pac::Dma {
    type Channels = Channels;
    fn split(self, rcu: &mut Rcu) -> Self::Channels {
        <pac::Dma as Enable>::enable(rcu);
        Channels {
            ch0: Channel {
                _marker: PhantomData,
            },
            ch1: Channel {
                _marker: PhantomData,
            },
            ch2: Channel {
                _marker: PhantomData,
            },
            ch3: Channel {
                _marker: PhantomData,
            },
            ch4: Channel {
                _marker: PhantomData,
            },
        }
    }
}