feat(dma): retain per-channel transfer data

Retain independent known data across DMA blocks. Duplicate mapped halfword sources and select the destination lane for blocked sources below work RAM. Keep cold history diagnostic, commit only successful units, and preserve separate CPU/BIOS history rules.

Add 13 original regressions and pinned source research. CPU resume ownership, general DMA open bus, and IWRAM DMA lane effects remain explicit limits.

Validated on Darwin arm64: 930 workspace and 861 core/demo tests in debug and release, 39 Python tests, native ROM windows, ten window smoke modes, fmt, clippy, and rustdoc. Public ARM/Thumb/memory/BIOS reports match the previous results exactly.

crates/gba-core/src/dma.rs

@@ -1,6 +1,7 @@
 //! Four-channel GBA direct memory access (DMA) controller.
 //! Transfers are scheduled one data unit at a time. Startup/resumption delays,
-//! open-bus latches, sound FIFO, video capture, and Game Pak DRQ are not modeled.
+//! CPU bus handoff, sound FIFO, video capture, and Game Pak DRQ are not modeled.
+//! Each channel retains known source data across blocks, including blocked reads.
 
 use std::{error::Error, fmt};
 
@@ -65,6 +66,8 @@ struct Channel {
     remaining: u32,
     active: bool,
     first: bool,
+    // Unknown at synthetic startup. Enable/disable does not reset retained data.
+    data_latch: Option<u32>,
 }
 
 impl Channel {
@@ -111,6 +114,7 @@ pub(crate) struct Transfer {
     pub destination: u32,
     pub width: AccessWidth,
     pub first: bool,
+    pub data_latch: Option<u32>,
 }
 
 impl Dma {
@@ -199,6 +203,7 @@ impl Dma {
                     destination: channel.current_destination,
                     width: channel.width(),
                     first: channel.first,
+                    data_latch: channel.data_latch,
                 }));
             }
         }
@@ -206,8 +211,9 @@ impl Dma {
     }
 
     /// Commit one successful data unit after its bus cycles. Return completion IRQ bits.
