refactor(dma): move DMA_MAX_TRANSFER_SIZE to dma module and init during HAL startup

Address felipebalbi's review comments on PR #52:

- Move DMA_MAX_TRANSFER_SIZE constant from lpuart/mod.rs to dma.rs
  where it logically belongs (describes eDMA4 hardware limitation)
- Add public dma::init() function called during hal::init() instead
  of lazy initialization via ensure_init()
- Remove ensure_init() entirely since it's no longer needed
- Remove ensure_init() calls from DmaChannel::new() and from_token()
- Remove ensure_init() calls from examples (dma_channel_link, dma_scatter_gather)
- Refactor lpuart_ring_buffer example to use LpuartDma::new() + split()
  pattern instead of separate TX/RX drivers
- Add [lints.rust] section to suppress unexpected_cfgs warning for 'rt'
  feature used by embassy_hal_internal::interrupt_mod! macro

This makes DMA initialization explicit during HAL startup (like GPIO)
and keeps DMA-specific constants in the DMA module.

7 files changed, 116 insertions, 60 deletions

diff --git a/Cargo.toml b/Cargo.toml
index 96b7d6b0f..f86b92c32 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -46,3 +46,9 @@ time = [
     "dep:embassy-time",
     "dep:embassy-time-driver",
 ]
+
+[lints.rust]
+# The `rt` cfg is checked by embassy_hal_internal::interrupt_mod! macro
+# even though it's defined in the macro's crate, not ours. This suppresses
+# the "unexpected cfg condition value" warning.
+unexpected_cfgs = { level = "warn", check-cfg = ["cfg(feature, values(\"rt\"))"] }
diff --git a/examples/src/bin/dma_channel_link.rs b/examples/src/bin/dma_channel_link.rs
index 34162d931..361c9ebc7 100644
--- a/examples/src/bin/dma_channel_link.rs
+++ b/examples/src/bin/dma_channel_link.rs
@@ -18,7 +18,7 @@
 
 use embassy_executor::Spawner;
 use embassy_mcxa::clocks::config::Div8;
-use embassy_mcxa::dma::{self, DmaCh0InterruptHandler, DmaCh1InterruptHandler, DmaCh2InterruptHandler, DmaChannel};
+use embassy_mcxa::dma::{DmaCh0InterruptHandler, DmaCh1InterruptHandler, DmaCh2InterruptHandler, DmaChannel};
 use embassy_mcxa::lpuart::{Blocking, Config, Lpuart, LpuartTx};
 use embassy_mcxa::{bind_interrupts, pac};
 use {defmt_rtt as _, embassy_mcxa as hal, panic_probe as _};
