feat(memory): retain sequential Thumb IWRAM bus lanes

Track a separate IWRAM latch with known lanes and transactional updates. Sequential Thumb prefetches and IWRAM byte/halfword/word reads and writes drive only addressed lanes. Other regions and host inspection do not replace the latch. Failed instructions discard staged changes.

Keep cold, refill, discontinuous-entry, IRQ, and DMA-transition history conservative. Share Thumb refill classification with nominal timing, including PC writes to fallthrough. Successful DMA and accepted machine IRQs invalidate history; failed DMA preserves it. Document source evidence, bounded scope, and remaining hardware-validation limits.

Add original lane, alignment, mirror/wrap, signed/unaligned-load, mode, block-transfer, rollback, isolation, control-flow, IRQ/DMA, and nominal-cost regressions. Darwin arm64 validation: 905 workspace tests and 836 core/demo tests per debug/release profile; 39 preparation tests; native ROM windows in both profiles; ten graphics/window smoke modes; fmt, clippy, and rustdoc. Public ARM, Thumb, memory, and BIOS reports remain identical to prior passing reports and between profiles.

docs/architecture.md

@@ -30,6 +30,8 @@ The repository is a Cargo workspace with three crates:
 | `crates/gba-core/src/cpu/bios_access_tests.rs` | Original CPU BIOS protection regressions for retained history, modes, widths, exception returns, and diagnostics |
 | `crates/gba-core/src/cpu/thumb_bios_access_tests.rs` | Thumb BIOS aligned-word snapshots, transitions, load lanes, boundaries, diagnostics, and nominal timing |
 | `crates/gba-core/src/cpu/thumb_open_bus_tests.rs` | Region-dependent Thumb open bus, mirrors, widths, transfers, source boundaries, isolation, and nominal timing |
+| `crates/gba-core/src/cpu/iwram_open_bus_tests.rs` | Sequential IWRAM lane history, access widths, isolation, errors, refills, IRQ/DMA invalidation, and nominal timing |
+| `crates/gba-core/src/memory/iwram_bus.rs` | Transactional known-lane history for sequential Thumb IWRAM execution |
 | `crates/gba-core/src/cpu/compare_psr_tests.rs` | Original Rd=15 test/compare status restoration, flags, bank, and timing regressions |
 | `crates/gba-core/src/cpu/status_tests.rs`, `crates/gba-core/src/cpu/exception_tests.rs` | Status, banking, exception, and return tests |
 | `crates/gba-core/src/cpu/thumb_tests.rs` | Thumb instructions, state switching, and decoder checks |

docs/hardware/cpu.md

@@ -97,12 +97,12 @@ Host inspection, ROM-suite memory assertions, instruction fetches, and DMA do no
 
 Limits remain explicit:
 