-    pub(crate) fn complete_unit(&mut self, index: usize) -> u16 {
+    pub(crate) fn complete_unit(&mut self, index: usize, data_latch: u32) -> u16 {
         let channel = &mut self.channels[index];
+        channel.data_latch = Some(data_latch);
         let width = channel.width().bytes();
         // The Game Pak source counter increments regardless of source control.
         let source_mode = if (0x08..=0x0d).contains(&(channel.current_source >> 24)) {

crates/gba-core/src/io.rs

@@ -383,8 +383,8 @@ impl Io {
         self.dma.next()
     }
 
-    pub(crate) fn complete_dma_unit(&mut self, channel: usize) {
-        self.pending |= self.dma.complete_unit(channel);
+    pub(crate) fn complete_dma_unit(&mut self, channel: usize, data_latch: u32) {
+        self.pending |= self.dma.complete_unit(channel, data_latch);
         self.wake_if_requested();
     }
 

crates/gba-core/src/memory.rs

@@ -67,7 +67,8 @@ struct CpuAccess {
 /// Protected BIOS reads separately retain the snapshot from BIOS execution.
 /// Sequential Thumb IWRAM accesses retain addressed bus lanes transactionally.
 /// Successful refills into Thumb IWRAM sample the target pair to establish history.
-/// A full fetch pipeline, ARM-target refill history, and DMA bus latches are not modeled.
+/// DMA channels retain transfer data separately; CPU bus handoff remains unmodeled.
+/// A full fetch pipeline and ARM-target refill history are not modeled.
 pub struct Memory {
     external_ram: Vec<u8>,
     internal_ram: Vec<u8>,
@@ -268,7 +269,7 @@ impl Memory {
                 address: transfer.destination,
             });
         }
-        if transfer.source < 0x0200_0000 {
+        if transfer.source < 0x0200_0000 && transfer.data_latch.is_none() {
             return Err(DmaError::UnsupportedSource {
                 channel,
                 address: transfer.source,
@@ -281,18 +282,33 @@ impl Memory {
             });
         }
         let map_error = |error| DmaError::Memory { channel, error };
-        // Reads have no side effects. A failed destination leaves the unit pending.
+        // Validate before reading or committing channel data. Failed units are atomic.
+        match transfer.width {
+            AccessWidth::Halfword => self.write_index::<2>(transfer.destination),
+            AccessWidth::Word => self.write_index::<4>(transfer.destination),
+            AccessWidth::Byte => unreachable!("DMA is never byte-wide"),
+        }
+        .map_err(map_error)?;
+        let data_latch = if transfer.source < 0x0200_0000 {
+            // DMA cannot read BIOS or the lower unused region. Retain this channel's
+            // full word; never read firmware bytes or borrow CPU/another channel's data.
+            transfer
+                .data_latch
+                .expect("unknown blocked source rejected above")
+        } else {
+            match transfer.width {
+                AccessWidth::Halfword => {
+                    u32::from(self.read16(transfer.source).map_err(map_error)?) * 0x0001_0001
+                }
+                AccessWidth::Word => self.read32(transfer.source).map_err(map_error)?,
+                AccessWidth::Byte => unreachable!("DMA is never byte-wide"),
+            }
+        };
+        // A blocked halfword read keeps both old lanes. The destination selects
+        // one lane; mapped halfword reads have already duplicated their source data.
         let value = match transfer.width {
-            AccessWidth::Halfword => {
-                self.write_index::<2>(transfer.destination)
-                    .map_err(map_error)?;
-                u32::from(self.read16(transfer.source).map_err(map_error)?)
-            }
-            AccessWidth::Word => {
-                self.write_index::<4>(transfer.destination)
-                    .map_err(map_error)?;
-                self.read32(transfer.source).map_err(map_error)?
-            }
+            AccessWidth::Halfword => data_latch >> ((transfer.destination & 2) * 8),
+            AccessWidth::Word => data_latch,
             AccessWidth::Byte => unreachable!("DMA is never byte-wide"),
         };
         let kind = if transfer.first {
@@ -318,7 +334,7 @@ impl Memory {
         // Keep this channel active during its cycles: another edge must not
         // queue a second block while the current block is still transferring.
         self.advance_cycles(timing.total());
-        self.io.complete_dma_unit(channel);
+        self.io.complete_dma_unit(channel, data_latch);
         Ok(Some((channel, timing)))
     }
 

crates/gba-core/tests/dma.rs

@@ -8,6 +8,9 @@ use gba_core::{
     timing::{bus_cycles, AccessKind, AccessWidth},
 };
 
+#[path = "dma/latch.rs"]
+mod latch;
+
 const SOURCE: u32 = 0x0200_0000;
 const DEST: u32 = 0x0300_0000;
 

crates/gba-core/tests/dma/latch.rs

@@ -0,0 +1,297 @@
+//! Original tests of per-channel retained data, not CPU open-bus handoff.
+use super::*;
+
+const DATA: u32 = 0x9a73_b5e1;
+const OTHER: u32 = 0x2468_1357;
+
+fn seed(machine: &mut Machine, channel: usize, value: u32) {
+    machine.memory_mut().write32(SOURCE, value).unwrap();
+    configure(machine.memory_mut(), channel, SOURCE, DEST, 1, 0x400);
+    units(machine, channel, 1);
+}
+
+fn blocked(machine: &mut Machine, channel: usize, destination: u32, control: u16) {
+    configure(machine.memory_mut(), channel, 0, destination, 1, control);
+    units(machine, channel, 1);
+}
+
+#[test]
+fn blocked_sources_reuse_each_channels_word_without_reading_bios() {
+    for channel in 0..4 {
+        for source in [0, 0x3ffc, 0x4000, 0x0100_0000, 0x01ff_fffc] {
+            let mut bios = vec![0x62; BIOS_SIZE];
+            bios[..4].copy_from_slice(&OTHER.to_le_bytes());
+            let mut machine = Machine::new(
+                Cpu::new(ROM_START),
+                Memory::with_bios(words(&[0xeaff_fffe]), bios).unwrap(),
+            );
+            seed(&mut machine, channel, DATA);
+            machine.memory_mut().write32(SOURCE, 0).unwrap();
+            assert_eq!(machine.memory().read32(0).unwrap(), OTHER);
+            configure(machine.memory_mut(), channel, source, DEST + 4, 1, 0x400);
+            units(&mut machine, channel, 1);
+            assert_eq!(machine.memory().read32(DEST + 4).unwrap(), DATA);
+            assert!(!enabled(&machine, channel));
+        }
+    }
+}
+
+#[test]
+fn blocked_halfwords_select_destination_lane_and_do_not_duplicate_retained_word() {
+    for channel in 0..4 {
+        let mut machine = machine();
+        seed(&mut machine, channel, DATA);
+        // Neither source alignment nor halfword width may replace the old full word.
+        for source in [0, 2, 0x3ffe, 0x01ff_fffe] {
+            for lane in [0, 2] {
+                configure(machine.memory_mut(), channel, source, DEST + 4 + lane, 1, 0);
+                units(&mut machine, channel, 1);
+            }
+            assert_eq!(machine.memory().read32(DEST + 4).unwrap(), DATA);
+        }
+        blocked(&mut machine, channel, DEST + 8, 0x400);
+        assert_eq!(machine.memory().read32(DEST + 8).unwrap(), DATA);
+    }
+}
+
+#[test]
+fn mapped_halfword_sources_duplicate_either_source_lane_in_the_channel_latch() {
+    for channel in 0..4 {
+        for source_lane in [0, 2] {
+            for destination_lane in [0, 2] {
+                let mut machine = machine();
+                seed(&mut machine, channel, OTHER);
+                machine.memory_mut().write32(SOURCE, DATA).unwrap();
+                configure(
+                    machine.memory_mut(),
+                    channel,
+                    SOURCE + source_lane,
+                    DEST + destination_lane,
+                    1,
+                    0,
+                );
+                units(&mut machine, channel, 1);
+                let half = (DATA >> (source_lane * 8)) as u16;
+                assert_eq!(
+                    machine.memory().read16(DEST + destination_lane).unwrap(),
+                    half
+                );
+                blocked(&mut machine, channel, DEST + 4, 0x400);
+                assert_eq!(
+                    machine.memory().read32(DEST + 4).unwrap(),
+                    u32::from(half) * 0x10001
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn latches_are_independent_and_survive_completion_disable_and_host_access() {
+    let mut machine = machine();
+    for channel in 0..4 {
+        seed(&mut machine, channel, DATA ^ (0x1111_1111 * channel as u32));
+    }
+    machine.memory_mut().write32(SOURCE, OTHER).unwrap();
+    assert_eq!(machine.memory().read32(SOURCE).unwrap(), OTHER);
+    for channel in (0..4).rev() {
+        machine.memory_mut().write16(base(channel) + 10, 0).unwrap();
+        blocked(&mut machine, channel, DEST + channel as u32 * 4, 0x400);
+        assert_eq!(
+            machine.memory().read32(DEST + channel as u32 * 4).unwrap(),
+            DATA ^ (0x1111_1111 * channel as u32)
+        );
+    }
+}
+
+#[test]
+fn cold_channel_stays_unknown_despite_other_channels_and_host_reads() {
+    for channel in 0..4 {
+        let mut machine = machine();
+        seed(&mut machine, (channel + 1) % 4, DATA);
+        assert_eq!(machine.memory().read32(DEST).unwrap(), DATA);
+        configure(machine.memory_mut(), channel, 0, DEST + 4, 1, 0x4400);
+        let cycles = machine.cycles();
+        let timing = machine.last_timing();
+        let cpu = machine.cpu().clone();
+        for _ in 0..2 {
+            assert_eq!(
+                machine.step(),
+                Err(MachineError::Dma(DmaError::UnsupportedSource {
+                    channel,
+                    address: 0
+                }))
+            );
+            assert_eq!(machine.cpu(), &cpu);
+            assert_eq!(machine.cycles(), cycles);
+            assert_eq!(machine.last_timing(), timing);
+            assert_eq!(machine.memory().read32(DEST + 4).unwrap(), 0);
+            assert_eq!(machine.memory().read16(IF).unwrap(), 0);
+            assert!(enabled(&machine, channel));
+        }
+    }
+}
+
+#[test]
+fn zero_is_known_data_not_an_unknown_latch() {
+    let mut machine = machine();
+    seed(&mut machine, 3, 0);
+    machine.memory_mut().write32(DEST + 4, u32::MAX).unwrap();
+    blocked(&mut machine, 3, DEST + 4, 0x400);
+    assert_eq!(machine.memory().read32(DEST + 4).unwrap(), 0);
+}
+
+#[test]
+fn failed_units_preserve_the_old_latch_without_new_data_or_irq() {
+    for (source, destination, control) in [
+        (0x0e00_0000, DEST, 0x4400), // Unmapped reads do not use a known latch.
+        (SOURCE, ROM_START, 0x4400),
+        (SOURCE, 0x0400_0058, 0x4400),
+        (SOURCE, DMA_BASE, 0x4400),
+        (SOURCE, 0x0400_0300, 0x4400),
+        (SOURCE, DEST, 0x4580), // Unsupported source mode.
+        (0, ROM_START, 0x4400), // A blocked source cannot bypass destination checks.
+    ] {
+        let mut machine = machine();
+        seed(&mut machine, 3, DATA);
+        machine.memory_mut().write32(SOURCE, OTHER).unwrap();
+        configure(machine.memory_mut(), 3, source, destination, 1, control);
+        let cycles = machine.cycles();
+        let timing = machine.last_timing();
+        for _ in 0..2 {
+            assert!(machine.step().is_err());
+            assert_eq!(machine.cycles(), cycles);
+            assert_eq!(machine.last_timing(), timing);
+            assert_eq!(machine.memory().read16(IF).unwrap(), 0);
+            assert_eq!(machine.memory().read32(DEST).unwrap(), DATA);
+        }
+        machine.memory_mut().write16(base(3) + 10, 0).unwrap();
+        blocked(&mut machine, 3, DEST + 4, 0x400);
+        assert_eq!(machine.memory().read32(DEST + 4).unwrap(), DATA);
+    }
+}
+
+#[test]
+fn failed_destination_does_not_seed_a_cold_channel() {
+    let mut machine = machine();
+    machine.memory_mut().write32(SOURCE, DATA).unwrap();
+    configure(machine.memory_mut(), 3, SOURCE, ROM_START, 1, 0x400);
+    assert!(machine.step().is_err());
+    machine.memory_mut().write16(base(3) + 10, 0).unwrap();
+    configure(machine.memory_mut(), 3, 0, DEST, 1, 0x400);
+    assert_eq!(
+        machine.step(),
+        Err(MachineError::Dma(DmaError::UnsupportedSource {
+            channel: 3,
+            address: 0
+        }))
+    );
+    assert_eq!(machine.cycles(), 0);
+}
+
+#[test]
+fn source_counter_crossing_into_blocked_region_retains_the_last_completed_unit() {
+    let mut machine = machine();
+    machine.memory_mut().write32(SOURCE, DATA).unwrap();
+    configure(machine.memory_mut(), 3, SOURCE, DEST, 3, 0x4480); // Decrement word source, IRQ.
+    units(&mut machine, 3, 3);
+    for offset in [0, 4, 8] {
+        assert_eq!(machine.memory().read32(DEST + offset).unwrap(), DATA);
+    }
+    assert_eq!(machine.cycles(), 13); // 6+1+2, then two 1+1 units.
+    assert_eq!(machine.memory().read16(IF).unwrap(), 1 << 11);
+    assert!(!enabled(&machine, 3));
+}
+
+#[test]
+fn failed_later_read_retains_last_successful_halfword_not_partial_bytes() {
+    let mut machine = Machine::new(
+        Cpu::new(ROM_START),
+        Memory::new(vec![0x37, 0x92, 0x6a]).unwrap(),
+    );
+    configure(machine.memory_mut(), 3, ROM_START, DEST, 2, 0);
+    units(&mut machine, 3, 1);
+    assert!(machine.step().is_err());
+    machine.memory_mut().write16(base(3) + 10, 0).unwrap();
+    blocked(&mut machine, 3, DEST + 4, 0x400);
+    assert_eq!(machine.memory().read32(DEST + 4).unwrap(), 0x9237_9237);
+}
+
+#[test]
+fn cancellation_keeps_the_last_completed_unit_not_programmed_source_bytes() {
+    let mut machine = machine();
+    machine.memory_mut().write32(SOURCE, DATA).unwrap();
+    machine.memory_mut().write32(SOURCE + 4, OTHER).unwrap();
+    configure(machine.memory_mut(), 3, SOURCE, DEST, 3, 0x400);
+    units(&mut machine, 3, 2);
+    assert!(enabled(&machine, 3));
+    machine.memory_mut().write16(base(3) + 10, 0).unwrap();
+    machine.memory_mut().write32(SOURCE + 4, 0).unwrap();
+    blocked(&mut machine, 3, DEST + 8, 0x400);
+    assert_eq!(machine.memory().read32(DEST + 8).unwrap(), OTHER);
+}
+
+#[test]
+fn blocked_dma_does_not_read_or_replace_the_protected_cpu_bios_word() {
+    let mut bios = vec![0; BIOS_SIZE];
+    bios[..16].copy_from_slice(&words(&[
+        0xe59f_0000, // LDR r0,[pc]: ROM destination.
+        0xe12f_ff10, // BX r0: retained BIOS word comes from address 12.
+        ROM_START,
+        OTHER,
+    ]));
+    let mut machine = Machine::new(
+        Cpu::new(0),
+        Memory::with_bios(words(&[0xe592_1000, 0xeaff_fffe, 0]), bios).unwrap(),
+    ); // ROM LDR r1,[r2], with r2=0.
+    for _ in 0..2 {
+        assert_eq!(machine.step().unwrap(), StepKind::Instruction);
+    }
+    seed(&mut machine, 3, DATA);
+    blocked(&mut machine, 3, DEST + 4, 0x400);
+    assert_eq!(machine.memory().read32(DEST + 4).unwrap(), DATA);
+    assert_eq!(machine.memory().read32(0).unwrap(), 0xe59f_0000);
+    assert_eq!(machine.step().unwrap(), StepKind::Instruction);
+    assert_eq!(machine.cpu().registers()[1], OTHER);
+}
+
+#[test]
+fn repeated_hblank_blocks_and_priority_keep_channel_history_and_nominal_clocks() {
+    let mut machine = machine();
+    seed(&mut machine, 0, OTHER);
+    seed(&mut machine, 3, DATA);
+    machine
+        .memory_mut()
+        .write32(TIMER_BASE, 0x0080_0000)
+        .unwrap();
+    let start = machine.cycles();
+    for channel in [3, 0] {
+        configure(
+            machine.memory_mut(),
+            channel,
+            0,
+            DEST + 8 + channel as u32 * 8,
+            1,
+            0x6340,
+        );
+    } // Halfword, fixed source, increment/reload destination, HBlank repeat, IRQ.
+    for cycle in [
+        u64::from(HBLANK_START),
+        u64::from(HBLANK_START + CYCLES_PER_LINE),
+    ] {
+        advance_to(&mut machine, cycle);
+        for channel in [0, 3] {
+            units(&mut machine, channel, 1);
+            assert_eq!(machine.last_timing().data_cycles, 2);
+            assert_eq!(machine.last_timing().internal_cycles, 2);
+            assert!(enabled(&machine, channel));
+        }
+        assert_eq!(machine.memory().read16(DEST + 8).unwrap(), OTHER as u16);
+        assert_eq!(machine.memory().read16(DEST + 32).unwrap(), DATA as u16);
+        assert_eq!(machine.memory().read16(IF).unwrap() & 0x900, 0x900);
+    }
+    assert_eq!(
+        u64::from(machine.memory().read16(TIMER_BASE).unwrap()),
+        machine.cycles() - start
+    );
+}