1 files changed, 244 insertions, 0 deletions

diff --git a/examples/mcxa/src/bin/raw_dma_ping_pong_transfer.rs b/examples/mcxa/src/bin/raw_dma_ping_pong_transfer.rs
new file mode 100644
index 000000000..80df40449
--- /dev/null
+++ b/examples/mcxa/src/bin/raw_dma_ping_pong_transfer.rs
@@ -0,0 +1,244 @@
+//! DMA ping-pong/double-buffer transfer example for MCXA276.
+//!
+//! NOTE: this is a "raw dma" example! It exists as a proof of concept, as we don't have
+//! a high-level and safe API for. It should not be taken as typical, recommended, or
+//! stable usage!
+//!
+//! This example demonstrates two approaches for ping-pong/double-buffering:
+//!
+//! ## Approach 1: Scatter/Gather with linked TCDs (manual)
+//! - Two TCDs link to each other for alternating transfers
+//! - Uses custom handler that delegates to on_interrupt() then signals completion
+//! - Note: With ESG=1, DONE bit is cleared by hardware when next TCD loads,
+//!   so we need an AtomicBool to track completion
+//!
+//! ## Approach 2: Half-transfer interrupt with wait_half() (NEW!)
+//! - Single continuous transfer over entire buffer
+//! - Uses half-transfer interrupt to know when first half is ready
+//! - Application can process first half while second half is being filled
+//!
+//! # Embassy-style features demonstrated:
+//! - `DmaChannel::new()` for channel creation
+//! - Scatter/gather with linked TCDs
+//! - Custom handler that delegates to HAL's `on_interrupt()` (best practice)
+//! - Standard `DmaCh1InterruptHandler` with `bind_interrupts!` macro
+//! - NEW: `wait_half()` for half-transfer interrupt handling
+
+#![no_std]
+#![no_main]
+
+use embassy_executor::Spawner;
+use embassy_mcxa::clocks::config::Div8;
+use embassy_mcxa::dma::{DmaChannel, Tcd, TransferOptions};
+use embassy_mcxa::pac;
+use static_cell::ConstStaticCell;
+use {defmt_rtt as _, embassy_mcxa as hal, panic_probe as _};
+
+// Source and destination buffers for Approach 1 (scatter/gather)
+static SRC: ConstStaticCell<[u32; 8]> = ConstStaticCell::new([1, 2, 3, 4, 5, 6, 7, 8]);
+static DST: ConstStaticCell<[u32; 8]> = ConstStaticCell::new([0; 8]);
+
+// Source and destination buffers for Approach 2 (wait_half)
+static SRC2: ConstStaticCell<[u32; 8]> = ConstStaticCell::new([0xA1, 0xA2, 0xA3, 0xA4, 0xB1, 0xB2, 0xB3, 0xB4]);
+static DST2: ConstStaticCell<[u32; 8]> = ConstStaticCell::new([0; 8]);
+
+// TCD pool for scatter/gather - must be 32-byte aligned
+#[repr(C, align(32))]
+struct TcdPool([Tcd; 2]);
+
+static TCD_POOL: ConstStaticCell<TcdPool> = ConstStaticCell::new(TcdPool(
+    [Tcd {
+        saddr: 0,
+        soff: 0,
+        attr: 0,
+        nbytes: 0,
+        slast: 0,
+        daddr: 0,
+        doff: 0,
+        citer: 0,
+        dlast_sga: 0,
+        csr: 0,
+        biter: 0,
+    }; 2],
+));
+
+#[embassy_executor::main]
+async fn main(_spawner: Spawner) {
+    // Small delay to allow probe-rs to attach after reset
+    for _ in 0..100_000 {
+        cortex_m::asm::nop();
+    }
+
+    let mut cfg = hal::config::Config::default();
+    cfg.clock_cfg.sirc.fro_12m_enabled = true;
+    cfg.clock_cfg.sirc.fro_lf_div = Some(Div8::no_div());
+    let p = hal::init(cfg);
+
+    defmt::info!("DMA ping-pong transfer example starting...");
+
+    defmt::info!("EDMA ping-pong transfer example begin.");
+
+    // Initialize buffers
+    let src = SRC.take();
+    let dst = DST.take();
+
+    defmt::info!("Source Buffer: {=[?]}", src.as_slice());
+    defmt::info!("Destination Buffer (before): {=[?]}", dst.as_slice());
+
+    defmt::info!("Configuring ping-pong DMA with Embassy-style API...");
+
+    let dma_ch0 = DmaChannel::new(p.DMA_CH0);
+
+    // Configure ping-pong transfer using direct TCD access:
+    // This sets up TCD0 and TCD1 in RAM, and loads TCD0 into the channel.
+    // TCD0 transfers first half (SRC[0..4] -> DST[0..4]), links to TCD1.
+    // TCD1 transfers second half (SRC[4..8] -> DST[4..8]), links to TCD0.
+    let tcds = &mut TCD_POOL.take().0;
+
+    let half_len = 4usize;
+    let half_bytes = (half_len * 4) as u32;
+
+    unsafe {
+        let tcd0_addr = &tcds[0] as *const _ as u32;
+        let tcd1_addr = &tcds[1] as *const _ as u32;
+
+        // TCD0: First half -> Links to TCD1
+        tcds[0] = Tcd {
+            saddr: src.as_ptr() as u32,
+            soff: 4,
+            attr: 0x0202, // 32-bit src/dst
+            nbytes: half_bytes,
+            slast: 0,
+            daddr: dst.as_mut_ptr() as u32,
+            doff: 4,
+            citer: 1,
+            dlast_sga: tcd1_addr as i32,
+            csr: 0x0012, // ESG | INTMAJOR
+            biter: 1,
+        };
+
+        // TCD1: Second half -> Links to TCD0
+        tcds[1] = Tcd {
+            saddr: src.as_ptr().add(half_len) as u32,
+            soff: 4,
+            attr: 0x0202,
+            nbytes: half_bytes,
+            slast: 0,
+            daddr: dst.as_mut_ptr().add(half_len) as u32,
+            doff: 4,
+            citer: 1,
+            dlast_sga: tcd0_addr as i32,
+            csr: 0x0012,
+            biter: 1,
+        };
+
+        // Load TCD0 into hardware registers
+        dma_ch0.load_tcd(&tcds[0]);
+    }
+
+    defmt::info!("Triggering first half transfer...");
+
+    // Trigger first transfer (first half: SRC[0..4] -> DST[0..4])
+    unsafe {
+        dma_ch0.trigger_start();
+    }
+
+    let tcd = dma_ch0.tcd();
+    // Wait for first half
+    loop {
+        if tcd.tcd_saddr().read().bits() != src.as_ptr() as u32 {
+            break;
+        }
+    }
+
+    defmt::info!("First half transferred.");
+    defmt::info!("Triggering second half transfer...");
+
+    // Trigger second transfer (second half: SRC[4..8] -> DST[4..8])
+    unsafe {
+        dma_ch0.trigger_start();
+    }
+
+    // Wait for second half
+    loop {
+        if tcd.tcd_saddr().read().bits() != unsafe { src.as_ptr().add(half_len) } as u32 {
+            break;
+        }
+    }
+
+    defmt::info!("Second half transferred.");
+
+    defmt::info!("EDMA ping-pong transfer example finish.");
+    defmt::info!("Destination Buffer (after): {=[?]}", dst.as_slice());
+
+    // Verify: DST should match SRC
+    let mismatch = src != dst;
+
+    if mismatch {
+        defmt::error!("FAIL: Approach 1 mismatch detected!");
+    } else {
+        defmt::info!("PASS: Approach 1 data verified.");
+    }
+
+    // =========================================================================
+    // Approach 2: Half-Transfer Interrupt with wait_half() (NEW!)
+    // =========================================================================
+    //
+    // This approach uses a single continuous DMA transfer with half-transfer
+    // interrupt enabled. The wait_half() method allows you to be notified
+    // when the first half of the buffer is complete, so you can process it
+    // while the second half is still being filled.
+    //
+    // Benefits:
+    // - Simpler setup (no TCD pool needed)
+    // - True async/await support
+    // - Good for streaming data processing
+
+    defmt::info!("--- Approach 2: wait_half() demo ---");
+
+    // Enable DMA CH1 interrupt
+    unsafe {
+        cortex_m::peripheral::NVIC::unmask(pac::Interrupt::DMA_CH1);
+    }
+
+    // Initialize approach 2 buffers
+    let src2 = SRC2.take();
+    let dst2 = DST2.take();
+
+    defmt::info!("SRC2: {=[?]}", src2.as_slice());
+
+    let dma_ch1 = DmaChannel::new(p.DMA_CH1);
+
+    // Configure transfer with half-transfer interrupt enabled
+    let mut options = TransferOptions::default();
+    options.half_transfer_interrupt = true; // Enable half-transfer interrupt
+    options.complete_transfer_interrupt = true;
+
+    defmt::info!("Starting transfer with half_transfer_interrupt...");
+
+    // Create the transfer
+    let mut transfer = dma_ch1.mem_to_mem(src2, dst2, options).unwrap();
+
+    // Wait for half-transfer (first 4 elements)
+    defmt::info!("Waiting for first half...");
+    let _ok = transfer.wait_half().await.unwrap();
+
+    defmt::info!("Half-transfer complete!");
+
+    // Wait for complete transfer
+    defmt::info!("Waiting for second half...");
+    transfer.await.unwrap();
+
+    defmt::info!("Transfer complete! Full DST2: {=[?]}", dst2.as_slice());
+
+    // Verify approach 2
+    let mismatch2 = src2 != dst2;
+
+    if mismatch2 {
+        defmt::error!("FAIL: Approach 2 mismatch!");
+    } else {
+        defmt::info!("PASS: Approach 2 verified.");
+    }
+
+    defmt::info!("=== All ping-pong demos complete ===");
+}