feat(memory): sample Thumb IWRAM refill targets

After successful refill instructions, sample the Thumb IWRAM target and target+2 halfwords to establish bus history. Share ARM/Thumb refill classification with nominal timing. Respect restored instruction state, completed data accesses, region limits, and diagnostic rollback; keep instruction execution and nominal costs unchanged.

Add original regressions for ARM/Thumb BX, Thumb branches and BL, PC writes, stack/block PC loads, status-restoring returns, real SWI/IRQ returns, both target alignments, mirrors/wrap, captured sample ordering, load lanes, failure retention, BIOS isolation, and DMA invalidation. Document official ARM7TDMI refill evidence and the distinction from a full pipeline.

Darwin arm64 validation: 917 workspace tests and 848 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 results and between profiles. Cold startup, ARM-target refill history, and DMA-to-CPU ordering remain incomplete; no hardware-conformance or commercial-game claim.

docs/architecture.md

@@ -31,7 +31,8 @@ The repository is a Cargo workspace with three crates:
 | `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/iwram_refill_tests.rs` | Thumb IWRAM target-pair refills, state changes, exception returns, boundaries, isolation, and nominal costs |
+| `crates/gba-core/src/memory/iwram_bus.rs` | Transactional known-lane history for Thumb IWRAM execution and target-pair refills |
 | `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

@@ -102,7 +102,7 @@ Limits remain explicit:
 - 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.
-- There is no persistent instruction pipeline. Sequential Thumb IWRAM history does not model refills or DMA-to-CPU bus transitions.
+- There is no persistent instruction pipeline. Thumb IWRAM refills sample their target pair, but DMA-to-CPU transitions remain unmodeled.
 
 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).
@@ -162,11 +162,33 @@ Success commits history only for the next sequential Thumb IWRAM PC. Failure pre
 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.
+Taken branches and PC-writing refills end the old continuation history, even when their target is the fallthrough address.
+A successful refill into Thumb IWRAM establishes new history from its target pair, as described below.
 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.
+Other execution states/regions, accepted machine IRQs, and successful DMA units invalidate continuation history.
+A later exception return into Thumb IWRAM can establish new history through its refill.
+Failed DMA units leave history unchanged. Discontinuous entry without an executed refill starts unknown.
+
+### Thumb IWRAM refill history
+
+After a successful refill instruction, the emulator uses the resulting PC and instruction state.
+If the destination is Thumb IWRAM, it samples two halfwords in order: target T, then T+2.
+Both accesses must remain in IWRAM. Normal physical RAM mirrors apply.
+These samples establish both word lanes for execution at T. The first instruction then samples T+4 as usual.
+
+This applies to ARM/Thumb BX, taken Thumb branches, BL suffixes, Thumb PC writes, and ARM status-restoring returns.
+Saved Thumb state, not the target's low bit alone, controls exception-return sampling.
+Stack and block-load returns finish their data accesses before the target samples.
+Failed instructions do not sample a target or replace committed history.
+
+Snapshots use strict mapped reads and add no nominal data or device cycles.
+They update bus history only; the interpreter does not cache these instructions for execution.
+Host inspection does not change captured lanes. A failed target fetch remains a later instruction diagnostic.
+Cold direct startup, unsupported target states/regions, and region-crossing lookahead still have no inferred refill history.
+DMA between refill and arrival still invalidates this history rather than supplying a guessed DMA value.
+
+The [refill evidence and scope](../research/iwram-bus-history.md#thumb-iwram-refill-extension) distinguish these samples from a full pipeline.
+ARM-target refill history, DMA ordering, self-modifying instruction execution, and exact refill timing remain incomplete.
 
 ## Processor status and exceptions
 
@@ -246,7 +268,8 @@ Important timing limits:
 - Code S/N counts follow instruction summaries, not a simulated fetch pipeline.
 - Ordinary code costs use the current instruction address. The ARM open-bus PC+8 snapshot has no fetch timing or startup pipeline fill.
 - PC writes use destination-region costs and the restored instruction width for nominal refill accesses.
-- Refill cost calculation does not read target bytes. An invalid branch target fails on the following instruction fetch.
+- Refill cost calculation does not read target bytes. Separate Thumb IWRAM target-pair samples update bus history without extra cycles.
+- Target-pair sampling cannot fail the branch early. An invalid branch target still fails on the following instruction fetch.
 - Game Pak prefetch is not implemented. WAITCNT bit 14 is stored but does not accelerate execution.
 - PHI and SRAM wait fields are stored; PHI output and SRAM mapping are not implemented.
 - External work RAM timing is fixed. The undocumented memory-control register is not implemented.

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 has bounded sequential lane history; refills and region transitions 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 and Thumb target-pair refill samples; 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).
@@ -112,6 +112,15 @@ IWRAM lane-history research:
 
 See [IWRAM Thumb bus history](research/iwram-bus-history.md). These were source reviews, not local hardware or external-emulator test runs.
 
+IWRAM refill research:
+
+- [ARM7TDMI branch cycle sequence](https://support.arm.com/documentation/ddi0029/g/instruction-cycle-timings/branch-and-branch-with-link), for destination and destination+instruction-width fetches.
+- [ARM7TDMI Thumb BL sequence](https://support.arm.com/documentation/ddi0210/c/Instruction-Cycle-Timings/Thumb-branch-with-link), for the prefix/suffix distinction.
+- [ARM7TDMI load-multiple sequence](https://support.arm.com/documentation/ddi0029/g/instruction-cycle-timings/load-multiple-registers), for data-transfer ordering before PC-load refills.
+- [NanoBoyAdvance refill helpers](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/arm/arm7tdmi.hh), reviewed for Thumb target/target+2 fetch order and the following execution fetch.
+
+These sources support bounded refill sampling, not a claim of cycle-accurate pipeline or DMA behavior.
+
 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

@@ -48,15 +48,43 @@ Ordinary instructions and mapped data accesses can establish history without req
 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.
+The initial sequential-only implementation invalidated history after all refill instructions.
+The extension below now establishes target-pair history for successful refills into Thumb IWRAM.
+The existing ARM/Thumb timing classifiers identify these refills for both timed and untimed CPU stepping.
+Execution outside Thumb IWRAM still ends a sequential history sequence.
+An accepted machine IRQ and each successful DMA unit invalidate history. Failed DMA units preserve it.
+The implementation does not guess 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.
+This is not a full IWRAM bus model across all CPU states. ARM-target history 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.
 
+## Thumb IWRAM refill extension
+
+The [ARM7TDMI branch sequence](https://support.arm.com/documentation/ddi0029/g/instruction-cycle-timings/branch-and-branch-with-link) fetches the destination, then destination plus instruction width.
+For Thumb destinations, those addresses are T and T+2.
+[NanoBoyAdvance's refill helpers](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/arm/arm7tdmi.hh) use that order.
+Its execution loop then fetches T+4 before executing the first Thumb instruction.
+
+After a successful refill instruction, we sample the two mapped destination halfwords if both remain in Thumb IWRAM.
+The samples replace the old lane history and establish the next expected PC as T.
+The next instruction's normal PC+4 sample updates one lane while the other retains the captured T+2 halfword.
+The samples occur after data accesses and status restoration, so loaded PC values and saved Thumb state select the destination.
+
+This covers actual ARM/Thumb BX, taken Thumb branches, BL suffixes, PC-writing Thumb operations, and ARM status-restoring returns.
+The Thumb BL prefix alone does not refill.
+Failed instructions retain the previous committed history. An unsupported or incomplete target sample does not fail the branch early.
+Unmapped instruction targets still fail on the following fetch.
+Cold direct startup and arbitrary PC changes do not manufacture a refill.
+
+These are bus-history samples, not instruction-buffer contents or extra emulated cycles.
+The interpreter still reads instructions when it executes them.
+Changing T+2 after the branch does not replace its captured bus value; changing T+4 before arrival affects the later sample.
+Those original tests verify sample ordering, not hardware-accurate self-modifying instruction execution.
+
+Successful DMA still invalidates history, including between refill and arrival.
+ARM-target refill history, exact pipeline timing, and DMA-to-CPU ordering remain outside this extension.
+No external emulator differential run or physical-hardware test was performed.
+
 ## Original regression coverage
 
 - Both code alignments, IWRAM mirrors, and physical RAM wrap.
@@ -66,11 +94,14 @@ It is not a persistent instruction pipeline. Self-modifying instruction executio
 - 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.
+- ARM/Thumb source regions, both target alignments, refill sample ordering, stack/block returns, and saved User/System banks.
+- Actual SWI/IRQ return handlers, failed refills, unmapped targets, separate BIOS history, and DMA between refill and arrival.
 - 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.
+The refill regressions also failed on the prior invalidation-only path, then passed with target-pair sampling.
 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.

docs/status.md

@@ -74,6 +74,7 @@ Update this file when a feature lands or a limit is removed.
 - 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.
+- Successful refills into Thumb IWRAM establish bus history from the target and target+2 halfwords, including exception returns.
 - 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.
@@ -134,8 +135,9 @@ The runner requires known completion addresses and has no debug-port protocol, s
 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) 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.
+Refills into Thumb IWRAM establish new target-pair history after the instruction succeeds.
+Accepted machine IRQs, successful DMA, unsupported refills, and other execution states/regions invalidate continuation history.
+This is not a fetch pipeline. ARM-target 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.
@@ -145,7 +147,7 @@ Writes to cartridge addresses return errors instead of modeling cartridge hardwa
 
 ## Next steps
 
-1. Extend IWRAM history across validated refill and DMA-to-CPU transitions.
+1. Research and validate DMA-to-CPU bus history, including latch ownership and IWRAM effects.
    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.

docs/testing.md

@@ -72,7 +72,10 @@ Short-ROM tests require only the fetched halfword in 16-bit regions. Cold IWRAM
 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.
+Control-flow tests distinguish taken/untaken branches and refill Thumb IWRAM targets even when the target equals fallthrough.
+Refill tests cover ARM/Thumb BX, Thumb branches and BL, high-register PC writes, stack/block PC loads, and saved-state returns.
+They check both target alignments, mirrors/wrap, captured target+2 versus later target+4, widths, sign extension, and rotation.
+Original SWI/IRQ handlers verify return-time history. Failed returns, cold entry, region boundaries, DMA invalidation, and BIOS isolation retain checks.
 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.
@@ -233,7 +236,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.
-Unknown Thumb IWRAM history remains diagnostic. Separate tests cover known sequential history, general Thumb snapshots, and retained BIOS history.
+Unknown Thumb IWRAM history remains diagnostic. Separate tests cover sequential/refill 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.