@@ -85,8 +85,7 @@ async fn main(_spawner: Spawner) {
 
     defmt::info!("DMA channel link example starting...");
 
-    // Ensure DMA is initialized (clock/reset/init handled automatically by HAL)
-    dma::ensure_init();
+    // DMA is initialized during hal::init() - no need to call ensure_init()
 
     let pac_periphs = unsafe { pac::Peripherals::steal() };
     let dma0 = &pac_periphs.dma0;
diff --git a/examples/src/bin/dma_scatter_gather.rs b/examples/src/bin/dma_scatter_gather.rs
index b5ae00057..9844071b7 100644
--- a/examples/src/bin/dma_scatter_gather.rs
+++ b/examples/src/bin/dma_scatter_gather.rs
@@ -120,8 +120,7 @@ async fn main(_spawner: Spawner) {
 
     defmt::info!("DMA scatter-gather transfer example starting...");
 
-    // Ensure DMA is initialized (clock/reset/init handled automatically by HAL)
-    dma::ensure_init();
+    // DMA is initialized during hal::init() - no need to call ensure_init()
 
     // Enable DMA interrupt
     unsafe {
diff --git a/examples/src/bin/lpuart_ring_buffer.rs b/examples/src/bin/lpuart_ring_buffer.rs
index 6cc14f1c7..0946bad03 100644
--- a/examples/src/bin/lpuart_ring_buffer.rs
+++ b/examples/src/bin/lpuart_ring_buffer.rs
@@ -1,18 +1,18 @@
 //! LPUART Ring Buffer DMA example for MCXA276.
 //!
-//! This example demonstrates using the new `RingBuffer` API for continuous
-//! circular DMA reception from a UART peripheral.
+//! This example demonstrates using the high-level `LpuartRxDma::setup_ring_buffer()`
+//! API for continuous circular DMA reception from a UART peripheral.
 //!
 //! # Features demonstrated:
-//! - `setup_circular_read()` for continuous peripheral-to-memory DMA
+//! - `LpuartRxDma::setup_ring_buffer()` for continuous peripheral-to-memory DMA
 //! - `RingBuffer` for async reading of received data
 //! - Handling of potential overrun conditions
 //! - Half-transfer and complete-transfer interrupts for timely wakeups
 //!
 //! # How it works:
-//! 1. Set up a circular DMA transfer from LPUART RX to a ring buffer
-//! 2. DMA continuously writes received bytes into the buffer, wrapping around
-//! 3. Application asynchronously reads data as it arrives
+//! 1. Create an `LpuartRxDma` driver with a DMA channel
+//! 2. Call `setup_ring_buffer()` which handles all low-level DMA configuration
+//! 3. Application asynchronously reads data as it arrives via `ring_buf.read()`
 //! 4. Both half-transfer and complete-transfer interrupts wake the reader
 
 #![no_std]
@@ -20,9 +20,9 @@
 
 use embassy_executor::Spawner;
 use embassy_mcxa::clocks::config::Div8;
-use embassy_mcxa::dma::{DmaCh0InterruptHandler, DmaCh1InterruptHandler, DmaChannel, DMA_REQ_LPUART2_RX};
-use embassy_mcxa::lpuart::{Blocking, Config, Lpuart, LpuartTx};
-use embassy_mcxa::{bind_interrupts, pac};
+use embassy_mcxa::dma::{DmaCh0InterruptHandler, DmaCh1InterruptHandler};
+use embassy_mcxa::lpuart::{Config, LpuartDma, LpuartTxDma};
+use embassy_mcxa::bind_interrupts;
 use {defmt_rtt as _, embassy_mcxa as hal, panic_probe as _};
 
 // Bind DMA channel interrupts
@@ -35,7 +35,10 @@ bind_interrupts!(struct Irqs {
 static mut RX_RING_BUFFER: [u8; 64] = [0; 64];
 
 /// Helper to write a byte as hex to UART
-fn write_hex(tx: &mut LpuartTx<'_, Blocking>, byte: u8) {
+fn write_hex<T: embassy_mcxa::lpuart::Instance, C: embassy_mcxa::dma::Channel>(
+    tx: &mut LpuartTxDma<'_, T, C>,
+    byte: u8,
+) {
     const HEX: &[u8; 16] = b"0123456789ABCDEF";
     let buf = [HEX[(byte >> 4) as usize], HEX[(byte & 0x0F) as usize]];
     tx.blocking_write(&buf).ok();
@@ -55,12 +58,6 @@ async fn main(_spawner: Spawner) {
 
     defmt::info!("LPUART Ring Buffer DMA example starting...");
 
-    // Enable DMA interrupts (DMA clock/reset/init is handled automatically by HAL)
-    unsafe {
-        cortex_m::peripheral::NVIC::unmask(pac::Interrupt::DMA_CH0);
-        cortex_m::peripheral::NVIC::unmask(pac::Interrupt::DMA_CH1);
-    }
-
     // Create UART configuration
     let config = Config {
         baudrate_bps: 115_200,
@@ -69,41 +66,27 @@ async fn main(_spawner: Spawner) {
         ..Default::default()
     };
 
-    // Create blocking UART for TX (we'll use DMA for RX only)
-    let lpuart = Lpuart::new_blocking(p.LPUART2, p.P2_2, p.P2_3, config).unwrap();
-    let (mut tx, _rx) = lpuart.split();
+    // Create LPUART with DMA support for both TX and RX, then split
+    // This is the proper Embassy pattern - create once, split into TX and RX
+    let lpuart = LpuartDma::new(p.LPUART2, p.P2_2, p.P2_3, p.DMA_CH1, p.DMA_CH0, config).unwrap();
+    let (mut tx, rx) = lpuart.split();
 
     tx.blocking_write(b"LPUART Ring Buffer DMA Example\r\n").unwrap();
     tx.blocking_write(b"==============================\r\n\r\n").unwrap();
 
-    // Get LPUART2 RX data register address for DMA
-    let lpuart2 = unsafe { &*pac::Lpuart2::ptr() };
-    let rx_data_addr = lpuart2.data().as_ptr() as *const u8;
-
-    // Enable RX DMA request in LPUART
-    lpuart2.baud().modify(|_, w| w.rdmae().enabled());
-
-    // Create DMA channel for RX
-    let dma_ch_rx = DmaChannel::new(p.DMA_CH0);
-
-    // Configure the DMA mux for LPUART2 RX
-    unsafe {
-        dma_ch_rx.set_request_source(DMA_REQ_LPUART2_RX);
-    }
-
     tx.blocking_write(b"Setting up circular DMA for UART RX...\r\n")
         .unwrap();
 
     // Set up the ring buffer with circular DMA
-    // This configures the DMA for continuous reception
+    // The HAL handles: DMA request source, RDMAE enable, circular transfer config, NVIC enable
     let ring_buf = unsafe {
         let buf = &mut *core::ptr::addr_of_mut!(RX_RING_BUFFER);
-        dma_ch_rx.setup_circular_read(rx_data_addr, buf)
+        rx.setup_ring_buffer(buf)
     };
 
     // Enable DMA requests to start continuous reception
     unsafe {
-        dma_ch_rx.enable_request();
+        rx.enable_dma_request();
     }
 
     tx.blocking_write(b"Ring buffer ready! Type characters to see them echoed.\r\n")
diff --git a/src/dma.rs b/src/dma.rs
index 7bfc95752..8d82c254a 100644
--- a/src/dma.rs
+++ b/src/dma.rs
@@ -118,17 +118,14 @@ use crate::peripherals::DMA0;
 /// Static flag to track whether DMA has been initialized.
 static DMA_INITIALIZED: AtomicBool = AtomicBool::new(false);
 
-/// Ensure DMA is initialized (clock enabled, reset released, controller configured).
+/// Initialize DMA controller (clock enabled, reset released, controller configured).
 ///
-/// This function is idempotent - it will only initialize DMA once, even if called
-/// multiple times. It is automatically called when creating a DmaChannel.
+/// This function is intended to be called during HAL initialization (`hal::init()`).
+/// It is idempotent - it will only initialize DMA once, even if called multiple times.
 ///
-/// # Safety
-///
-/// This function accesses hardware registers and must be called from a context
-/// where such access is safe (typically during system initialization or with
-/// interrupts properly managed).
-pub fn ensure_init() {
+/// The function enables the DMA0 clock, releases reset, and configures the controller
+/// for normal operation with round-robin arbitration.
+pub fn init() {
     // Fast path: already initialized
     if DMA_INITIALIZED.load(Ordering::Acquire) {
         return;
@@ -334,6 +331,16 @@ pub enum EnableInterrupt {
 }
 
 // ============================================================================
+// 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 Constants
 // ============================================================================
 
@@ -531,11 +538,9 @@ pub struct DmaChannel<C: Channel> {
 impl<C: Channel> DmaChannel<C> {
     /// Wrap a DMA channel token (takes ownership of the Peri wrapper).
     ///
-    /// This automatically initializes the DMA controller if not already done
-    /// (enables clock, releases reset, configures controller).
+    /// Note: DMA is initialized during `hal::init()` via `dma::init()`.
     #[inline]
     pub fn new(_ch: embassy_hal_internal::Peri<'_, C>) -> Self {
-        ensure_init();
         Self {
             _ch: core::marker::PhantomData,
         }
@@ -543,10 +548,9 @@ impl<C: Channel> DmaChannel<C> {
 
     /// Wrap a DMA channel token directly (for internal use).
     ///
-    /// This automatically initializes the DMA controller if not already done.
+    /// Note: DMA is initialized during `hal::init()` via `dma::init()`.
     #[inline]
     pub fn from_token(_ch: C) -> Self {
-        ensure_init();
         Self {
             _ch: core::marker::PhantomData,
         }
@@ -2205,6 +2209,9 @@ impl<C: Channel> DmaChannel<C> {
         // 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)
     }
 }
diff --git a/src/lib.rs b/src/lib.rs
index d3560e651..d721f53e6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -373,6 +373,9 @@ pub fn init(cfg: crate::config::Config) -> Peripherals {
         crate::gpio::init();
     }
 
+    // Initialize DMA controller (clock, reset, configuration)
+    crate::dma::init();
+
     // Initialize embassy-time global driver backed by OSTIMER0
     #[cfg(feature = "time")]
     crate::ostimer::time_driver::init(crate::config::Config::default().time_interrupt_priority, 1_000_000);
diff --git a/src/lpuart/mod.rs b/src/lpuart/mod.rs
index 1f8904e9c..bcac1fdbd 100644
--- a/src/lpuart/mod.rs
+++ b/src/lpuart/mod.rs
@@ -18,7 +18,7 @@ pub mod buffered;
 // DMA INTEGRATION
 // ============================================================================
 
-use crate::dma::{Channel as DmaChannelTrait, DmaChannel, EnableInterrupt};
+use crate::dma::{Channel as DmaChannelTrait, DmaChannel, EnableInterrupt, RingBuffer, DMA_MAX_TRANSFER_SIZE};
 
 // ============================================================================
 // MISC
@@ -1056,9 +1056,6 @@ impl<'a> Lpuart<'a, Blocking> {
 // ASYNC MODE IMPLEMENTATIONS (DMA-based)
 // ============================================================================
 
-/// Maximum bytes per DMA transfer (eDMA CITER/BITER are 15-bit fields).
-const DMA_MAX_TRANSFER_SIZE: usize = 0x7FFF;
-
 /// Guard struct that ensures DMA is stopped if the async future is cancelled.
 ///
 /// This implements the RAII pattern: if the future is dropped before completion
@@ -1357,6 +1354,68 @@ impl<'a, T: Instance, C: DmaChannelTrait> LpuartRxDma<'a, T, C> {
         }
         Ok(())
     }
+
+    /// Set up a ring buffer for continuous DMA reception.
+    ///
+    /// This configures the DMA channel for circular operation, enabling continuous
+    /// reception of data without gaps. The DMA will continuously write received
+    /// bytes into the buffer, wrapping around when it reaches the end.
+    ///
+    /// This method encapsulates all the low-level setup:
+    /// - Configures the DMA request source for this LPUART instance
+    /// - Enables the RX DMA request in the LPUART peripheral
+    /// - Sets up the circular DMA transfer
+    /// - Enables the NVIC interrupt for async wakeups
+    ///
+    /// # Arguments
+    ///
+    /// * `buf` - Destination buffer for received data (power-of-2 size is ideal for efficiency)
+    ///
+    /// # Returns
+    ///
+    /// A [`RingBuffer`] that can be used to asynchronously read received data.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// static mut RX_BUF: [u8; 64] = [0; 64];
+    ///
+    /// let rx = LpuartRxDma::new(p.LPUART2, p.P2_3, p.DMA_CH0, config).unwrap();
+    /// let ring_buf = unsafe { rx.setup_ring_buffer(&mut RX_BUF) };
+    ///
+    /// // Read data as it arrives
+    /// let mut buf = [0u8; 16];
+    /// let n = ring_buf.read(&mut buf).await.unwrap();
+    /// ```
+    ///
+    /// # Safety
+    ///
+    /// - The buffer must remain valid for the lifetime of the returned RingBuffer.
+    /// - Only one RingBuffer should exist per LPUART RX channel at a time.
+    /// - The caller must ensure the static buffer is not accessed elsewhere while
+    ///   the ring buffer is active.
+    pub unsafe fn setup_ring_buffer<'b>(&self, buf: &'b mut [u8]) -> RingBuffer<'b, u8> {
+        // Get the peripheral data register address
+        let peri_addr = self.info.regs.data().as_ptr() as *const u8;
+
+        // Configure DMA request source for this LPUART instance
+        self.rx_dma.set_request_source(T::RX_DMA_REQ);
+
+        // Enable RX DMA request in the LPUART peripheral
+        self.info.regs.baud().modify(|_, w| w.rdmae().enabled());
+
+        // Set up circular DMA transfer (this also enables NVIC interrupt)
+        self.rx_dma.setup_circular_read(peri_addr, buf)
+    }
+
+    /// Enable the DMA channel request.
+    ///
+    /// Call this after `setup_ring_buffer()` to start continuous reception.
+    /// This is separated from setup to allow for any additional configuration
+    /// before starting the transfer.
+    pub unsafe fn enable_dma_request(&self) {
+        self.rx_dma.enable_request();
+    }
 }
 
 impl<'a, T: Instance, TxC: DmaChannelTrait, RxC: DmaChannelTrait> LpuartDma<'a, T, TxC, RxC> {