-- Thumb open bus uses the supported region rules below. Internal work RAM still needs unmodeled bus history.
+- Thumb open bus uses the supported region rules below, including bounded sequential internal-RAM lane history.
 - [BIOS-protected reads](bios.md#cpu-bios-read-protection) use separate retained ARM PC+8 or aligned Thumb PC+4 word snapshots.
 - Unused/write-only I/O reads, DMA latches, and disabled-RAM reads are not modeled here.
 - Missing BIOS, truncated ROM, unsupported I/O, and save-memory accesses retain their existing diagnostics.
 - Unused-memory writes remain diagnostics rather than ignored hardware writes. Swaps cannot silently discard their write.
-- No persistent pipeline or bus history exists. Self-modifying code and DMA-to-CPU bus transitions are not hardware-accurate.
+- There is no persistent instruction pipeline. Sequential Thumb IWRAM history does not model refills or DMA-to-CPU bus transitions.
 
 This subset lets public ARM test 362 complete. That test does not assert the loaded data value.
 Original regressions check the values separately. See [the public ARM result](../public-arm-tests.md).
@@ -116,7 +116,7 @@ The snapshot depends on the executing code region. P below is the executing inst
 | --- | --- |
 | External work RAM, palette RAM, video RAM, all three ROM windows | Halfword at P+4, repeated in both word lanes |
 | BIOS and object attribute memory (OAM) | Full word at `(P+4) & ~3` |
-| Internal work RAM (IWRAM) | Unsupported: one lane depends on previous bus activity |
+| Internal work RAM (IWRAM) | PC+4 replaces one halfword in known sequential IWRAM history; the other lanes retain their values |
 | Other code regions | Unsupported |
 
 For BIOS/OAM, aligned instructions expose halfwords at P+4 and P+6.
@@ -135,14 +135,39 @@ Snapshots add no nominal cycles. Host reads, instruction fetches, DMA, and unsup
 Protected BIOS reads use separate retained history, not the current ROM/RAM snapshot.
 
 GBATEK and nocash's [open-bus findings](https://www.ngemu.com/threads/gba-open-bus.170809/) document these region differences.
-IWRAM needs prior bus lanes, including data-load overwrites and possible DMA effects.
+IWRAM needs prior bus lanes, including IWRAM data-read/write changes and possible DMA effects.
 Do not substitute P+2 for that history: it is only the usual case, not a general rule.
 The original Nintendo DS also differs from GBA-family IWRAM behavior; this core targets GBA.
 
 This remains a bounded snapshot implementation, not a pipeline or a complete bus-history model.
-Refill timing, self-modifying code, DMA-to-CPU transitions, IWRAM, unused/write-only I/O, and disabled RAM remain incomplete.
+Refill timing, self-modifying code, DMA-to-CPU transitions, cross-state IWRAM history, unused/write-only I/O, and disabled RAM remain incomplete.
 Original regressions validate the documented formulas. No physical-hardware or independent public Thumb open-bus pass is claimed.
 
+### Sequential IWRAM history
+
+For consecutive Thumb instructions in IWRAM, the emulator retains a separate lane value and known-bit mask.
+The PC+4 halfword fetch updates its addressed halfword before execution.
+IWRAM data reads and writes then update only their addressed byte, halfword, or word lanes.
+The recorded value is raw aligned bus data, before CPU rotation or sign extension.
+Accesses to other regions do not replace the IWRAM latch.
+See [the evidence and implementation scope](../research/iwram-bus-history.md).
+
+History starts unknown. An unused-memory load requires all word lanes to be known, including for byte/halfword loads.
+Ordinary instructions and mapped loads still execute with incomplete history.
+Consecutive fetches can establish both halves. An IWRAM word read or write establishes the entire word.
+Host inspection and setup writes do not seed or change this emulated history.
+
+Each instruction stages its fetch and data-access changes.
+Success commits history only for the next sequential Thumb IWRAM PC. Failure preserves the previous committed history.
+Block-transfer data accesses stage updates in order; unused-memory reads still use one entry snapshot per instruction.
+This preserves the existing atomic diagnostic policy without adding bus or device cycles.
+
+Taken branches and PC-writing refills invalidate continuation history, even when their target is the fallthrough address.
+Untaken conditional branches keep sequential history.
+Other instruction states/regions, accepted machine IRQs, and successful DMA units end the supported history sequence.
+Failed DMA units leave history unchanged. Discontinuous entry starts unknown instead of borrowing stale lanes.
+Refill fetches, ARM-to-Thumb history, and DMA latch contents remain unmodeled.
+
 ## Processor status and exceptions
 
 User and System share registers. Each exception mode has its own stack pointer, link register, and SPSR.

docs/hardware/dma.md

@@ -55,3 +55,5 @@ DMA writes to DMA registers return `DmaError::RegisterDestination`; self-modifyi
 Other accesses use the existing memory map, alignment checks, mirrors, and I/O write rules.
 Unmapped memory and cartridge writes remain diagnostics, not hardware open-bus/latch behavior.
 A failed unit changes no memory, device state, or clock. Earlier units remain committed; the failed unit remains pending.
+Successful units invalidate bounded sequential Thumb IWRAM history because DMA-to-CPU latch ordering is not modeled.
+Failed units preserve that history. No DMA value is substituted for a CPU open-bus read.

docs/references.md

@@ -50,7 +50,7 @@ Hardware references used for the core:
 - [NanoBoyAdvance keypad implementation](https://github.com/nba-emu/NanoBoyAdvance/blob/master/src/nba/src/hw/keypad/keypad.cc), compared for control access widths; its AND/retrigger behavior differs from the chosen polling model.
 - [mGBA keypad timing issue](https://github.com/mgba-emu/mgba/issues/2490), for frontend frame-based input timing limits.
 - [Tonc hardware interrupts](https://gbadev.net/tonc/interrupts.html), for keypad source enable and IF/IE bit 12.
-- [GBATEK memory mirrors, video byte writes, and unused-memory reads](https://problemkaputt.de/gbatek-gba-unpredictable-things.htm), for unused address ranges, ARM PC+8 open bus, byte lanes, the distinct Thumb region/history rules, and PC-dependent BIOS read protection. The Thumb implementation follows its 16-bit-region and BIOS/OAM formulas; IWRAM and region-transition history remain unsupported.
+- [GBATEK memory mirrors, video byte writes, and unused-memory reads](https://problemkaputt.de/gbatek-gba-unpredictable-things.htm), for unused address ranges, ARM PC+8 open bus, byte lanes, the distinct Thumb region/history rules, and PC-dependent BIOS read protection. The Thumb implementation follows its 16-bit-region and BIOS/OAM formulas. IWRAM has bounded sequential lane history; refills and region transitions remain unsupported.
 - [nocash GBA open-bus discussion](https://www.ngemu.com/threads/gba-open-bus.170809/), for ARM prefetch, repeated Thumb halfwords in 16-bit regions, aligned BIOS/OAM words, and history-dependent IWRAM lanes. Its data-load overwrite note prevents treating P+2 as a universal IWRAM rule.
 - [mGBA memory implementation](https://github.com/mgba-emu/mgba/blob/master/src/gba/memory.c), reviewed for `GBALoadBad`, ARM prefetch sourcing, byte/halfword lane selection, and separate DMA/history behavior. Also reviewed its BIOS region-exit prefetch retention and protected-load lane selection.
 - [GBATEK GBA memory map and bus widths](https://problemkaputt.de/gbatek-gba-memory-map.htm).
@@ -104,6 +104,14 @@ Thumb BIOS fetch research:
 
 See [Thumb BIOS prefetch snapshots](research/thumb-bios-prefetch.md) for the inference, implementation limits, and original regressions.
 
+IWRAM lane-history research:
+
+- [mGBA issue 1575](https://github.com/mgba-emu/mgba/issues/1575), for reported hardware alignment results and IWRAM read/write effects.
+- [ares IWRAM accesses](https://github.com/ares-emulator/ares/blob/6f6786e04f0822a3475463df284f313ab8518d51/ares/gba/cpu/memory.cpp) and [bus dispatch](https://github.com/ares-emulator/ares/blob/6f6786e04f0822a3475463df284f313ab8518d51/ares/gba/cpu/bus.cpp), for separate byte-lane retention and debugger isolation.
+- [jgenesis issue 676](https://github.com/jsgroth/jgenesis/issues/676) and [its correction](https://github.com/jsgroth/jgenesis/commit/fab6e2ccc60e492dd68b7f1e927b0829a6d80195), for distinguishing the IWRAM latch from reads to other regions.
+
+See [IWRAM Thumb bus history](research/iwram-bus-history.md). These were source reviews, not local hardware or external-emulator test runs.
+
 Use [GBATEK](https://problemkaputt.de/gbatek.htm) and ARM7TDMI documentation for further hardware work.
 Only use game ROMs that you may lawfully use. Do not commit game ROMs, BIOS files, or game assets.
 The ignore file excludes `roms/`, common game ROM extensions, and save files.

docs/research/iwram-bus-history.md

@@ -0,0 +1,79 @@
+# IWRAM Thumb bus history
+
+## Finding
+
+Internal work RAM (IWRAM) retains its own bus lanes. A previous CPU load result is not a universal replacement.
+An IWRAM byte, halfword, or word access updates only the addressed lanes of that latch.
+A Thumb fetch updates one halfword. Reads and writes elsewhere do not replace the IWRAM latch.
+This distinction matters when Thumb code reads another memory region before an unused-memory read.
+
+For sequential Thumb execution at P, the fetch at P+4 updates:
+
+- Bits 0–15 when P is word-aligned.
+- Bits 16–31 when P has only halfword alignment.
+
+The other halfword retains its previous IWRAM value.
+Without intervening IWRAM data accesses, consecutive fetches produce GBATEK's usual P+2/P+4 combination.
+Using current bytes at P+2 would lose observed history and ignore data-access changes.
+
+## Evidence
+
+- [GBATEK](https://problemkaputt.de/gbatek-gba-unpredictable-things.htm) documents the two Thumb IWRAM lanes and warns about overwritten history.
+- [mGBA issue 1575](https://github.com/mgba-emu/mgba/issues/1575) reports hardware-based alignment expectations and read/write effects on IWRAM open bus.
+- [ares IWRAM access implementation](https://github.com/ares-emulator/ares/blob/6f6786e04f0822a3475463df284f313ab8518d51/ares/gba/cpu/memory.cpp) retains separate IWRAM lanes for byte, halfword, and word reads and writes.
+  Its [bus implementation](https://github.com/ares-emulator/ares/blob/6f6786e04f0822a3475463df284f313ab8518d51/ares/gba/cpu/bus.cpp) distinguishes this latch from the general data bus and debugger access.
+- [jgenesis issue 676](https://github.com/jsgroth/jgenesis/issues/676) identifies failures after byte/halfword reads from other regions.
+  The [correction at fab6e2cc](https://github.com/jsgroth/jgenesis/commit/fab6e2ccc60e492dd68b7f1e927b0829a6d80195) adds a separate IWRAM latch.
+  The commit reports that its openbuster tests pass. That report is upstream evidence, not a test run by this project.
+
+These sources support a separate lane-retaining latch, rather than a copy of the last CPU destination register.
+Our implementation and synthetic programs are original. No external source code or test ROM was imported.
+No physical-hardware measurement or external emulator differential run was performed here.
+
+## Bounded implementation
+
+`memory/iwram_bus.rs` records lane values and a known-bit mask during consecutive Thumb instructions in IWRAM.
+Before execution, the mapped PC+4 halfword updates its addressed lanes.
+During execution, successful IWRAM bus reads and writes update the staged lanes at their actual aligned addresses and widths.
+The latch sees raw bus data before CPU load rotation and sign extension.
+Other-region accesses and host inspection do not change it.
+
+A completed sequential instruction commits the staged history for the next exact virtual PC.
+A failed instruction discards all staged changes and preserves the last committed history.
+The existing whole-instruction diagnostic policy still applies; this is not hardware data-abort behavior.
+All unused-memory reads within one instruction use its entry snapshot.
+
+The model starts with unknown lanes. An unused-memory load requires a complete known word, even for a narrower load.
+Ordinary instructions and mapped data accesses can establish history without requiring a prior complete word.
+Consecutive halfword fetches or an IWRAM word access can make every lane known.
+Missing lookahead and 16 MiB region-crossing fetches retain diagnostics.
+
+Successful branches and other refill instructions invalidate continuation history, even when the target equals the next sequential address.
+The existing Thumb timing classifier identifies these refills for both timed and untimed CPU stepping.
+Execution outside Thumb IWRAM also ends this bounded history sequence.
+An accepted machine IRQ and each successful DMA unit invalidate the history. Failed DMA units preserve it.
+The implementation does not guess refill or DMA latch contents.
+
+This is not a full IWRAM bus model across all CPU states. ARM access history, refill fetches, and DMA-to-CPU ordering remain incomplete.
+It is not a persistent instruction pipeline. Self-modifying instruction execution and exact per-access device timing remain unverified.
+
+## Original regression coverage
+
+- Both code alignments, IWRAM mirrors, and physical RAM wrap.
+- Captured halfwords that remain unchanged by host inspection or later host writes.
+- Byte/halfword/word data reads and writes, sign extension, load rotation, and all processor modes.
+- Other-region accesses that leave IWRAM lanes unchanged.
+- Multiple-register transfers, final-word retention, and writeback.
+- Unknown lanes, establishment of known history, staged-access rollback, and retry.
+- Taken and untaken branches, PC writes to fallthrough, discontinuities, IRQ entry, and DMA success/failure.
+- Equal timed/untimed CPU results and unchanged nominal data/device costs.
+
+## Validation result
+
+The sequential-history regressions reproduced the old unsupported-read failures before implementation.
+Workspace and core/demo tests pass on Darwin arm64 in debug and release builds.
+Formatting, lint checks, rustdoc, preparation tests, native ROM windows, and graphics smoke modes also pass.
+Public ARM, Thumb, memory, and BIOS reports match their previous passing results exactly.
+Debug and release reports also match for the same fixture paths.
+
+Those public suites remain regression checks, not independent IWRAM-history conformance tests.

docs/research/thumb-bios-prefetch.md

@@ -62,7 +62,7 @@ Original tests in `crates/gba-core/src/cpu/thumb_bios_access_tests.rs` cover:
 - Sequential history, ARM/Thumb transitions, SWI entry, and POP-to-PC exits with RAM stack data.
 - Raw reads inside BIOS and protected reads outside it.
 - The last complete fetch word, unavailable lookahead, and failure retention.
-- Separate host reads, retained IWRAM Thumb open-bus diagnostics, nominal costs, and device progression.
+- Separate host reads, retained cold-IWRAM Thumb open-bus diagnostics, nominal costs, and device progression.
 
 ## Validation result
 

docs/status.md

@@ -73,6 +73,7 @@ Update this file when a feature lands or a limit is removed.
 - ARM test/compare Rd=15 status restoration, without a PC result write or nominal refill.
 - ARM unused-memory data reads return a PC+8 word snapshot, with normal byte lanes and load rotation.
 - Thumb unused-memory reads use repeated PC+4 halfwords in 16-bit code regions and aligned PC+4 words in BIOS/OAM.
+- Sequential Thumb IWRAM history retains fetched and data-access lanes, with known-bit tracking and diagnostic rollback.
 - Little-endian byte, halfword, and word reads/writes.
 - ARM7TDMI word-load rotation, aligned stores, and odd-address halfword-load behavior.
 - Explicit errors for unsupported instructions when their condition passes, and for unsupported memory accesses.
@@ -131,8 +132,10 @@ Other public suites remain unverified. These results do not establish full CPU o
 The runner requires known completion addresses and has no debug-port protocol, scripted input, or rendered-image assertions.
 
 ARM data reads from unused address ranges use a bounded [PC+8 open-bus snapshot](hardware/cpu.md#arm-unused-memory-data-reads).
-Thumb reads use [region-dependent snapshots](hardware/cpu.md#thumb-unused-memory-data-reads) where the documented value needs no prior bus history.
-This is not a fetch pipeline. Thumb IWRAM, region-crossing fetches, DMA, and unused/write-only I/O open bus remain unsupported.
+Thumb reads use [region-dependent snapshots](hardware/cpu.md#thumb-unused-memory-data-reads) and bounded sequential IWRAM lane history.
+Cold or invalidated IWRAM history remains diagnostic until all lanes are known.
+Refill instructions, accepted machine IRQs, successful DMA, and execution outside Thumb IWRAM end the supported history sequence.
+This is not a fetch pipeline. Refill history, region-crossing fetches, DMA latches, and unused/write-only I/O open bus remain unsupported.
 BIOS protection uses separate retained BIOS fetch snapshots as described in [BIOS behavior](hardware/bios.md#cpu-bios-read-protection).
 Host inspection and instruction fetches remain strict. Other unmapped reads return errors.
 Reads beyond the supplied cartridge bytes also return errors.
@@ -142,8 +145,8 @@ Writes to cartridge addresses return errors instead of modeling cartridge hardwa
 
 ## Next steps
 
-1. Add validated prior-bus history for Thumb IWRAM open bus, including data-load overwrites and DMA transitions.
-   Keep unknown history diagnostic until those interactions have independent coverage.
+1. Extend IWRAM history across validated refill and DMA-to-CPU transitions.
+   Keep unknown history diagnostic until fetch ordering and latch ownership have independent coverage.
    Validate BIOS snapshots with independent hardware tests before claiming exact refill or data-access history.
    The desktop runner still uses only the original BIOS. Keep protected reads image-derived for all supplied images.
 2. Refine nominal timing with a fetch pipeline, Game Pak prefetch, per-access device updates, and verified timer/IRQ delays.

docs/testing.md

@@ -65,10 +65,15 @@ Compare/status CPU regressions verify saved flags/masks, bank switching, sequent
 Load-alias regressions cover widths, signed/unaligned values, immediate/register offsets, pre/post-indexing, every non-PC register bank, and address wrapping.
 They verify loaded-value precedence, preserved flags, unchanged stores, nominal timing, I/O reads before device progress, deferred IRQ delivery, and atomic errors.
 ARM open-bus regressions cover unused-range boundaries, PC+8 source regions, byte lanes, signed/unaligned loads, writeback, and block loads.
-They check branch-target resampling, missing lookahead, skipped conditions, nominal timing, device progress, and retained host/fetch/IWRAM-Thumb/DMA diagnostics.
+They check branch-target resampling, missing lookahead, skipped conditions, nominal timing, device progress, and retained host/fetch/cold-IWRAM/DMA diagnostics.
 Thumb open-bus tests cover supported code regions, both instruction alignments, ROM windows, mirrors, and physical memory wrap.
 They check widths, sign extension, rotation, block/stack/PC loads, aliases, modes, state preservation, and sequential/branch resampling.
-Short-ROM tests require only the fetched halfword in 16-bit regions. IWRAM and region-crossing tests retain explicit diagnostics.
+Short-ROM tests require only the fetched halfword in 16-bit regions. Cold IWRAM and region-crossing tests retain explicit diagnostics.
+Sequential IWRAM regressions check retained lanes across fetches, reads, writes, mirrors, and physical RAM wrap.
+They cover raw bus values before load rotation/sign extension, all modes, block transfers, and isolation from other memory regions.
+Known-bit tests reject incomplete words. Transaction tests verify discarded partial updates and preserved history after errors.
+Control-flow tests distinguish taken/untaken branches and invalidate PC writes even when the target equals fallthrough.
+DMA and IRQ tests check conservative invalidation; timed/untimed tests verify CPU results and nominal clock costs.
 Host/fetch isolation, separate BIOS history, unsupported stores/data regions, nominal device progression, and DMA diagnostics also have checks.
 The pinned public ARM ROM now reaches its completion checkpoint with r12 = 0 in debug and release builds.
 The pinned public Thumb ROM also reaches its ARM-state checkpoint with r7 = 0 in both builds.
@@ -228,7 +233,7 @@ They cover all processor modes, load widths, lanes, rotation, both Thumb code al
 They verify direct reads while executing inside BIOS, re-entry, SWI/IRQ returns, host-inspection isolation, and original-boot provenance.
 Thumb tests cover sequential snapshots, instruction-state transitions, SWI entry, and RAM-backed POP exits.
 Unknown history, last valid fetch words, missing lookahead, and diagnostic-step retention have explicit checks.
-Thumb IWRAM unused-memory reads remain diagnostics. Separate tests cover supported general Thumb snapshots and retained BIOS history.
+Unknown Thumb IWRAM history remains diagnostic. Separate tests cover known sequential history, general Thumb snapshots, and retained BIOS history.
 Protected loads keep normal nominal costs and advance devices only through machine stepping.
 Firmware readback regressions separately verify documented boot, SoftReset, returning SWI, IRQ callback, and IRQ return words.
 They execute ARM/Thumb loads across widths and lanes, check caller state, and trace actual exits to their image data.