Merge branch 'main' into main

author: Raul Alimbekov <[email protected]> 2025-12-16 09:05:22 +0300
committer: GitHub <[email protected]> 2025-12-16 09:05:22 +0300
commit: c9a04b4b732b7a3b696eb8223664c1a7942b1875 (patch)
tree: 6dbe5c02e66eed8d8762f13f95afd24f8db2b38c /embassy-mcxa/src/dma.rs
parent: cde24a3ef1117653ba5ed4184102b33f745782fb (diff)
parent: 5ae6e060ec1c90561719aabdc29d5b6e7b8b0a82 (diff)
1 files changed, 2602 insertions, 0 deletions
diff --git a/embassy-mcxa/src/dma.rs b/embassy-mcxa/src/dma.rs
new file mode 100644
index 000000000..8d519d99b
--- /dev/null
+++ b/embassy-mcxa/src/dma.rs
@@ -0,0 +1,2602 @@
+//! DMA driver for MCXA276.
+//!
+//! This module provides a typed channel abstraction over the EDMA_0_TCD0 array
+//! and helpers for configuring the channel MUX. The driver supports both
+//! low-level TCD configuration and higher-level async transfer APIs.
+//!
+//! # Architecture
+//!
+//! The MCXA276 has 8 DMA channels (0-7), each with its own interrupt vector.
+//! Each channel has a Transfer Control Descriptor (TCD) that defines the
+//! transfer parameters.
+//!
+//! # Choosing the Right API
+//!
+//! This module provides several API levels to match different use cases:
+//!
+//! ## High-Level Async API (Recommended for Most Users)
+//!
+//! Use the async methods when you want simple, safe DMA transfers:
+//!
+//! | Method | Description |
+//! |--------|-------------|
+//! | [`DmaChannel::mem_to_mem()`] | Memory-to-memory copy |
+//! | [`DmaChannel::memset()`] | Fill memory with a pattern |
+//! | [`DmaChannel::write()`] | Memory-to-peripheral (TX) |
+//! | [`DmaChannel::read()`] | Peripheral-to-memory (RX) |
+//!
+//! These return a [`Transfer`] future that can be `.await`ed:
+//!
+//! ```no_run
+//! # use embassy_mcxa::dma::{DmaChannel, TransferOptions};
+//! # let dma_ch = DmaChannel::new(p.DMA_CH0);
+//! # let src = [0u32; 4];
+//! # let mut dst = [0u32; 4];
+//! // Simple memory-to-memory transfer
+//! unsafe {
+//!     dma_ch.mem_to_mem(&src, &mut dst, TransferOptions::default()).await;
+//! }
+//! ```
+//!
+//! ## Setup Methods (For Peripheral Drivers)
+//!
+//! Use setup methods when you need manual lifecycle control:
+//!
+//! | Method | Description |
+//! |--------|-------------|
+//! | [`DmaChannel::setup_write()`] | Configure TX without starting |
+//! | [`DmaChannel::setup_read()`] | Configure RX without starting |
+//!
+//! These configure the TCD but don't start the transfer. You control:
+//! 1. When to call [`DmaChannel::enable_request()`]
+//! 2. How to detect completion (polling or interrupts)
+//! 3. When to clean up with [`DmaChannel::clear_done()`]
+//!
+//! ## Circular/Ring Buffer API (For Continuous Reception)
+//!
+//! Use [`DmaChannel::setup_circular_read()`] for continuous data reception:
+//!
+//! ```no_run
+//! # use embassy_mcxa::dma::DmaChannel;
+//! # let dma_ch = DmaChannel::new(p.DMA_CH0);
+//! # let uart_rx_addr = 0x4000_0000 as *const u8;
+//! static mut RX_BUF: [u8; 64] = [0; 64];
+//!
+//! let ring_buf = unsafe {
+//!     dma_ch.setup_circular_read(uart_rx_addr, &mut RX_BUF)
+//! };
+//!
+//! // Read data as it arrives
+//! let mut buf = [0u8; 16];
+//! let n = ring_buf.read(&mut buf).await.unwrap();
+//! ```
+//!
+//! ## Scatter-Gather Builder (For Chained Transfers)
+//!
+//! Use [`ScatterGatherBuilder`] for complex multi-segment transfers:
+//!
+//! ```no_run
+//! # use embassy_mcxa::dma::{DmaChannel, ScatterGatherBuilder};
+//! # let dma_ch = DmaChannel::new(p.DMA_CH0);
+//! let mut builder = ScatterGatherBuilder::<u32>::new();
+//! builder.add_transfer(&src1, &mut dst1);
+//! builder.add_transfer(&src2, &mut dst2);
+//!
+//! let transfer = unsafe { builder.build(&dma_ch).unwrap() };
+//! transfer.await;
+//! ```
+//!
+//! ## Direct TCD Access (For Advanced Use Cases)
+//!
+//! For full control, use the channel's `tcd()` method to access TCD registers directly.
+//! See the `dma_*` examples for patterns.
+//!
+//! # Example
+//!
+//! ```no_run
+//! use embassy_mcxa::dma::{DmaChannel, TransferOptions, Direction};
+//!
+//! let dma_ch = DmaChannel::new(p.DMA_CH0);
+//! // Configure and trigger a transfer...
+//! ```
+use core::future::Future;
+use core::marker::PhantomData;
+use core::pin::Pin;
+use core::ptr::NonNull;
+use core::sync::atomic::{AtomicUsize, Ordering, fence};
+use core::task::{Context, Poll};
+use embassy_hal_internal::PeripheralType;
+use embassy_sync::waitqueue::AtomicWaker;
+use crate::clocks::Gate;
+use crate::pac;
+use crate::pac::Interrupt;
+use crate::peripherals::DMA0;
+/// Initialize DMA controller (clock enabled, reset released, controller configured).
+///
+/// This function is intended to be called ONCE during HAL initialization (`hal::init()`).
+///
+/// The function enables the DMA0 clock, releases reset, and configures the controller
+/// for normal operation with round-robin arbitration.
+pub(crate) fn init() {
+    unsafe {
+        // Enable DMA0 clock and release reset
+        DMA0::enable_clock();
+        DMA0::release_reset();
+        // Configure DMA controller
+        let dma = &(*pac::Dma0::ptr());
+        dma.mp_csr().modify(|_, w| {
+            w.edbg()
+                .enable()
+                .erca()
+                .enable()
+                .halt()
+                .normal_operation()
+                .gclc()
+                .available()
+                .gmrc()
+                .available()
+        });
+    }
+}
+// ============================================================================
+// Phase 1: Foundation Types (Embassy-aligned)
+// ============================================================================
+/// DMA transfer direction.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum Direction {
+    /// Transfer from memory to memory.
+    MemoryToMemory,
+    /// Transfer from memory to a peripheral register.
+    MemoryToPeripheral,
+    /// Transfer from a peripheral register to memory.
+    PeripheralToMemory,
+}
+/// DMA transfer priority.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Default)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum Priority {
+    /// Low priority (channel priority 7).
+    Low,
+    /// Medium priority (channel priority 4).
+    Medium,
+    /// High priority (channel priority 1).
+    #[default]
+    High,
+    /// Highest priority (channel priority 0).
+    Highest,
+}
+impl Priority {
+    /// Convert to hardware priority value (0 = highest, 7 = lowest).
+    pub fn to_hw_priority(self) -> u8 {
+        match self {
+            Priority::Low => 7,
+            Priority::Medium => 4,
+            Priority::High => 1,
+            Priority::Highest => 0,
+        }
+    }
+}
+/// DMA transfer data width.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Default)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum WordSize {
+    /// 8-bit (1 byte) transfers.
+    OneByte,
+    /// 16-bit (2 byte) transfers.
+    TwoBytes,
+    /// 32-bit (4 byte) transfers.
+    #[default]
+    FourBytes,
+}
+impl WordSize {
+    /// Size in bytes.
+    pub const fn bytes(self) -> usize {
+        match self {
+            WordSize::OneByte => 1,
+            WordSize::TwoBytes => 2,
+            WordSize::FourBytes => 4,
+        }
+    }
+    /// Convert to hardware SSIZE/DSIZE field value.
+    pub const fn to_hw_size(self) -> u8 {
+        match self {
+            WordSize::OneByte => 0,
+            WordSize::TwoBytes => 1,
+            WordSize::FourBytes => 2,
+        }
+    }
+    /// Create from byte width (1, 2, or 4).
+    pub const fn from_bytes(bytes: u8) -> Option<Self> {
+        match bytes {
+            1 => Some(WordSize::OneByte),
+            2 => Some(WordSize::TwoBytes),
+            4 => Some(WordSize::FourBytes),
+            _ => None,
+        }
+    }
+}
+/// Trait for types that can be transferred via DMA.
+///
+/// This provides compile-time type safety for DMA transfers.
+pub trait Word: Copy + 'static {
+    /// The word size for this type.
+    fn size() -> WordSize;
+}
+impl Word for u8 {
+    fn size() -> WordSize {
+        WordSize::OneByte
+    }
+}
+impl Word for u16 {
+    fn size() -> WordSize {
+        WordSize::TwoBytes
+    }
+}
+impl Word for u32 {
+    fn size() -> WordSize {
+        WordSize::FourBytes
+    }
+}
+/// DMA transfer options.
+///
+/// This struct configures various aspects of a DMA transfer.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[non_exhaustive]
+pub struct TransferOptions {
+    /// Transfer priority.
+    pub priority: Priority,
+    /// Enable circular (continuous) mode.
+    ///
+    /// When enabled, the transfer repeats automatically after completing.
+    pub circular: bool,
+    /// Enable interrupt on half transfer complete.
+    pub half_transfer_interrupt: bool,
+    /// Enable interrupt on transfer complete.
+    pub complete_transfer_interrupt: bool,
+}
+impl Default for TransferOptions {
+    fn default() -> Self {
+        Self {
+            priority: Priority::High,
+            circular: false,
+            half_transfer_interrupt: false,
+            complete_transfer_interrupt: true,
+        }
+    }
+}
+/// DMA error types.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum Error {
+    /// The DMA controller reported a bus error.
+    BusError,
+    /// The transfer was aborted.
+    Aborted,
+    /// Configuration error (e.g., invalid parameters).
+    Configuration,
+    /// Buffer overrun (for ring buffers).
+    Overrun,
+}
+/// Whether to enable the major loop completion interrupt.
+///
+/// This enum provides better readability than a boolean parameter
+/// for functions that configure DMA interrupt behavior.
+#[derive(Debug, Copy, Clone, PartialEq, Eq)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum EnableInterrupt {
+    /// Enable the interrupt on major loop completion.
+    Yes,
+    /// Do not enable the interrupt.
+    No,
+}
+// ============================================================================
+// DMA Constants
+// ============================================================================
+/// Maximum bytes per DMA transfer (eDMA4 CITER/BITER are 15-bit fields).
+///
+/// This is a hardware limitation of the eDMA4 controller. Transfers larger
+/// than this must be split into multiple DMA operations.
+pub const DMA_MAX_TRANSFER_SIZE: usize = 0x7FFF;
+// ============================================================================
+// DMA Request Source Types (Type-Safe API)
+// ============================================================================
+/// Trait for type-safe DMA request sources.
+///
+/// Each peripheral that can trigger DMA requests implements this trait
+/// with marker types that encode the correct request source number at
+/// compile time. This prevents using the wrong request source for a
+/// peripheral.
+///
+/// # Example
+///
+/// ```ignore
+/// // The LPUART2 RX request source is automatically derived from the type:
+/// channel.set_request_source::<Lpuart2RxRequest>();
+/// ```
+///
+/// This trait is sealed and cannot be implemented outside this crate.
+#[allow(private_bounds)]
+pub trait DmaRequest: sealed::SealedDmaRequest {
+    /// The hardware request source number for the DMA mux.
+    const REQUEST_NUMBER: u8;
+}
+/// Macro to define a DMA request type.
+///
+/// Creates a zero-sized marker type that implements `DmaRequest` with
+/// the specified request number.
+macro_rules! define_dma_request {
+    ($(#[$meta:meta])* $name:ident = $num:expr) => {
+        $(#[$meta])*
+        #[derive(Debug, Copy, Clone)]
+        pub struct $name;
+        impl sealed::SealedDmaRequest for $name {}
+        impl DmaRequest for $name {
+            const REQUEST_NUMBER: u8 = $num;
+        }
+    };
+}
+// LPUART DMA request sources (from MCXA276 reference manual Table 4-8)
+define_dma_request!(
+    /// DMA request source for LPUART0 RX.
+    Lpuart0RxRequest = 21
+);
+define_dma_request!(
+    /// DMA request source for LPUART0 TX.
+    Lpuart0TxRequest = 22
+);
+define_dma_request!(
+    /// DMA request source for LPUART1 RX.
+    Lpuart1RxRequest = 23
+);
+define_dma_request!(
+    /// DMA request source for LPUART1 TX.
+    Lpuart1TxRequest = 24
+);
+define_dma_request!(
+    /// DMA request source for LPUART2 RX.
+    Lpuart2RxRequest = 25
+);
+define_dma_request!(
+    /// DMA request source for LPUART2 TX.
+    Lpuart2TxRequest = 26
+);
+define_dma_request!(
+    /// DMA request source for LPUART3 RX.
+    Lpuart3RxRequest = 27
+);
+define_dma_request!(
+    /// DMA request source for LPUART3 TX.
+    Lpuart3TxRequest = 28
+);
+define_dma_request!(
+    /// DMA request source for LPUART4 RX.
+    Lpuart4RxRequest = 29
+);
+define_dma_request!(
+    /// DMA request source for LPUART4 TX.
+    Lpuart4TxRequest = 30
+);
+define_dma_request!(
+    /// DMA request source for LPUART5 RX.
+    Lpuart5RxRequest = 31
+);
+define_dma_request!(
+    /// DMA request source for LPUART5 TX.
+    Lpuart5TxRequest = 32
+);
+// ============================================================================
+// Channel Trait (Sealed Pattern)
+// ============================================================================
+mod sealed {
+    use crate::pac::Interrupt;
+    /// Sealed trait for DMA channels.
+    pub trait SealedChannel {
+        /// Zero-based channel index into the TCD array.
+        fn index(&self) -> usize;
+        /// Interrupt vector for this channel.
+        fn interrupt(&self) -> Interrupt;
+    }
+    /// Sealed trait for DMA request sources.
+    pub trait SealedDmaRequest {}
+}
+/// Marker trait implemented by HAL peripheral tokens that map to a DMA0
+/// channel backed by one EDMA_0_TCD0 TCD slot.
+///
+/// This trait is sealed and cannot be implemented outside this crate.
+#[allow(private_bounds)]
+pub trait Channel: sealed::SealedChannel + PeripheralType + Into<AnyChannel> + 'static {
+    /// Zero-based channel index into the TCD array.
+    const INDEX: usize;
+    /// Interrupt vector for this channel.
+    const INTERRUPT: Interrupt;
+}
+/// Type-erased DMA channel.
+///
+/// This allows storing DMA channels in a uniform way regardless of their
+/// concrete type, useful for async transfer futures and runtime channel selection.
+#[derive(Debug, Clone, Copy)]
+pub struct AnyChannel {
+    index: usize,
+    interrupt: Interrupt,
+}
+impl AnyChannel {
+    /// Get the channel index.
+    #[inline]
+    pub const fn index(&self) -> usize {
+        self.index
+    }
+    /// Get the channel interrupt.
+    #[inline]
+    pub const fn interrupt(&self) -> Interrupt {
+        self.interrupt
+    }
+    /// Get a reference to the TCD register block for this channel.
+    ///
+    /// This steals the eDMA pointer internally since MCXA276 has only one eDMA instance.
+    #[inline]
+    fn tcd(&self) -> &'static pac::edma_0_tcd0::Tcd {
+        // Safety: MCXA276 has a single eDMA instance, and we're only accessing
+        // the TCD for this specific channel
+        let edma = unsafe { &*pac::Edma0Tcd0::ptr() };
+        edma.tcd(self.index)
+    }
+    /// Check if the channel's DONE flag is set.
+    pub fn is_done(&self) -> bool {
+        self.tcd().ch_csr().read().done().bit_is_set()
+    }
+    /// Get the waker for this channel.
+    pub fn waker(&self) -> &'static AtomicWaker {
+        &STATES[self.index].waker
+    }
+}
+impl sealed::SealedChannel for AnyChannel {
+    fn index(&self) -> usize {
+        self.index
+    }
+    fn interrupt(&self) -> Interrupt {
+        self.interrupt
+    }
+}
+/// Macro to implement Channel trait for a peripheral.
+macro_rules! impl_channel {
+    ($peri:ident, $index:expr, $irq:ident) => {
+        impl sealed::SealedChannel for crate::peripherals::$peri {
+            fn index(&self) -> usize {
+                $index
+            }
+            fn interrupt(&self) -> Interrupt {
+                Interrupt::$irq
+            }
+        }
+        impl Channel for crate::peripherals::$peri {
+            const INDEX: usize = $index;
+            const INTERRUPT: Interrupt = Interrupt::$irq;
+        }
+        impl From<crate::peripherals::$peri> for AnyChannel {
+            fn from(_: crate::peripherals::$peri) -> Self {
+                AnyChannel {
+                    index: $index,
+                    interrupt: Interrupt::$irq,
+                }
+            }
+        }
+    };
+}
+impl_channel!(DMA_CH0, 0, DMA_CH0);
+impl_channel!(DMA_CH1, 1, DMA_CH1);
+impl_channel!(DMA_CH2, 2, DMA_CH2);
+impl_channel!(DMA_CH3, 3, DMA_CH3);
+impl_channel!(DMA_CH4, 4, DMA_CH4);
+impl_channel!(DMA_CH5, 5, DMA_CH5);
+impl_channel!(DMA_CH6, 6, DMA_CH6);
+impl_channel!(DMA_CH7, 7, DMA_CH7);
+/// Strongly-typed handle to a DMA0 channel.
+///
+/// The lifetime of this value is tied to the unique peripheral token
+/// supplied by `embassy_hal_internal::peripherals!`, so safe code cannot
+/// create two `DmaChannel` instances for the same hardware channel.
+pub struct DmaChannel<C: Channel> {
+    _ch: core::marker::PhantomData<C>,
+}
+// ============================================================================
+// DMA Transfer Methods - API Overview
+// ============================================================================
+//
+// The DMA API provides two categories of methods for configuring transfers:
+//
+// ## 1. Async Methods (Return `Transfer` Future)
+//
+// These methods return a [`Transfer`] Future that must be `.await`ed:
+//
+// - [`write()`](DmaChannel::write) - Memory-to-peripheral using default eDMA TCD block
+// - [`read()`](DmaChannel::read) - Peripheral-to-memory using default eDMA TCD block
+// - [`write_to_peripheral()`](DmaChannel::write_to_peripheral) - Memory-to-peripheral with custom eDMA TCD block
+// - [`read_from_peripheral()`](DmaChannel::read_from_peripheral) - Peripheral-to-memory with custom eDMA TCD block
+// - [`mem_to_mem()`](DmaChannel::mem_to_mem) - Memory-to-memory using default eDMA TCD block
+//
+// The `Transfer` manages the DMA lifecycle automatically:
+// - Enables channel request
+// - Waits for completion via async/await
+// - Cleans up on completion
+//
+// **Important:** `Transfer::Drop` aborts the transfer if dropped before completion.
+// This means you MUST `.await` the Transfer or it will be aborted when it goes out of scope.
+//
+// **Use case:** When you want to use async/await and let the Transfer handle lifecycle management.
+//
+// ## 2. Setup Methods (Configure TCD Only)
+//
+// These methods configure the TCD but do NOT return a `Transfer`:
+//
+// - [`setup_write()`](DmaChannel::setup_write) - Memory-to-peripheral using default eDMA TCD block
+// - [`setup_read()`](DmaChannel::setup_read) - Peripheral-to-memory using default eDMA TCD block
+// - [`setup_write_to_peripheral()`](DmaChannel::setup_write_to_peripheral) - Memory-to-peripheral with custom eDMA TCD block
+// - [`setup_read_from_peripheral()`](DmaChannel::setup_read_from_peripheral) - Peripheral-to-memory with custom eDMA TCD block
+//
+// The caller is responsible for the complete DMA lifecycle:
+// 1. Call [`enable_request()`](DmaChannel::enable_request) to start the transfer
+// 2. Poll [`is_done()`](DmaChannel::is_done) or use interrupts to detect completion
+// 3. Call [`disable_request()`](DmaChannel::disable_request), [`clear_done()`](DmaChannel::clear_done),
+//    [`clear_interrupt()`](DmaChannel::clear_interrupt) for cleanup
+//
+// **Use case:** Peripheral drivers (like LPUART) that need fine-grained control over
+// DMA setup before starting a `Transfer`.
+//
+// ============================================================================
+impl<C: Channel> DmaChannel<C> {
+    /// Wrap a DMA channel token (takes ownership of the Peri wrapper).
+    ///
+    /// Note: DMA is initialized during `hal::init()` via `dma::init()`.
+    #[inline]
+    pub fn new(_ch: embassy_hal_internal::Peri<'_, C>) -> Self {
+        unsafe {
+            cortex_m::peripheral::NVIC::unmask(C::INTERRUPT);
+        }
+        Self {
+            _ch: core::marker::PhantomData,
+        }
+    }
+    /// Channel index in the EDMA_0_TCD0 array.
+    #[inline]
+    pub const fn index(&self) -> usize {
+        C::INDEX
+    }
+    /// Convert this typed channel into a type-erased `AnyChannel`.
+    #[inline]
+    pub fn into_any(self) -> AnyChannel {
+        AnyChannel {
+            index: C::INDEX,
+            interrupt: C::INTERRUPT,
+        }
+    }
+    /// Get a reference to the type-erased channel info.
+    #[inline]
+    pub fn as_any(&self) -> AnyChannel {
+        AnyChannel {
+            index: C::INDEX,
+            interrupt: C::INTERRUPT,
+        }
+    }
+    /// Return a reference to the underlying TCD register block.
+    ///
+    /// This steals the eDMA pointer internally since MCXA276 has only one eDMA instance.
+    ///
+    /// # Note
+    ///
+    /// This is exposed for advanced use cases that need direct TCD access.
+    /// For most use cases, prefer the higher-level transfer methods.
+    #[inline]
+    pub fn tcd(&self) -> &'static pac::edma_0_tcd0::Tcd {
+        // Safety: MCXA276 has a single eDMA instance
+        let edma = unsafe { &*pac::Edma0Tcd0::ptr() };
+        edma.tcd(C::INDEX)
+    }
+    fn clear_tcd(t: &'static pac::edma_0_tcd0::Tcd) {
+        // Full TCD reset following NXP SDK pattern (EDMA_TcdResetExt).
+        // Reset ALL TCD registers to 0 to clear any stale configuration from
+        // previous transfers. This is critical when reusing a channel.
+        t.tcd_saddr().write(|w| unsafe { w.saddr().bits(0) });
+        t.tcd_soff().write(|w| unsafe { w.soff().bits(0) });
+        t.tcd_attr().write(|w| unsafe { w.bits(0) });
+        t.tcd_nbytes_mloffno().write(|w| unsafe { w.nbytes().bits(0) });
+        t.tcd_slast_sda().write(|w| unsafe { w.slast_sda().bits(0) });
+        t.tcd_daddr().write(|w| unsafe { w.daddr().bits(0) });
+        t.tcd_doff().write(|w| unsafe { w.doff().bits(0) });
+        t.tcd_citer_elinkno().write(|w| unsafe { w.bits(0) });
+        t.tcd_dlast_sga().write(|w| unsafe { w.dlast_sga().bits(0) });
+        t.tcd_csr().write(|w| unsafe { w.bits(0) }); // Clear CSR completely
+        t.tcd_biter_elinkno().write(|w| unsafe { w.bits(0) });
+    }
+    #[inline]
+    fn set_major_loop_ct_elinkno(t: &'static pac::edma_0_tcd0::Tcd, count: u16) {
+        t.tcd_biter_elinkno().write(|w| unsafe { w.biter().bits(count) });
+        t.tcd_citer_elinkno().write(|w| unsafe { w.citer().bits(count) });
+    }
+    #[inline]
+    fn set_minor_loop_ct_no_offsets(t: &'static pac::edma_0_tcd0::Tcd, count: u32) {
+        t.tcd_nbytes_mloffno().write(|w| unsafe { w.nbytes().bits(count) });
+    }
+    #[inline]
+    fn set_no_final_adjustments(t: &'static pac::edma_0_tcd0::Tcd) {
+        // No source/dest adjustment after major loop
+        t.tcd_slast_sda().write(|w| unsafe { w.slast_sda().bits(0) });
+        t.tcd_dlast_sga().write(|w| unsafe { w.dlast_sga().bits(0) });
+    }
+    #[inline]
+    fn set_source_ptr<T>(t: &'static pac::edma_0_tcd0::Tcd, p: *const T) {
+        t.tcd_saddr().write(|w| unsafe { w.saddr().bits(p as u32) });
+    }
+    #[inline]
+    fn set_source_increment(t: &'static pac::edma_0_tcd0::Tcd, sz: WordSize) {
+        t.tcd_soff().write(|w| unsafe { w.soff().bits(sz.bytes() as u16) });
+    }
+    #[inline]
+    fn set_source_fixed(t: &'static pac::edma_0_tcd0::Tcd) {
+        t.tcd_soff().write(|w| unsafe { w.soff().bits(0) });
+    }
+    #[inline]
+    fn set_dest_ptr<T>(t: &'static pac::edma_0_tcd0::Tcd, p: *mut T) {
+        t.tcd_daddr().write(|w| unsafe { w.daddr().bits(p as u32) });
+    }
+    #[inline]
+    fn set_dest_increment(t: &'static pac::edma_0_tcd0::Tcd, sz: WordSize) {
+        t.tcd_doff().write(|w| unsafe { w.doff().bits(sz.bytes() as u16) });
+    }
+    #[inline]
+    fn set_dest_fixed(t: &'static pac::edma_0_tcd0::Tcd) {
+        t.tcd_doff().write(|w| unsafe { w.doff().bits(0) });
+    }
+    #[inline]
+    fn set_even_transfer_size(t: &'static pac::edma_0_tcd0::Tcd, sz: WordSize) {
+        let hw_size = sz.to_hw_size();
+        t.tcd_attr()
+            .write(|w| unsafe { w.ssize().bits(hw_size).dsize().bits(hw_size) });
+    }
+    #[inline]
+    fn reset_channel_state(t: &'static pac::edma_0_tcd0::Tcd) {
+        // CSR: Resets to all zeroes (disabled), "done" is cleared by writing 1
+        t.ch_csr().write(|w| w.done().clear_bit_by_one());
+        // ES: Resets to all zeroes (disabled), "err" is cleared by writing 1
+        t.ch_es().write(|w| w.err().clear_bit_by_one());
+        // INT: Resets to all zeroes (disabled), "int" is cleared by writing 1
+        t.ch_int().write(|w| w.int().clear_bit_by_one());
+    }
+    /// Start an async transfer.
+    ///
+    /// The channel must already be configured. This enables the channel
+    /// request and returns a `Transfer` future that resolves when the
+    /// DMA transfer completes.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure the DMA channel has been properly configured
+    /// and that source/destination buffers remain valid for the duration
+    /// of the transfer.
+    pub unsafe fn start_transfer(&self) -> Transfer<'_> {
+        // Clear any previous DONE/INT flags
+        let t = self.tcd();
+        t.ch_csr().modify(|_, w| w.done().clear_bit_by_one());
+        t.ch_int().write(|w| w.int().clear_bit_by_one());
+        // Enable the channel request
+        t.ch_csr().modify(|_, w| w.erq().enable());
+        Transfer::new(self.as_any())
+    }
+    // ========================================================================
+    // Type-Safe Transfer Methods (Embassy-style API)
+    // ========================================================================
+    /// Perform a memory-to-memory DMA transfer (simplified API).
+    ///
+    /// This is a type-safe wrapper that uses the `Word` trait to determine
+    /// the correct transfer width automatically. Uses the global eDMA TCD
+    /// register accessor internally.
+    ///
+    /// # Arguments
+    ///
+    /// * `src` - Source buffer
+    /// * `dst` - Destination buffer (must be at least as large as src)
+    /// * `options` - Transfer configuration options
+    ///
+    /// # Safety
+    ///
+    /// The source and destination buffers must remain valid for the
+    /// duration of the transfer.
+    pub fn mem_to_mem<W: Word>(
+        &self,
+        src: &[W],
+        dst: &mut [W],
+        options: TransferOptions,
+    ) -> Result<Transfer<'_>, Error> {
+        let mut invalid = false;
+        invalid |= src.is_empty();
+        invalid |= src.len() > dst.len();
+        invalid |= src.len() > 0x7fff;
+        if invalid {
+            return Err(Error::Configuration);
+        }
+        let size = W::size();
+        let byte_count = (src.len() * size.bytes()) as u32;
+        let t = self.tcd();
+        // Reset channel state - clear DONE, disable requests, clear errors
+        Self::reset_channel_state(t);
+        // Memory barrier to ensure channel state is fully reset before touching TCD
+        cortex_m::asm::dsb();
+        Self::clear_tcd(t);
+        // Memory barrier after TCD reset
+        cortex_m::asm::dsb();
+        // Note: Priority is managed by round-robin arbitration (set in init())
+        // Per-channel priority can be configured via ch_pri() if needed
+        // Now configure the new transfer
+        // Source address and increment
+        Self::set_source_ptr(t, src.as_ptr());
+        Self::set_source_increment(t, size);
+        // Destination address and increment
+        Self::set_dest_ptr(t, dst.as_mut_ptr());
+        Self::set_dest_increment(t, size);
+        // Transfer attributes (size)
+        Self::set_even_transfer_size(t, size);
+        // Minor loop: transfer all bytes in one minor loop
+        Self::set_minor_loop_ct_no_offsets(t, byte_count);
+        // No source/dest adjustment after major loop
+        Self::set_no_final_adjustments(t);
+        // Major loop count = 1 (single major loop)
+        // Write BITER first, then CITER (CITER must match BITER at start)
+        Self::set_major_loop_ct_elinkno(t, 1);
+        // Memory barrier before setting START
+        cortex_m::asm::dsb();
+        // Control/status: interrupt on major complete, start
+        // Write this last after all other TCD registers are configured
+        let int_major = options.complete_transfer_interrupt;
+        t.tcd_csr().write(|w| {
+            w.intmajor()
+                .bit(int_major)
+                .inthalf()
+                .bit(options.half_transfer_interrupt)
+                .dreq()
+                .set_bit() // Auto-disable request after major loop
+                .start()
+                .set_bit() // Start the channel
+        });
+        Ok(Transfer::new(self.as_any()))
+    }
+    /// Fill a memory buffer with a pattern value (memset).
+    ///
+    /// This performs a DMA transfer where the source address remains fixed
+    /// (pattern value) while the destination address increments through the buffer.
+    /// It's useful for quickly filling large memory regions with a constant value.
+    ///
+    /// # Arguments
+    ///
+    /// * `pattern` - Reference to the pattern value (will be read repeatedly)
+    /// * `dst` - Destination buffer to fill
+    /// * `options` - Transfer configuration options
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// use embassy_mcxa::dma::{DmaChannel, TransferOptions};
+    ///
+    /// let dma_ch = DmaChannel::new(p.DMA_CH0);
+    /// let pattern: u32 = 0xDEADBEEF;
+    /// let mut buffer = [0u32; 256];
+    ///
+    /// unsafe {
+    ///     dma_ch.memset(&pattern, &mut buffer, TransferOptions::default()).await;
+    /// }
+    /// // buffer is now filled with 0xDEADBEEF
+    /// ```
+    ///
+    pub fn memset<W: Word>(&self, pattern: &W, dst: &mut [W], options: TransferOptions) -> Transfer<'_> {
+        assert!(!dst.is_empty());
+        assert!(dst.len() <= 0x7fff);
+        let size = W::size();
+        let byte_size = size.bytes();
+        // Total bytes to transfer - all in one minor loop for software-triggered transfers
+        let total_bytes = (dst.len() * byte_size) as u32;
+        let t = self.tcd();
+        // Reset channel state - clear DONE, disable requests, clear errors
+        Self::reset_channel_state(t);
+        // Memory barrier to ensure channel state is fully reset before touching TCD
+        cortex_m::asm::dsb();
+        Self::clear_tcd(t);
+        // Memory barrier after TCD reset
+        cortex_m::asm::dsb();
+        // Now configure the new transfer
+        //
+        // For software-triggered memset, we use a SINGLE minor loop that transfers
+        // all bytes at once. The source address stays fixed (SOFF=0) while the
+        // destination increments (DOFF=byte_size). The eDMA will read from the
+        // same source address for each destination word.
+        //
+        // This is necessary because the START bit only triggers ONE minor loop
+        // iteration. Using CITER>1 with software trigger would require multiple
+        // START triggers.
+        // Source: pattern address, fixed (soff=0)
+        Self::set_source_ptr(t, pattern);
+        Self::set_source_fixed(t);
+        // Destination: memory buffer, incrementing by word size
+        Self::set_dest_ptr(t, dst.as_mut_ptr());
+        Self::set_dest_increment(t, size);
+        // Transfer attributes - source and dest are same word size
+        Self::set_even_transfer_size(t, size);
+        // Minor loop: transfer ALL bytes in one minor loop (like mem_to_mem)
+        // This allows the entire transfer to complete with a single START trigger
+        Self::set_minor_loop_ct_no_offsets(t, total_bytes);
+        // No address adjustment after major loop
+        Self::set_no_final_adjustments(t);
+        // Major loop count = 1 (single major loop, all data in minor loop)
+        // Write BITER first, then CITER (CITER must match BITER at start)
+        Self::set_major_loop_ct_elinkno(t, 1);
+        // Memory barrier before setting START
+        cortex_m::asm::dsb();
+        // Control/status: interrupt on major complete, start immediately
+        // Write this last after all other TCD registers are configured
+        let int_major = options.complete_transfer_interrupt;
+        t.tcd_csr().write(|w| {
+            w.intmajor()
+                .bit(int_major)
+                .inthalf()
+                .bit(options.half_transfer_interrupt)
+                .dreq()
+                .set_bit() // Auto-disable request after major loop
+                .start()
+                .set_bit() // Start the channel
+        });
+        Transfer::new(self.as_any())
+    }
+    /// Write data from memory to a peripheral register.
+    ///
+    /// The destination address remains fixed (peripheral register) while
+    /// the source address increments through the buffer.
+    ///
+    /// # Arguments
+    ///
+    /// * `buf` - Source buffer to write from
+    /// * `peri_addr` - Peripheral register address
+    /// * `options` - Transfer configuration options
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the duration of the transfer.
+    /// - The peripheral address must be valid for writes.
+    pub unsafe fn write<W: Word>(&self, buf: &[W], peri_addr: *mut W, options: TransferOptions) -> Transfer<'_> {
+        self.write_to_peripheral(buf, peri_addr, options)
+    }
+    /// Configure a memory-to-peripheral DMA transfer without starting it.
+    ///
+    /// This is a convenience wrapper around [`setup_write_to_peripheral()`](Self::setup_write_to_peripheral)
+    /// that uses the default eDMA TCD register block.
+    ///
+    /// This method configures the TCD but does NOT return a `Transfer`. The caller
+    /// is responsible for the complete DMA lifecycle:
+    /// 1. Call [`enable_request()`](Self::enable_request) to start the transfer
+    /// 2. Poll [`is_done()`](Self::is_done) or use interrupts to detect completion
+    /// 3. Call [`disable_request()`](Self::disable_request), [`clear_done()`](Self::clear_done),
+    ///    [`clear_interrupt()`](Self::clear_interrupt) for cleanup
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use embassy_mcxa::dma::DmaChannel;
+    /// # let dma_ch = DmaChannel::new(p.DMA_CH0);
+    /// # let uart_tx_addr = 0x4000_0000 as *mut u8;
+    /// let data = [0x48, 0x65, 0x6c, 0x6c, 0x6f]; // "Hello"
+    ///
+    /// unsafe {
+    ///     // Configure the transfer
+    ///     dma_ch.setup_write(&data, uart_tx_addr, EnableInterrupt::Yes);
+    ///
+    ///     // Start when peripheral is ready
+    ///     dma_ch.enable_request();
+    ///
+    ///     // Wait for completion (or use interrupt)
+    ///     while !dma_ch.is_done() {}
+    ///
+    ///     // Clean up
+    ///     dma_ch.clear_done();
+    ///     dma_ch.clear_interrupt();
+    /// }
+    /// ```
+    ///
+    /// # Arguments
+    ///
+    /// * `buf` - Source buffer to write from
+    /// * `peri_addr` - Peripheral register address
+    /// * `enable_interrupt` - Whether to enable interrupt on completion
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the duration of the transfer.
+    /// - The peripheral address must be valid for writes.
+    pub unsafe fn setup_write<W: Word>(&self, buf: &[W], peri_addr: *mut W, enable_interrupt: EnableInterrupt) {
+        self.setup_write_to_peripheral(buf, peri_addr, enable_interrupt)
+    }
+    /// Write data from memory to a peripheral register.
+    ///
+    /// The destination address remains fixed (peripheral register) while
+    /// the source address increments through the buffer.
+    ///
+    /// # Arguments
+    ///
+    /// * `buf` - Source buffer to write from
+    /// * `peri_addr` - Peripheral register address
+    /// * `options` - Transfer configuration options
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the duration of the transfer.
+    /// - The peripheral address must be valid for writes.
+    pub unsafe fn write_to_peripheral<W: Word>(
+        &self,
+        buf: &[W],
+        peri_addr: *mut W,
+        options: TransferOptions,
+    ) -> Transfer<'_> {
+        assert!(!buf.is_empty());
+        assert!(buf.len() <= 0x7fff);
+        let size = W::size();
+        let byte_size = size.bytes();
+        let t = self.tcd();
+        // Reset channel state
+        Self::reset_channel_state(t);
+        // Addresses
+        Self::set_source_ptr(t, buf.as_ptr());
+        Self::set_dest_ptr(t, peri_addr);
+        // Offsets: Source increments, Dest fixed
+        Self::set_source_increment(t, size);
+        Self::set_dest_fixed(t);
+        // Attributes: set size and explicitly disable modulo
+        Self::set_even_transfer_size(t, size);
+        // Minor loop: transfer one word per request (match old: only set nbytes)
+        Self::set_minor_loop_ct_no_offsets(t, byte_size as u32);
+        // No final adjustments
+        Self::set_no_final_adjustments(t);
+        // Major loop count = number of words
+        let count = buf.len() as u16;
+        Self::set_major_loop_ct_elinkno(t, count);
+        // CSR: interrupt on major loop complete and auto-clear ERQ
+        t.tcd_csr().write(|w| {
+            let w = if options.complete_transfer_interrupt {
+                w.intmajor().enable()
+            } else {
+                w.intmajor().disable()
+            };
+            w.inthalf()
+                .disable()
+                .dreq()
+                .erq_field_clear() // Disable request when done
+                .esg()
+                .normal_format()
+                .majorelink()
+                .disable()
+                .eeop()
+                .disable()
+                .esda()
+                .disable()
+                .bwc()
+                .no_stall()
+        });
+        // Ensure all TCD writes have completed before DMA engine reads them
+        cortex_m::asm::dsb();
+        Transfer::new(self.as_any())
+    }
+    /// Read data from a peripheral register to memory.
+    ///
+    /// The source address remains fixed (peripheral register) while
+    /// the destination address increments through the buffer.
+    ///
+    /// # Arguments
+    ///
+    /// * `peri_addr` - Peripheral register address
+    /// * `buf` - Destination buffer to read into
+    /// * `options` - Transfer configuration options
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the duration of the transfer.
+    /// - The peripheral address must be valid for reads.
+    pub unsafe fn read<W: Word>(&self, peri_addr: *const W, buf: &mut [W], options: TransferOptions) -> Transfer<'_> {
+        self.read_from_peripheral(peri_addr, buf, options)
+    }
+    /// Configure a peripheral-to-memory DMA transfer without starting it.
+    ///
+    /// This is a convenience wrapper around [`setup_read_from_peripheral()`](Self::setup_read_from_peripheral)
+    /// that uses the default eDMA TCD register block.
+    ///
+    /// This method configures the TCD but does NOT return a `Transfer`. The caller
+    /// is responsible for the complete DMA lifecycle:
+    /// 1. Call [`enable_request()`](Self::enable_request) to start the transfer
+    /// 2. Poll [`is_done()`](Self::is_done) or use interrupts to detect completion
+    /// 3. Call [`disable_request()`](Self::disable_request), [`clear_done()`](Self::clear_done),
+    ///    [`clear_interrupt()`](Self::clear_interrupt) for cleanup
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use embassy_mcxa::dma::DmaChannel;
+    /// # let dma_ch = DmaChannel::new(p.DMA_CH0);
+    /// # let uart_rx_addr = 0x4000_0000 as *const u8;
+    /// let mut buf = [0u8; 32];
+    ///
+    /// unsafe {
+    ///     // Configure the transfer
+    ///     dma_ch.setup_read(uart_rx_addr, &mut buf, EnableInterrupt::Yes);
+    ///
+    ///     // Start when peripheral is ready
+    ///     dma_ch.enable_request();
+    ///
+    ///     // Wait for completion (or use interrupt)
+    ///     while !dma_ch.is_done() {}
+    ///
+    ///     // Clean up
+    ///     dma_ch.clear_done();
+    ///     dma_ch.clear_interrupt();
+    /// }
+    /// // buf now contains received data
+    /// ```
+    ///
+    /// # Arguments
+    ///
+    /// * `peri_addr` - Peripheral register address
+    /// * `buf` - Destination buffer to read into
+    /// * `enable_interrupt` - Whether to enable interrupt on completion
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the duration of the transfer.
+    /// - The peripheral address must be valid for reads.
+    pub unsafe fn setup_read<W: Word>(&self, peri_addr: *const W, buf: &mut [W], enable_interrupt: EnableInterrupt) {
+        self.setup_read_from_peripheral(peri_addr, buf, enable_interrupt)
+    }
+    /// Read data from a peripheral register to memory.
+    ///
+    /// The source address remains fixed (peripheral register) while
+    /// the destination address increments through the buffer.
+    ///
+    /// # Arguments
+    ///
+    /// * `peri_addr` - Peripheral register address
+    /// * `buf` - Destination buffer to read into
+    /// * `options` - Transfer configuration options
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the duration of the transfer.
+    /// - The peripheral address must be valid for reads.
+    pub unsafe fn read_from_peripheral<W: Word>(
+        &self,
+        peri_addr: *const W,
+        buf: &mut [W],
+        options: TransferOptions,
+    ) -> Transfer<'_> {
+        assert!(!buf.is_empty());
+        assert!(buf.len() <= 0x7fff);
+        let size = W::size();
+        let byte_size = size.bytes();
+        let t = self.tcd();
+        // Reset channel control/error/interrupt state
+        Self::reset_channel_state(t);
+        // Source: peripheral register, fixed
+        Self::set_source_ptr(t, peri_addr);
+        Self::set_source_fixed(t);
+        // Destination: memory buffer, incrementing
+        Self::set_dest_ptr(t, buf.as_mut_ptr());
+        Self::set_dest_increment(t, size);
+        // Transfer attributes: set size and explicitly disable modulo
+        Self::set_even_transfer_size(t, size);
+        // Minor loop: transfer one word per request, no offsets
+        Self::set_minor_loop_ct_no_offsets(t, byte_size as u32);
+        // Major loop count = number of words
+        let count = buf.len() as u16;
+        Self::set_major_loop_ct_elinkno(t, count);
+        // No address adjustment after major loop
+        Self::set_no_final_adjustments(t);
+        // Control/status: interrupt on major complete, auto-clear ERQ when done
+        t.tcd_csr().write(|w| {
+            let w = if options.complete_transfer_interrupt {
+                w.intmajor().enable()
+            } else {
+                w.intmajor().disable()
+            };
+            let w = if options.half_transfer_interrupt {
+                w.inthalf().enable()
+            } else {
+                w.inthalf().disable()
+            };
+            w.dreq()
+                .erq_field_clear() // Disable request when done (important for peripheral DMA)
+                .esg()
+                .normal_format()
+                .majorelink()
+                .disable()
+                .eeop()
+                .disable()
+                .esda()
+                .disable()
+                .bwc()
+                .no_stall()
+        });
+        // Ensure all TCD writes have completed before DMA engine reads them
+        cortex_m::asm::dsb();
+        Transfer::new(self.as_any())
+    }
+    /// Configure a memory-to-peripheral DMA transfer without starting it.
+    ///
+    /// This configures the TCD for a memory-to-peripheral transfer but does NOT
+    /// return a Transfer object. The caller is responsible for:
+    /// 1. Enabling the peripheral's DMA request
+    /// 2. Calling `enable_request()` to start the transfer
+    /// 3. Polling `is_done()` or using interrupts to detect completion
+    /// 4. Calling `disable_request()`, `clear_done()`, `clear_interrupt()` for cleanup
+    ///
+    /// Use this when you need manual control over the DMA lifecycle (e.g., in
+    /// peripheral drivers that have their own completion polling).
+    ///
+    /// # Arguments
+    ///
+    /// * `buf` - Source buffer to write from
+    /// * `peri_addr` - Peripheral register address
+    /// * `enable_interrupt` - Whether to enable interrupt on completion
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the duration of the transfer.
+    /// - The peripheral address must be valid for writes.
+    pub unsafe fn setup_write_to_peripheral<W: Word>(
+        &self,
+        buf: &[W],
+        peri_addr: *mut W,
+        enable_interrupt: EnableInterrupt,
+    ) {
+        assert!(!buf.is_empty());
+        assert!(buf.len() <= 0x7fff);
+        let size = W::size();
+        let byte_size = size.bytes();
+        let t = self.tcd();
+        // Reset channel state
+        Self::reset_channel_state(t);
+        // Addresses
+        Self::set_source_ptr(t, buf.as_ptr());
+        Self::set_dest_ptr(t, peri_addr);
+        // Offsets: Source increments, Dest fixed
+        Self::set_source_increment(t, size);
+        Self::set_dest_fixed(t);
+        // Attributes: set size and explicitly disable modulo
+        Self::set_even_transfer_size(t, size);
+        // Minor loop: transfer one word per request
+        Self::set_minor_loop_ct_no_offsets(t, byte_size as u32);
+        // No final adjustments
+        Self::set_no_final_adjustments(t);
+        // Major loop count = number of words
+        let count = buf.len() as u16;
+        Self::set_major_loop_ct_elinkno(t, count);
+        // CSR: optional interrupt on major loop complete and auto-clear ERQ
+        t.tcd_csr().write(|w| {
+            let w = match enable_interrupt {
+                EnableInterrupt::Yes => w.intmajor().enable(),
+                EnableInterrupt::No => w.intmajor().disable(),
+            };
+            w.inthalf()
+                .disable()
+                .dreq()
+                .erq_field_clear()
+                .esg()
+                .normal_format()
+                .majorelink()
+                .disable()
+                .eeop()
+                .disable()
+                .esda()
+                .disable()
+                .bwc()
+                .no_stall()
+        });
+        // Ensure all TCD writes have completed before DMA engine reads them
+        cortex_m::asm::dsb();
+    }
+    /// Configure a peripheral-to-memory DMA transfer without starting it.
+    ///
+    /// This configures the TCD for a peripheral-to-memory transfer but does NOT
+    /// return a Transfer object. The caller is responsible for:
+    /// 1. Enabling the peripheral's DMA request
+    /// 2. Calling `enable_request()` to start the transfer
+    /// 3. Polling `is_done()` or using interrupts to detect completion
+    /// 4. Calling `disable_request()`, `clear_done()`, `clear_interrupt()` for cleanup
+    ///
+    /// Use this when you need manual control over the DMA lifecycle (e.g., in
+    /// peripheral drivers that have their own completion polling).
+    ///
+    /// # Arguments
+    ///
+    /// * `peri_addr` - Peripheral register address
+    /// * `buf` - Destination buffer to read into
+    /// * `enable_interrupt` - Whether to enable interrupt on completion
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the duration of the transfer.
+    /// - The peripheral address must be valid for reads.
+    pub unsafe fn setup_read_from_peripheral<W: Word>(
+        &self,
+        peri_addr: *const W,
+        buf: &mut [W],
+        enable_interrupt: EnableInterrupt,
+    ) {
+        assert!(!buf.is_empty());
+        assert!(buf.len() <= 0x7fff);
+        let size = W::size();
+        let byte_size = size.bytes();
+        let t = self.tcd();
+        // Reset channel control/error/interrupt state
+        Self::reset_channel_state(t);
+        // Source: peripheral register, fixed
+        Self::set_source_ptr(t, peri_addr);
+        Self::set_source_fixed(t);
+        // Destination: memory buffer, incrementing
+        Self::set_dest_ptr(t, buf.as_mut_ptr());
+        Self::set_dest_increment(t, size);
+        // Attributes: set size and explicitly disable modulo
+        Self::set_even_transfer_size(t, size);
+        // Minor loop: transfer one word per request
+        Self::set_minor_loop_ct_no_offsets(t, byte_size as u32);
+        // No final adjustments
+        Self::set_no_final_adjustments(t);
+        // Major loop count = number of words
+        let count = buf.len() as u16;
+        Self::set_major_loop_ct_elinkno(t, count);
+        // CSR: optional interrupt on major loop complete and auto-clear ERQ
+        t.tcd_csr().write(|w| {
+            let w = match enable_interrupt {
+                EnableInterrupt::Yes => w.intmajor().enable(),
+                EnableInterrupt::No => w.intmajor().disable(),
+            };
+            w.inthalf()
+                .disable()
+                .dreq()
+                .erq_field_clear()
+                .esg()
+                .normal_format()
+                .majorelink()
+                .disable()
+                .eeop()
+                .disable()
+                .esda()
+                .disable()
+                .bwc()
+                .no_stall()
+        });
+        // Ensure all TCD writes have completed before DMA engine reads them
+        cortex_m::asm::dsb();
+    }
+    /// Configure the integrated channel MUX to use the given typed
+    /// DMA request source (e.g., [`Lpuart2TxRequest`] or [`Lpuart2RxRequest`]).
+    ///
+    /// This is the type-safe version that uses marker types to ensure
+    /// compile-time verification of request source validity.
+    ///
+    /// # Safety
+    ///
+    /// The channel must be properly configured before enabling requests.
+    /// The caller must ensure the DMA request source matches the peripheral
+    /// that will drive this channel.
+    ///
+    /// # Note
+    ///
+    /// The NXP SDK requires a two-step write sequence: first clear
+    /// the mux to 0, then set the actual source. This is a hardware
+    /// requirement on eDMA4 for the mux to properly latch.
+    ///
+    /// # Example
+    ///
+    /// ```ignore
+    /// use embassy_mcxa::dma::{DmaChannel, Lpuart2RxRequest};
+    ///
+    /// // Type-safe: compiler verifies this is a valid DMA request type
+    /// unsafe {
+    ///     channel.set_request_source::<Lpuart2RxRequest>();
+    /// }
+    /// ```
+    #[inline]
+    pub unsafe fn set_request_source<R: DmaRequest>(&self) {
+        // Two-step write per NXP SDK: clear to 0, then set actual source.
+        self.tcd().ch_mux().write(|w| w.src().bits(0));
+        cortex_m::asm::dsb(); // Ensure the clear completes before setting new source
+        self.tcd().ch_mux().write(|w| w.src().bits(R::REQUEST_NUMBER));
+    }
+    /// Enable hardware requests for this channel (ERQ=1).
+    ///
+    /// # Safety
+    ///
+    /// The channel must be properly configured before enabling requests.
+    pub unsafe fn enable_request(&self) {
+        let t = self.tcd();
+        t.ch_csr().modify(|_, w| w.erq().enable());
+    }
+    /// Disable hardware requests for this channel (ERQ=0).
+    ///
+    /// # Safety
+    ///
+    /// Disabling requests on an active transfer may leave the transfer incomplete.
+    pub unsafe fn disable_request(&self) {
+        let t = self.tcd();
+        t.ch_csr().modify(|_, w| w.erq().disable());
+    }
+    /// Return true if the channel's DONE flag is set.
+    pub fn is_done(&self) -> bool {
+        let t = self.tcd();
+        t.ch_csr().read().done().bit_is_set()
+    }
+    /// Clear the DONE flag for this channel.
+    ///
+    /// Uses modify to preserve other bits (especially ERQ) unlike write
+    /// which would clear ERQ and halt an active transfer.
+    ///
+    /// # Safety
+    ///
+    /// Clearing DONE while a transfer is in progress may cause undefined behavior.
+    pub unsafe fn clear_done(&self) {
+        let t = self.tcd();
+        t.ch_csr().modify(|_, w| w.done().clear_bit_by_one());
+    }
+    /// Clear the channel interrupt flag (CH_INT.INT).
+    ///
+    /// # Safety
+    ///
+    /// Must be called from the correct interrupt context or with interrupts disabled.
+    pub unsafe fn clear_interrupt(&self) {
+        let t = self.tcd();
+        t.ch_int().write(|w| w.int().clear_bit_by_one());
+    }
+    /// Trigger a software start for this channel.
+    ///
+    /// # Safety
+    ///
+    /// The channel must be properly configured with a valid TCD before triggering.
+    pub unsafe fn trigger_start(&self) {
+        let t = self.tcd();
+        t.tcd_csr().modify(|_, w| w.start().channel_started());
+    }
+    /// Get the waker for this channel
+    pub fn waker(&self) -> &'static AtomicWaker {
+        &STATES[C::INDEX].waker
+    }
+    /// Enable the interrupt for this channel in the NVIC.
+    pub fn enable_interrupt(&self) {
+        unsafe {
+            cortex_m::peripheral::NVIC::unmask(C::INTERRUPT);
+        }
+    }
+    /// Enable Major Loop Linking.
+    ///
+    /// When the major loop completes, the hardware will trigger a service request
+    /// on `link_ch`.
+    ///
+    /// # Arguments
+    ///
+    /// * `link_ch` - Target channel index (0-7) to link to
+    ///
+    /// # Safety
+    ///
+    /// The channel must be properly configured before setting up linking.
+    pub unsafe fn set_major_link(&self, link_ch: usize) {
+        let t = self.tcd();
+        t.tcd_csr()
+            .modify(|_, w| w.majorelink().enable().majorlinkch().bits(link_ch as u8));
+    }
+    /// Disable Major Loop Linking.
+    ///
+    /// Removes any major loop channel linking previously configured.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure this doesn't disrupt an active transfer that
+    /// depends on the linking.
+    pub unsafe fn clear_major_link(&self) {
+        let t = self.tcd();
+        t.tcd_csr().modify(|_, w| w.majorelink().disable());
+    }
+    /// Enable Minor Loop Linking.
+    ///
+    /// After each minor loop, the hardware will trigger a service request
+    /// on `link_ch`.
+    ///
+    /// # Arguments
+    ///
+    /// * `link_ch` - Target channel index (0-7) to link to
+    ///
+    /// # Note
+    ///
+    /// This rewrites CITER and BITER registers to the ELINKYES format.
+    /// It preserves the current loop count.
+    ///
+    /// # Safety
+    ///
+    /// The channel must be properly configured before setting up linking.
+    pub unsafe fn set_minor_link(&self, link_ch: usize) {
+        let t = self.tcd();
+        // Read current CITER (assuming ELINKNO format initially)
+        let current_citer = t.tcd_citer_elinkno().read().citer().bits();
+        let current_biter = t.tcd_biter_elinkno().read().biter().bits();
+        // Write back using ELINKYES format
+        t.tcd_citer_elinkyes().write(|w| {
+            w.citer()
+                .bits(current_citer)
+                .elink()
+                .enable()
+                .linkch()
+                .bits(link_ch as u8)
+        });
+        t.tcd_biter_elinkyes().write(|w| {
+            w.biter()
+                .bits(current_biter)
+                .elink()
+                .enable()
+                .linkch()
+                .bits(link_ch as u8)
+        });
+    }
+    /// Disable Minor Loop Linking.
+    ///
+    /// Removes any minor loop channel linking previously configured.
+    /// This rewrites CITER and BITER registers to the ELINKNO format,
+    /// preserving the current loop count.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure this doesn't disrupt an active transfer that
+    /// depends on the linking.
+    pub unsafe fn clear_minor_link(&self) {
+        let t = self.tcd();
+        // Read current CITER (could be in either format, but we only need the count)
+        // Note: In ELINKYES format, citer is 9 bits; in ELINKNO, it's 15 bits.
+        // We read from ELINKNO which will give us the combined value.
+        let current_citer = t.tcd_citer_elinkno().read().citer().bits();
+        let current_biter = t.tcd_biter_elinkno().read().biter().bits();
+        // Write back using ELINKNO format (disabling link)
+        t.tcd_citer_elinkno()
+            .write(|w| w.citer().bits(current_citer).elink().disable());
+        t.tcd_biter_elinkno()
+            .write(|w| w.biter().bits(current_biter).elink().disable());
+    }
+    /// Load a TCD from memory into the hardware channel registers.
+    ///
+    /// This is useful for scatter/gather and ping-pong transfers where
+    /// TCDs are prepared in RAM and then loaded into the hardware.
+    ///
+    /// # Safety
+    ///
+    /// - The TCD must be properly initialized.
+    /// - The caller must ensure no concurrent access to the same channel.
+    pub unsafe fn load_tcd(&self, tcd: &Tcd) {
+        let t = self.tcd();
+        t.tcd_saddr().write(|w| w.saddr().bits(tcd.saddr));
+        t.tcd_soff().write(|w| w.soff().bits(tcd.soff as u16));
+        t.tcd_attr().write(|w| w.bits(tcd.attr));
+        t.tcd_nbytes_mloffno().write(|w| w.nbytes().bits(tcd.nbytes));
+        t.tcd_slast_sda().write(|w| w.slast_sda().bits(tcd.slast as u32));
+        t.tcd_daddr().write(|w| w.daddr().bits(tcd.daddr));
+        t.tcd_doff().write(|w| w.doff().bits(tcd.doff as u16));
+        t.tcd_citer_elinkno().write(|w| w.citer().bits(tcd.citer));
+        t.tcd_dlast_sga().write(|w| w.dlast_sga().bits(tcd.dlast_sga as u32));
+        t.tcd_csr().write(|w| w.bits(tcd.csr));
+        t.tcd_biter_elinkno().write(|w| w.biter().bits(tcd.biter));
+    }
+}
+/// In-memory representation of a Transfer Control Descriptor (TCD).
+///
+/// This matches the hardware layout (32 bytes).
+#[repr(C, align(32))]
+#[derive(Clone, Copy, Debug, Default)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub struct Tcd {
+    pub saddr: u32,
+    pub soff: i16,
+    pub attr: u16,
+    pub nbytes: u32,
+    pub slast: i32,
+    pub daddr: u32,
+    pub doff: i16,
+    pub citer: u16,
+    pub dlast_sga: i32,
+    pub csr: u16,
+    pub biter: u16,
+}
+struct State {
+    /// Waker for transfer complete interrupt
+    waker: AtomicWaker,
+    /// Waker for half-transfer interrupt
+    half_waker: AtomicWaker,
+}
+impl State {
+    const fn new() -> Self {
+        Self {
+            waker: AtomicWaker::new(),
+            half_waker: AtomicWaker::new(),
+        }
+    }
+}
+static STATES: [State; 8] = [
+    State::new(),
+    State::new(),
+    State::new(),
+    State::new(),
+    State::new(),
+    State::new(),
+    State::new(),
+    State::new(),
+];
+pub(crate) fn waker(idx: usize) -> &'static AtomicWaker {
+    &STATES[idx].waker
+}
+pub(crate) fn half_waker(idx: usize) -> &'static AtomicWaker {
+    &STATES[idx].half_waker
+}
+// ============================================================================
+// Async Transfer Future
+// ============================================================================
+/// An in-progress DMA transfer.
+///
+/// This type implements `Future` and can be `.await`ed to wait for the
+/// transfer to complete. Dropping the transfer will abort it.
+#[must_use = "futures do nothing unless you `.await` or poll them"]
+pub struct Transfer<'a> {
+    channel: AnyChannel,
+    _phantom: core::marker::PhantomData<&'a ()>,
+}
+impl<'a> Transfer<'a> {
+    /// Create a new transfer for the given channel.
+    ///
+    /// The caller must have already configured and started the DMA channel.
+    pub(crate) fn new(channel: AnyChannel) -> Self {
+        Self {
+            channel,
+            _phantom: core::marker::PhantomData,
+        }
+    }
+    /// Check if the transfer is still running.
+    pub fn is_running(&self) -> bool {
+        !self.channel.is_done()
+    }
+    /// Get the remaining transfer count.
+    pub fn remaining(&self) -> u16 {
+        let t = self.channel.tcd();
+        t.tcd_citer_elinkno().read().citer().bits()
+    }
+    /// Block until the transfer completes.
+    pub fn blocking_wait(self) {
+        while self.is_running() {
+            core::hint::spin_loop();
+        }
+        // Ensure all DMA writes are visible
+        fence(Ordering::SeqCst);
+        // Don't run drop (which would abort)
+        core::mem::forget(self);
+    }
+    /// Wait for the half-transfer interrupt asynchronously.
+    ///
+    /// This is useful for double-buffering scenarios where you want to process
+    /// the first half of the buffer while the second half is being filled.
+    ///
+    /// Returns `true` if the half-transfer occurred, `false` if the transfer
+    /// completed before the half-transfer interrupt.
+    ///
+    /// # Note
+    ///
+    /// The transfer must be configured with `TransferOptions::half_transfer_interrupt = true`
+    /// for this method to work correctly.
+    pub async fn wait_half(&mut self) -> Result<bool, TransferErrorRaw> {
+        use core::future::poll_fn;
+        poll_fn(|cx| {
+            let state = &STATES[self.channel.index];
+            // Register the half-transfer waker
+            state.half_waker.register(cx.waker());
+            // Check if there's an error
+            let t = self.channel.tcd();
+            let es = t.ch_es().read();
+            if es.err().is_error() {
+                // Currently, all error fields are in the lowest 8 bits, as-casting truncates
+                let errs = es.bits() as u8;
+                return Poll::Ready(Err(TransferErrorRaw(errs)));
+            }
+            // Check if we're past the half-way point
+            let biter = t.tcd_biter_elinkno().read().biter().bits();
+            let citer = t.tcd_citer_elinkno().read().citer().bits();
+            let half_point = biter / 2;
+            if self.channel.is_done() {
+                // Transfer completed before half-transfer
+                Poll::Ready(Ok(false))
+            } else if citer <= half_point {
+                // We're past the half-way point
+                fence(Ordering::SeqCst);
+                Poll::Ready(Ok(true))
+            } else {
+                Poll::Pending
+            }
+        })
+        .await
+    }
+    /// Abort the transfer.
+    fn abort(&mut self) {
+        let t = self.channel.tcd();
+        // Disable channel requests
+        t.ch_csr().modify(|_, w| w.erq().disable());
+        // Clear any pending interrupt
+        t.ch_int().write(|w| w.int().clear_bit_by_one());
+        // Clear DONE flag
+        t.ch_csr().modify(|_, w| w.done().clear_bit_by_one());
+        fence(Ordering::SeqCst);
+    }
+}
+/// Raw transfer error bits. Can be queried or all errors can be iterated over
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[derive(Copy, Clone, Debug)]
+pub struct TransferErrorRaw(u8);
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+#[derive(Copy, Clone, Debug)]
+pub struct TransferErrorRawIter(u8);
+impl TransferErrorRaw {
+    const MAP: &[(u8, TransferError)] = &[
+        (1 << 0, TransferError::DestinationBus),
+        (1 << 1, TransferError::SourceBus),
+        (1 << 2, TransferError::ScatterGatherConfiguration),
+        (1 << 3, TransferError::NbytesCiterConfiguration),
+        (1 << 4, TransferError::DestinationOffset),
+        (1 << 5, TransferError::DestinationAddress),
+        (1 << 6, TransferError::SourceOffset),
+        (1 << 7, TransferError::SourceAddress),
+    ];
+    /// Convert to an iterator of contained errors
+    pub fn err_iter(self) -> TransferErrorRawIter {
+        TransferErrorRawIter(self.0)
+    }
+    /// Destination Bus Error
+    #[inline]
+    pub fn has_destination_bus_err(&self) -> bool {
+        (self.0 & (1 << 0)) != 0
+    }
+    /// Source Bus Error
+    #[inline]
+    pub fn has_source_bus_err(&self) -> bool {
+        (self.0 & (1 << 1)) != 0
+    }
+    /// Indicates that `TCDn_DLAST_SGA` is not on a 32-byte boundary. This field is
+    /// checked at the beginning of a scatter/gather operation after major loop completion
+    /// if `TCDn_CSR[ESG]` is enabled.
+    #[inline]
+    pub fn has_scatter_gather_configuration_err(&self) -> bool {
+        (self.0 & (1 << 2)) != 0
+    }
+    /// This error indicates that one of the following has occurred:
+    ///
+    /// * `TCDn_NBYTES` is not a multiple of `TCDn_ATTR[SSIZE]` and `TCDn_ATTR[DSIZE]`
+    /// * `TCDn_CITER[CITER]` is equal to zero
+    /// * `TCDn_CITER[ELINK]` is not equal to `TCDn_BITER[ELINK]`
+    #[inline]
+    pub fn has_nbytes_citer_configuration_err(&self) -> bool {
+        (self.0 & (1 << 3)) != 0
+    }
+    /// `TCDn_DOFF` is inconsistent with `TCDn_ATTR[DSIZE]`.
+    #[inline]
+    pub fn has_destination_offset_err(&self) -> bool {
+        (self.0 & (1 << 4)) != 0
+    }
+    /// `TCDn_DADDR` is inconsistent with `TCDn_ATTR[DSIZE]`.
+    #[inline]
+    pub fn has_destination_address_err(&self) -> bool {
+        (self.0 & (1 << 5)) != 0
+    }
+    /// `TCDn_SOFF` is inconsistent with `TCDn_ATTR[SSIZE]`.
+    #[inline]
+    pub fn has_source_offset_err(&self) -> bool {
+        (self.0 & (1 << 6)) != 0
+    }
+    /// `TCDn_SADDR` is inconsistent with `TCDn_ATTR[SSIZE]`
+    #[inline]
+    pub fn has_source_address_err(&self) -> bool {
+        (self.0 & (1 << 7)) != 0
+    }
+}
+impl Iterator for TransferErrorRawIter {
+    type Item = TransferError;
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.0 == 0 {
+            return None;
+        }
+        for (mask, var) in TransferErrorRaw::MAP {
+            // If the bit is set...
+            if self.0 | mask != 0 {
+                // clear the bit
+                self.0 &= !mask;
+                // and return the answer
+                return Some(*var);
+            }
+        }
+        // Shouldn't happen, but oh well.
+        None
+    }
+}
+#[derive(Copy, Clone, Debug)]
+#[cfg_attr(feature = "defmt", derive(defmt::Format))]
+pub enum TransferError {
+    /// `TCDn_SADDR` is inconsistent with `TCDn_ATTR[SSIZE]`
+    SourceAddress,
+    /// `TCDn_SOFF` is inconsistent with `TCDn_ATTR[SSIZE]`.
+    SourceOffset,
+    /// `TCDn_DADDR` is inconsistent with `TCDn_ATTR[DSIZE]`.
+    DestinationAddress,
+    /// `TCDn_DOFF` is inconsistent with `TCDn_ATTR[DSIZE]`.
+    DestinationOffset,
+    /// This error indicates that one of the following has occurred:
+    ///
+    /// * `TCDn_NBYTES` is not a multiple of `TCDn_ATTR[SSIZE]` and `TCDn_ATTR[DSIZE]`
+    /// * `TCDn_CITER[CITER]` is equal to zero
+    /// * `TCDn_CITER[ELINK]` is not equal to `TCDn_BITER[ELINK]`
+    NbytesCiterConfiguration,
+    /// Indicates that `TCDn_DLAST_SGA` is not on a 32-byte boundary. This field is
+    /// checked at the beginning of a scatter/gather operation after major loop completion
+    /// if `TCDn_CSR[ESG]` is enabled.
+    ScatterGatherConfiguration,
+    /// Source Bus Error
+    SourceBus,
+    /// Destination Bus Error
+    DestinationBus,
+}
+impl<'a> Unpin for Transfer<'a> {}
+impl<'a> Future for Transfer<'a> {
+    type Output = Result<(), TransferErrorRaw>;
+    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
+        let state = &STATES[self.channel.index];
+        // Register waker first
+        state.waker.register(cx.waker());
+        let done = self.channel.is_done();
+        if done {
+            // Ensure all DMA writes are visible before returning
+            fence(Ordering::SeqCst);
+            let es = self.channel.tcd().ch_es().read();
+            if es.err().is_error() {
+                // Currently, all error fields are in the lowest 8 bits, as-casting truncates
+                let errs = es.bits() as u8;
+                Poll::Ready(Err(TransferErrorRaw(errs)))
+            } else {
+                Poll::Ready(Ok(()))
+            }
+        } else {
+            Poll::Pending
+        }
+    }
+}
+impl<'a> Drop for Transfer<'a> {
+    fn drop(&mut self) {
+        // Only abort if the transfer is still running
+        // If already complete, no need to abort
+        if self.is_running() {
+            self.abort();
+            // Wait for abort to complete
+            while self.is_running() {
+                core::hint::spin_loop();
+            }
+        }
+        fence(Ordering::SeqCst);
+    }
+}
+// ============================================================================
+// Ring Buffer for Circular DMA
+// ============================================================================
+/// A ring buffer for continuous DMA reception.
+///
+/// This structure manages a circular DMA transfer, allowing continuous
+/// reception of data without losing bytes between reads. It uses both
+/// half-transfer and complete-transfer interrupts to track available data.
+///
+/// # Example
+///
+/// ```no_run
+/// use embassy_mcxa::dma::{DmaChannel, RingBuffer, TransferOptions};
+///
+/// static mut RX_BUF: [u8; 64] = [0; 64];
+///
+/// let dma_ch = DmaChannel::new(p.DMA_CH0);
+/// let ring_buf = unsafe {
+///     dma_ch.setup_circular_read(
+///         uart_rx_addr,
+///         &mut RX_BUF,
+///     )
+/// };
+///
+/// // Read data as it arrives
+/// let mut buf = [0u8; 16];
+/// let n = ring_buf.read(&mut buf).await?;
+/// ```
+pub struct RingBuffer<'a, W: Word> {
+    channel: AnyChannel,
+    /// Buffer pointer. We use NonNull instead of &mut because DMA acts like
+    /// a separate thread writing to this buffer, and &mut claims exclusive
+    /// access which the compiler could optimize incorrectly.
+    buf: NonNull<[W]>,
+    /// Buffer length cached for convenience
+    buf_len: usize,
+    /// Read position in the buffer (consumer side)
+    read_pos: AtomicUsize,
+    /// Phantom data to tie the lifetime to the original buffer
+    _lt: PhantomData<&'a mut [W]>,
+}
+impl<'a, W: Word> RingBuffer<'a, W> {
+    /// Create a new ring buffer for the given channel and buffer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure:
+    /// - The DMA channel has been configured for circular transfer
+    /// - The buffer remains valid for the lifetime of the ring buffer
+    /// - Only one RingBuffer exists per DMA channel at a time
+    pub(crate) unsafe fn new(channel: AnyChannel, buf: &'a mut [W]) -> Self {
+        let buf_len = buf.len();
+        Self {
+            channel,
+            buf: NonNull::from(buf),
+            buf_len,
+            read_pos: AtomicUsize::new(0),
+            _lt: PhantomData,
+        }
+    }
+    /// Get a slice reference to the buffer.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that DMA is not actively writing to the
+    /// portion of the buffer being accessed, or that the access is
+    /// appropriately synchronized.
+    #[inline]
+    unsafe fn buf_slice(&self) -> &[W] {
+        self.buf.as_ref()
+    }
+    /// Get the current DMA write position in the buffer.
+    ///
+    /// This reads the current destination address from the DMA controller
+    /// and calculates the buffer offset.
+    fn dma_write_pos(&self) -> usize {
+        let t = self.channel.tcd();
+        let daddr = t.tcd_daddr().read().daddr().bits() as usize;
+        let buf_start = self.buf.as_ptr() as *const W as usize;
+        // Calculate offset from buffer start
+        let offset = daddr.wrapping_sub(buf_start) / core::mem::size_of::<W>();
+        // Ensure we're within bounds (DMA wraps around)
+        offset % self.buf_len
+    }
+    /// Returns the number of bytes available to read.
+    pub fn available(&self) -> usize {
+        let write_pos = self.dma_write_pos();
+        let read_pos = self.read_pos.load(Ordering::Acquire);
+        if write_pos >= read_pos {
+            write_pos - read_pos
+        } else {
+            self.buf_len - read_pos + write_pos
+        }
+    }
+    /// Check if the buffer has overrun (data was lost).
+    ///
+    /// This happens when DMA writes faster than the application reads.
+    pub fn is_overrun(&self) -> bool {
+        // In a true overrun, the DMA would have wrapped around and caught up
+        // to our read position. We can detect this by checking if available()
+        // equals the full buffer size (minus 1 to distinguish from empty).
+        self.available() >= self.buf_len - 1
+    }
+    /// Read data from the ring buffer into the provided slice.
+    ///
+    /// Returns the number of elements read, which may be less than
+    /// `dst.len()` if not enough data is available.
+    ///
+    /// This method does not block; use `read_async()` for async waiting.
+    pub fn read_immediate(&self, dst: &mut [W]) -> usize {
+        let write_pos = self.dma_write_pos();
+        let read_pos = self.read_pos.load(Ordering::Acquire);
+        // Calculate available bytes
+        let available = if write_pos >= read_pos {
+            write_pos - read_pos
+        } else {
+            self.buf_len - read_pos + write_pos
+        };
+        let to_read = dst.len().min(available);
+        if to_read == 0 {
+            return 0;
+        }
+        // Safety: We only read from portions of the buffer that DMA has
+        // already written to (between read_pos and write_pos).
+        let buf = unsafe { self.buf_slice() };
+        // Read data, handling wrap-around
+        let first_chunk = (self.buf_len - read_pos).min(to_read);
+        dst[..first_chunk].copy_from_slice(&buf[read_pos..read_pos + first_chunk]);
+        if to_read > first_chunk {
+            let second_chunk = to_read - first_chunk;
+            dst[first_chunk..to_read].copy_from_slice(&buf[..second_chunk]);
+        }
+        // Update read position
+        let new_read_pos = (read_pos + to_read) % self.buf_len;
+        self.read_pos.store(new_read_pos, Ordering::Release);
+        to_read
+    }
+    /// Read data from the ring buffer asynchronously.
+    ///
+    /// This waits until at least one byte is available, then reads as much
+    /// as possible into the destination buffer.
+    ///
+    /// Returns the number of elements read.
+    pub async fn read(&self, dst: &mut [W]) -> Result<usize, Error> {
+        use core::future::poll_fn;
+        if dst.is_empty() {
+            return Ok(0);
+        }
+        poll_fn(|cx| {
+            // Check for overrun
+            if self.is_overrun() {
+                return Poll::Ready(Err(Error::Overrun));
+            }
+            // Try to read immediately
+            let n = self.read_immediate(dst);
+            if n > 0 {
+                return Poll::Ready(Ok(n));
+            }
+            // Register wakers for both half and complete interrupts
+            let state = &STATES[self.channel.index()];
+            state.waker.register(cx.waker());
+            state.half_waker.register(cx.waker());
+            // Check again after registering waker (avoid race)
+            let n = self.read_immediate(dst);
+            if n > 0 {
+                return Poll::Ready(Ok(n));
+            }
+            Poll::Pending
+        })
+        .await
+    }
+    /// Clear the ring buffer, discarding all unread data.
+    pub fn clear(&self) {
+        let write_pos = self.dma_write_pos();
+        self.read_pos.store(write_pos, Ordering::Release);
+    }
+    /// Stop the DMA transfer and consume the ring buffer.
+    ///
+    /// Returns any remaining unread data count.
+    pub fn stop(mut self) -> usize {
+        let res = self.teardown();
+        drop(self);
+        res
+    }
+    /// Stop the DMA transfer. Intended to be called by `stop()` or `Drop`.
+    fn teardown(&mut self) -> usize {
+        let available = self.available();
+        // Disable the channel
+        let t = self.channel.tcd();
+        t.ch_csr().modify(|_, w| w.erq().disable());
+        // Clear flags
+        t.ch_int().write(|w| w.int().clear_bit_by_one());
+        t.ch_csr().modify(|_, w| w.done().clear_bit_by_one());
+        fence(Ordering::SeqCst);
+        available
+    }
+}
+impl<'a, W: Word> Drop for RingBuffer<'a, W> {
+    fn drop(&mut self) {
+        self.teardown();
+    }
+}
+impl<C: Channel> DmaChannel<C> {
+    /// Set up a circular DMA transfer for continuous peripheral-to-memory reception.
+    ///
+    /// This configures the DMA channel for circular operation with both half-transfer
+    /// and complete-transfer interrupts enabled. The transfer runs continuously until
+    /// stopped via [`RingBuffer::stop()`].
+    ///
+    /// # Arguments
+    ///
+    /// * `peri_addr` - Peripheral register address to read from
+    /// * `buf` - Destination buffer (should be power-of-2 size for best efficiency)
+    ///
+    /// # Returns
+    ///
+    /// A [`RingBuffer`] that can be used to read received data.
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the lifetime of the returned RingBuffer.
+    /// - The peripheral address must be valid for reads.
+    /// - The peripheral's DMA request must be configured to trigger this channel.
+    pub unsafe fn setup_circular_read<'a, W: Word>(&self, peri_addr: *const W, buf: &'a mut [W]) -> RingBuffer<'a, W> {
+        assert!(!buf.is_empty());
+        assert!(buf.len() <= 0x7fff);
+        // For circular mode, buffer size should ideally be power of 2
+        // but we don't enforce it
+        let size = W::size();
+        let byte_size = size.bytes();
+        let t = self.tcd();
+        // Reset channel state
+        Self::reset_channel_state(t);
+        // Source: peripheral register, fixed
+        Self::set_source_ptr(t, peri_addr);
+        Self::set_source_fixed(t);
+        // Destination: memory buffer, incrementing
+        Self::set_dest_ptr(t, buf.as_mut_ptr());
+        Self::set_dest_increment(t, size);
+        // Transfer attributes
+        Self::set_even_transfer_size(t, size);
+        // Minor loop: transfer one word per request
+        Self::set_minor_loop_ct_no_offsets(t, byte_size as u32);
+        // Major loop count = buffer size
+        let count = buf.len() as u16;
+        Self::set_major_loop_ct_elinkno(t, count);
+        // After major loop: reset destination to buffer start (circular)
+        let buf_bytes = (buf.len() * byte_size) as i32;
+        t.tcd_slast_sda().write(|w| w.slast_sda().bits(0)); // Source doesn't change
+        t.tcd_dlast_sga().write(|w| w.dlast_sga().bits((-buf_bytes) as u32));
+        // Control/status: enable both half and complete interrupts, NO DREQ (continuous)
+        t.tcd_csr().write(|w| {
+            w.intmajor()
+                .enable()
+                .inthalf()
+                .enable()
+                .dreq()
+                .channel_not_affected() // Don't clear ERQ on complete (circular)
+                .esg()
+                .normal_format()
+                .majorelink()
+                .disable()
+                .eeop()
+                .disable()
+                .esda()
+                .disable()
+                .bwc()
+                .no_stall()
+        });
+        cortex_m::asm::dsb();
+        // Enable the channel request
+        t.ch_csr().modify(|_, w| w.erq().enable());
+        // Enable NVIC interrupt for this channel so async wakeups work
+        self.enable_interrupt();
+        RingBuffer::new(self.as_any(), buf)
+    }
+}
+// ============================================================================
+// Scatter-Gather Builder
+// ============================================================================
+/// Maximum number of TCDs in a scatter-gather chain.
+pub const MAX_SCATTER_GATHER_TCDS: usize = 16;
+/// A builder for constructing scatter-gather DMA transfer chains.
+///
+/// This provides a type-safe way to build TCD chains for scatter-gather
+/// transfers without manual TCD manipulation.
+///
+/// # Example
+///
+/// ```no_run
+/// use embassy_mcxa::dma::{DmaChannel, ScatterGatherBuilder};
+///
+/// let mut builder = ScatterGatherBuilder::<u32>::new();
+///
+/// // Add transfer segments
+/// builder.add_transfer(&src1, &mut dst1);
+/// builder.add_transfer(&src2, &mut dst2);
+/// builder.add_transfer(&src3, &mut dst3);
+///
+/// // Build and execute
+/// let transfer = unsafe { builder.build(&dma_ch).unwrap() };
+/// transfer.await;
+/// ```
+pub struct ScatterGatherBuilder<'a, W: Word> {
+    /// TCD pool (must be 32-byte aligned)
+    tcds: [Tcd; MAX_SCATTER_GATHER_TCDS],
+    /// Number of TCDs configured
+    count: usize,
+    /// Phantom marker for word type
+    _phantom: core::marker::PhantomData<W>,
+    _plt: core::marker::PhantomData<&'a mut W>,
+}
+impl<'a, W: Word> ScatterGatherBuilder<'a, W> {
+    /// Create a new scatter-gather builder.
+    pub fn new() -> Self {
+        ScatterGatherBuilder {
+            tcds: [Tcd::default(); MAX_SCATTER_GATHER_TCDS],
+            count: 0,
+            _phantom: core::marker::PhantomData,
+            _plt: core::marker::PhantomData,
+        }
+    }
+    /// Add a memory-to-memory transfer segment to the chain.
+    ///
+    /// # Arguments
+    ///
+    /// * `src` - Source buffer for this segment
+    /// * `dst` - Destination buffer for this segment
+    ///
+    /// # Panics
+    ///
+    /// Panics if the maximum number of segments (16) is exceeded.
+    pub fn add_transfer<'b: 'a>(&mut self, src: &'b [W], dst: &'b mut [W]) -> &mut Self {
+        assert!(self.count < MAX_SCATTER_GATHER_TCDS, "Too many scatter-gather segments");
+        assert!(!src.is_empty());
+        assert!(dst.len() >= src.len());
+        let size = W::size();
+        let byte_size = size.bytes();
+        let hw_size = size.to_hw_size();
+        let nbytes = (src.len() * byte_size) as u32;
+        // Build the TCD for this segment
+        self.tcds[self.count] = Tcd {
+            saddr: src.as_ptr() as u32,
+            soff: byte_size as i16,
+            attr: ((hw_size as u16) << 8) | (hw_size as u16), // SSIZE | DSIZE
+            nbytes,
+            slast: 0,
+            daddr: dst.as_mut_ptr() as u32,
+            doff: byte_size as i16,
+            citer: 1,
+            dlast_sga: 0, // Will be filled in by build()
+            csr: 0x0002,  // INTMAJOR only (ESG will be set for non-last TCDs)
+            biter: 1,
+        };
+        self.count += 1;
+        self
+    }
+    /// Get the number of transfer segments added.
+    pub fn segment_count(&self) -> usize {
+        self.count
+    }
+    /// Build the scatter-gather chain and start the transfer.
+    ///
+    /// # Arguments
+    ///
+    /// * `channel` - The DMA channel to use for the transfer
+    ///
+    /// # Returns
+    ///
+    /// A `Transfer` future that completes when the entire chain has executed.
+    pub fn build<C: Channel>(&mut self, channel: &DmaChannel<C>) -> Result<Transfer<'a>, Error> {
+        if self.count == 0 {
+            return Err(Error::Configuration);
+        }
+        // Link TCDs together
+        //
+        // CSR bit definitions:
+        // - START = bit 0 = 0x0001 (triggers transfer when set)
+        // - INTMAJOR = bit 1 = 0x0002 (interrupt on major loop complete)
+        // - ESG = bit 4 = 0x0010 (enable scatter-gather, loads next TCD on complete)
+        //
+        // When hardware loads a TCD via scatter-gather (ESG), it copies the TCD's
+        // CSR directly into the hardware register. If START is not set in that CSR,
+        // the hardware will NOT auto-execute the loaded TCD.
+        //
+        // Strategy:
+        // - First TCD: ESG | INTMAJOR (no START - we add it manually after loading)
+        // - Middle TCDs: ESG | INTMAJOR | START (auto-execute when loaded via S/G)
+        // - Last TCD: INTMAJOR | START (auto-execute, no further linking)
+        for i in 0..self.count {
+            let is_first = i == 0;
+            let is_last = i == self.count - 1;
+            if is_first {
+                if is_last {
+                    // Only one TCD - no ESG, no START (we add START manually)
+                    self.tcds[i].dlast_sga = 0;
+                    self.tcds[i].csr = 0x0002; // INTMAJOR only
+                } else {
+                    // First of multiple - ESG to link, no START (we add START manually)
+                    self.tcds[i].dlast_sga = &self.tcds[i + 1] as *const Tcd as i32;
+                    self.tcds[i].csr = 0x0012; // ESG | INTMAJOR
+                }
+            } else if is_last {
+                // Last TCD (not first) - no ESG, but START so it auto-executes
+                self.tcds[i].dlast_sga = 0;
+                self.tcds[i].csr = 0x0003; // INTMAJOR | START
+            } else {
+                // Middle TCD - ESG to link, and START so it auto-executes
+                self.tcds[i].dlast_sga = &self.tcds[i + 1] as *const Tcd as i32;
+                self.tcds[i].csr = 0x0013; // ESG | INTMAJOR | START
+            }
+        }
+        let t = channel.tcd();
+        // Reset channel state - clear DONE, disable requests, clear errors
+        // This ensures the channel is in a clean state before loading the TCD
+        DmaChannel::<C>::reset_channel_state(t);
+        // Memory barrier to ensure channel state is reset before loading TCD
+        cortex_m::asm::dsb();
+        // Load first TCD into hardware
+        unsafe {
+            channel.load_tcd(&self.tcds[0]);
+        }
+        // Memory barrier before setting START
+        cortex_m::asm::dsb();
+        // Start the transfer
+        t.tcd_csr().modify(|_, w| w.start().channel_started());
+        Ok(Transfer::new(channel.as_any()))
+    }
+    /// Reset the builder for reuse.
+    pub fn clear(&mut self) {
+        self.count = 0;
+    }
+}
+impl<W: Word> Default for ScatterGatherBuilder<'_, W> {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+/// A completed scatter-gather transfer result.
+///
+/// This type is returned after a scatter-gather transfer completes,
+/// providing access to any error information.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct ScatterGatherResult {
+    /// Number of segments successfully transferred
+    pub segments_completed: usize,
+    /// Error if any occurred
+    pub error: Option<Error>,
+}
+// ============================================================================
+// Interrupt Handler
+// ============================================================================
+/// Interrupt handler helper.
+///
+/// Call this from your interrupt handler to clear the interrupt flag and wake the waker.
+/// This handles both half-transfer and complete-transfer interrupts.
+///
+/// # Safety
+/// Must be called from the correct DMA channel interrupt context.
+pub unsafe fn on_interrupt(ch_index: usize) {
+    let p = pac::Peripherals::steal();
+    let edma = &p.edma_0_tcd0;
+    let t = edma.tcd(ch_index);
+    // Read TCD CSR to determine interrupt source
+    let csr = t.tcd_csr().read();
+    // Check if this is a half-transfer interrupt
+    // INTHALF is set and we're at or past the half-way point
+    if csr.inthalf().bit_is_set() {
+        let biter = t.tcd_biter_elinkno().read().biter().bits();
+        let citer = t.tcd_citer_elinkno().read().citer().bits();
+        let half_point = biter / 2;
+        if citer <= half_point && citer > 0 {
+            // Half-transfer interrupt - wake half_waker
+            half_waker(ch_index).wake();
+        }
+    }
+    // Clear INT flag
+    t.ch_int().write(|w| w.int().clear_bit_by_one());
+    // If DONE is set, this is a complete-transfer interrupt
+    // Only wake the full-transfer waker when the transfer is actually complete
+    if t.ch_csr().read().done().bit_is_set() {
+        waker(ch_index).wake();
+    }
+}
+// ============================================================================
+// Type-level Interrupt Handlers
+// ============================================================================
+/// Macro to generate DMA channel interrupt handlers.
+macro_rules! impl_dma_interrupt_handler {
+    ($irq:ident, $ch:expr) => {
+        #[interrupt]
+        fn $irq() {
+            unsafe {
+                on_interrupt($ch);
+            }
+        }
+    };
+}
+use crate::pac::interrupt;
+impl_dma_interrupt_handler!(DMA_CH0, 0);
+impl_dma_interrupt_handler!(DMA_CH1, 1);
+impl_dma_interrupt_handler!(DMA_CH2, 2);
+impl_dma_interrupt_handler!(DMA_CH3, 3);
+impl_dma_interrupt_handler!(DMA_CH4, 4);
+impl_dma_interrupt_handler!(DMA_CH5, 5);
+impl_dma_interrupt_handler!(DMA_CH6, 6);
+impl_dma_interrupt_handler!(DMA_CH7, 7);
author	Raul Alimbekov <[email protected]>	2025-12-16 09:05:22 +0300
committer	GitHub <[email protected]>	2025-12-16 09:05:22 +0300
commit	c9a04b4b732b7a3b696eb8223664c1a7942b1875 (patch)
tree	6dbe5c02e66eed8d8762f13f95afd24f8db2b38c /embassy-mcxa/src/dma.rs
parent	cde24a3ef1117653ba5ed4184102b33f745782fb (diff)
parent	5ae6e060ec1c90561719aabdc29d5b6e7b8b0a82 (diff)