fix(timers): retain shared free-running prescaler phase

docs/architecture.md

@@ -48,7 +48,7 @@ The repository is a Cargo workspace with three crates:
 | `crates/gba-core/src/cpu/fetch_history_tests.rs` | Shared sample consumption, no execution-entry rereads, and failed-step retry |
 | `crates/gba-core/src/cpu/fetch_boundary_tests.rs` | Actual fetch-region snapshots, split refills, IWRAM lane requirements, ROM-window boundaries, and nominal timing |
 | `crates/gba-core/src/io.rs` | I/O registers, timers, HALT/STOP wake-up, next-event bounds, and IRQ latches |
-| `crates/gba-core/src/io/timer_step.rs` | Staged timer bank and timer IF bits at ordered CPU/DMA bus phases |
+| `crates/gba-core/src/io/timer_step.rs` | Staged timer bank, shared divider phase, and timer IF bits at ordered CPU/DMA bus phases |
 | `crates/gba-core/src/memory/timer_step_tests.rs` | Timer access phases, coherent lanes, cascades, IF ordering, rollback, DMA, idle, and clock ownership |
 | `crates/gba-core/src/display.rs` | Display clock, scanline status, comparison edges, and display IRQ events |
 | `crates/gba-core/src/dma.rs` | DMA registers, internal pointers, retained channel data, trigger state, priority, and completion IRQs |
@@ -132,6 +132,7 @@ The repository is a Cargo workspace with three crates:
 | `crates/gba-core/tests/timers.rs` | Timer rules, interrupt registers, and a cycle-by-cycle reference |
 | `crates/gba-core/tests/machine.rs` | Device IRQ entry/return, clock policy, and I/O failure atomicity |
 | `crates/gba-core/tests/timing.rs` | WAITCNT fields, bus costs, and timer/IRQ timing integration |
+| `crates/gba-core/tests/timer_prescaler.rs` | Exhaustive divider phases, staggered starts, control/cascade transitions, independent edge simulation, large batches, and idle ownership |
 | `crates/gba-core/tests/keypad.rs` | Keypad register widths, IRQ sampling, CPU/DMA ordering, HALT wake-up, diagnostics, and BIOS IntrWait |
 | `crates/gba-core/tests/graphics.rs` | Video memory, rendering, KEYINPUT, and CPU-driven graphics integration |
 | `crates/gba-core/tests/tiles.rs` | Mode 0 registers, maps, palettes, composition, diagnostics, and CPU tile/sprite demo |

docs/hardware/cpu.md

@@ -422,4 +422,4 @@ Important timing limits:
 - Game Pak prefetch is nominal. Full-buffer restart, page boundaries, cancellation, and live WAITCNT changes need independent hardware validation.
 - 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.
-- Exact DMA startup/resumption delays, display-bus contention, shared timer prescaler phase, and timer startup delays remain unmodeled.
+- Exact DMA startup/resumption delays, display-bus contention, and timer startup/register-write delays remain unmodeled.

docs/hardware/timers-irq.md

@@ -34,7 +34,8 @@ The transaction also owns timer IF bits. Reads see overflows through the current
 A later internal cycle can raise an acknowledged timer request again. Non-timer IF bits retain their existing behavior.
 IRQ delivery still waits until the next machine step. A committed timer request can wake HALT, but not STOP.
 
-Successful steps commit timers and timer IF bits. Failed steps discard staged counters, prescaler phases, reload/control writes, and requests.
+Successful steps commit timers, the shared divider phase, and timer IF bits.
+Failed steps discard staged counters, divider progress, reload/control writes, and requests.
 Display and other device clocks then advance once, without advancing timers again.
 Those devices still use the bulk scheduler. Mid-instruction display events, general bus arbitration, and IRQ synchronization delays remain unmodeled.
 Host clock advances and HALT idle batches retain ordinary bulk timer advancement; STOP idle does not advance timers.
@@ -81,8 +82,16 @@ Entering IRQ mode does not clear IF. Software must acknowledge the request.
 Unused register bits read as zero. Unknown I/O addresses and mirrors remain unmapped.
 Byte, halfword, and word accesses are supported for this register subset.
 
-Timer startup delays and shared prescaler phase are not modeled.
-The provisional timer model resets its private prescaler phase on enable or clock-source changes.
+Independent timers share a free-running divider with a synthetic zero phase at reset.
+The divider advances even when all timers are disabled. Enable, restart, and clock-source changes do not reset it.
+A timer receives selected divider edges after the start of an interval and through its end.
+Changing out of cascade mode uses the existing shared phase; cascade mode ignores the divider selection.
+HALT next-event bounds use that phase. STOP freezes it, and wake resumes without resetting it.
+CPU/DMA timer transactions stage divider progress and commit it only on success, without a second bulk tick.
+See [prescaler evidence and original tests](../research/timer-prescaler.md).
+
+Hardware startup and register-write delays are still not modeled. Writes retain the immediate bus-completion policy.
+The shared-phase tests validate this bounded model, not absolute enable/reload edges on hardware.
 Audio events and interrupt sources other than timers, display events, DMA completion, and keypad input are not implemented.
 
 `--timer-demo` executes original ARM code that configures Timer 0, IE, and IME.
@@ -207,7 +216,7 @@ A later running-state input sample follows the normal keypad IRQ policy.
 Host/debug writes to IE or KEYCNT can also satisfy the wake condition; stopped CPU code cannot execute such writes.
 
 After wake-up, ready DMA again takes priority, then IRQ delivery or CPU execution resumes.
-Timer prescaler phases, display position, RAM, and completed captured frames are retained, not reset.
+The shared timer divider phase, display position, RAM, and completed captured frames are retained, not reset.
 STOP does not automatically set forced blank or clear DISPCNT.
 Software can force blank before STOP if it wants the displayed image disabled.
 

docs/references.md

@@ -223,6 +223,14 @@ Ordered timer data accesses:
 
 See [staged timer clock ownership](research/ordered-timer-access.md). Relative probe agreement does not establish all absolute timer edges.
 
+Shared timer prescaler phase:
+
+- [Jgenesis timers at fab6e2cc](https://github.com/jsgroth/jgenesis/blob/fab6e2ccc60e492dd68b7f1e927b0829a6d80195/backend/gba-core/src/timers.rs), for absolute-clock divider edges and separate pending-write/enable state.
+- [NanoBoyAdvance timer logic at 55b5cf0a](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/hw/timer/timer.cc) and [channel definitions](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/hw/timer/timer.hh), for shared timestamp alignment and startup overflow corner cases.
+- Search leads: [VBA-M prescaler change](https://github.com/visualboyadvance-m/visualboyadvance-m/commit/92154dcd2ef7fca8c8afa8fced2f350ad2d2452a) and [mGBA timer suite](https://github.com/mgba-emu/suite/blob/04ada216ee13c56d786e54636ac980a71d791145/src/timers.c). Neither was used as a local hardware-test oracle.
+
+See [shared divider scope and tests](research/timer-prescaler.md). The correction does not implement delayed register writes or startup edges.
+
 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/ordered-timer-access.md

@@ -28,7 +28,8 @@ Those remain explicit validation limits.
 ## Staged clock ownership
 
 `Memory` owns an optional `TimerStep` during each machine instruction, IRQ entry, or DMA unit.
-The transaction copies only the four timers and timer IF bits, not RAM, display state, or the entire I/O object.
+The transaction copies the four timers, shared divider phase, and timer IF bits, not RAM or the entire I/O object.
+The later [shared-prescaler correction](timer-prescaler.md) replaced private timer remainders with this common divider.
 Its elapsed timestamp starts at zero and increases monotonically.
 It has no heap allocation or event log.
 
@@ -44,7 +45,7 @@ One word access has one sampling time for all four byte lanes.
 Reload bytes merge before control bytes at that same time.
 Block transfers have separate completion times for successive words.
 A start write cannot count earlier source cycles. A stop write includes clocks through its completion.
-Prescaler remainders, cascaded overflow pulses, and reload behavior use the existing timer implementation.
+Shared divider edges, cascaded overflow pulses, and reload behavior use the timer-bank implementation.
 
 Timer IF reads include requests raised through the access phase.
 Acknowledgement clears timer requests already present at that phase; later work can raise them again.
@@ -63,7 +64,7 @@ This extends the existing whole-unit scheduler; it does not establish physical D
 
 ### Errors and API isolation
 
-CPU diagnostics discard staged time, counter values, prescaler remainders, and pending timer requests.
+CPU diagnostics discard staged time, counter values, shared divider progress, and pending timer requests.
 This includes failures before instruction fetch and failures after earlier block-load accesses.
 Existing store validation still prevents partial writes when a block transfer has an invalid destination.
 Previously completed machine steps remain committed.

docs/research/timer-prescaler.md

@@ -0,0 +1,94 @@
+# Shared timer prescaler phase
+
+## Result and scope
+
+All four timers now derive independent-clock ticks from one free-running system-clock divider.
+Enabling, disabling, restarting, or changing a timer's clock source does not reset that divider.
+This replaces the previous per-timer phase, which restarted on enable or clock-source changes.
+
+The correction covers divider ownership and edge selection in the current immediate-write timer model.
+It does **not** add hardware startup delays, delayed register writes, or IRQ synchronization delays.
+Those behaviors need separate edge tests; adding a fixed startup delay alone would be incomplete.
+No physical-hardware measurement or external-emulator differential run was performed locally.
+
+## Evidence reviewed
+
+- [Jgenesis timers at fab6e2cc](https://github.com/jsgroth/jgenesis/blob/fab6e2ccc60e492dd68b7f1e927b0829a6d80195/backend/gba-core/src/timers.rs) derive ticks from absolute clock values shifted by the selected divisor.
+  Pending register writes and newly enabled reloads have separate handling.
+- [NanoBoyAdvance timers at 55b5cf0a](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/hw/timer/timer.cc) derive prescaler alignment from the scheduler timestamp.
+  Its [channel definitions](https://github.com/nba-emu/NanoBoyAdvance/blob/55b5cf0ae3d929582ac5bfd486558173502b8354/src/nba/src/hw/timer/timer.hh) separate pending writes from active timer control.
+  The implementation also handles a possible overflow from an old `0xffff` counter during enable/reload timing.
+
+Both implementations use a common clock origin rather than a private period restarted for each timer.
+Their startup handling also shows why divider phase and enable delay must be treated separately.
+The current correction uses the shared-clock rule without claiming their complete transition behavior.
+No implementation code was imported.
+
+Search also identified a [VBA-M prescaler change](https://github.com/visualboyadvance-m/visualboyadvance-m/commit/92154dcd2ef7fca8c8afa8fced2f350ad2d2452a)
+and the [mGBA timer suite](https://github.com/mgba-emu/suite/blob/04ada216ee13c56d786e54636ac980a71d791145/src/timers.c).
+These remain follow-up leads, not local test passes or implementation oracles.
+
+## Implemented divider
+
+Synthetic reset starts the shared phase at zero.
+Only the low ten system-clock bits are needed for divisors 1, 64, 256, and 1024.
+The phase advances with emulated time even when all timers are disabled or cascaded.
+It does not depend on host wall time or display-frame position.
+
+For an interval from clock `start` to clock `end`, an independently clocked timer receives:
+
+```text
+ticks = floor(end / divisor) - floor(start / divisor)
+```
+
+This counts divider edges after the starting timestamp and through the ending timestamp.
+An enable at an already completed edge does not replay that edge.
+A clock-source change selects another output of the same divider, not a new clock origin.
+Leaving cascade mode resumes from that existing divider position.
+Cascade mode still counts predecessor overflows and ignores the prescaler selection field.
+
+The core counts ticks and overflow pulses in bulk without iterating once per cycle.
+Wide arithmetic handles maximum `u32` clock batches before retaining the low divider bits.
+Overflow scheduling subtracts the current shared remainder, so HALT can stop at the next actual divider edge.
+
+For example, under the current immediate-enable policy, a /64 timer enabled at clock 63 ticks at clock 64.
+The old private-phase model incorrectly waited until clock 127.
+This example defines the implemented no-delay subset, not a claim about an enable write adjacent to a hardware startup edge.
+
+## Clock ownership and rollback
+
+The divider belongs to the timer bank, not an individual timer.
+Each machine `TimerStep` copies the shared phase with the counters and timer IF bits.
+CPU and DMA bus phases advance that copy. Success commits it; a failed step discards it.
+Other devices' bulk updates do not advance the committed divider again.
+
+Host clock advances and HALT idle periods advance the same divider.
+STOP freezes it, and keypad wake resumes the retained phase.
+Host register access and CPU-only stepping do not advance time or reset the divider.
+See [ordered timer accesses](ordered-timer-access.md) for transaction and API ownership.
+
+## Original regression coverage
+
+Tests exercise every low-ten-bit phase and all divider selections, including zero-cycle advances and completed-edge enables.
+Staggered timer starts verify shared edges. Clock-source changes, restarts, and cascade transitions preserve the common origin.
+A literal cycle-by-cycle reference checks randomized control, reload, acknowledgement, and clock sequences.
+It uses absolute edge tests, not the implementation's phase accumulator or bulk overflow division.
+Maximum-size batches check bounded progress and divider wrap.
+
+Machine tests cross a shared edge during CPU stores, timer loads, and DMA source/destination phases.
+Failed CPU and DMA steps must not consume that edge or retain its IRQ request.
+HALT after a machine timer start must use the committed phase for its next-event bound.
+STOP/keypad tests verify that stopped time does not move the divider.
+
+## Validation and remaining work
+
+Workspace/core/demo tests pass in debug and release on Darwin arm64.
+Formatting, clippy, rustdoc, Python tests, native ROM windows, and all graphics smoke modes pass.
+The release executable remains native Mach-O arm64.
+Public ARM, Thumb, memory, and BIOS reports remain byte-identical to the preceding ordered-timer change.
+The timer demo trace and both profiles of the cancellation probe are unchanged.
+The probe still matches all its published observations, but it uses divisor one and does not validate prescaler startup edges.
+
+Next, use independent timer-edge observations to define delayed reload/control writes and enable behavior.
+Include overflow from the previous counter, cascade transitions, same-cycle reads, and IRQ timing before adding startup delays.
+Full-buffer prefetch restart and page-boundary validation remain separate work.

docs/status.md

@@ -35,6 +35,7 @@ Update this file when a feature lands or a limit is removed.
 - CPU interrupt entry, interrupt masks, and FIQ priority.
 - GBA interrupt enable (`IE`), request flags (`IF`), and master enable (`IME`) registers.
 - Four 16-bit timers, with reloads, prescalers, count-up cascading, and timer-generated IRQs.
+- A shared free-running timer divider survives enable and clock-source changes; HALT advances it and STOP freezes it.
 - A 228-line display clock, VCOUNT/DISPSTAT, and VBlank/HBlank/VCount-match interrupts.
 - Four direct memory access (DMA) channels, with immediate, VBlank, and visible-line HBlank triggers.
 - Halfword/word DMA, address controls, repeat, channel priority, CPU pausing, and completion IRQs.
@@ -175,7 +176,8 @@ Writes to cartridge addresses return errors instead of modeling cartridge hardwa
    The desktop runner still uses only the original BIOS. Keep protected reads image-derived for all supplied images.
 2. Validate the active nominal Game Pak prefetch queue against independent timing tests.
    The [cancellation probe](research/prefetch-cancellation.md) now matches after [ordered timer accesses](research/ordered-timer-access.md).
-   Validate absolute timer startup/control edges and extend ordered observations to other devices without duplicate clocks or lost rollback.
+   The [shared timer prescaler](research/timer-prescaler.md) now retains a common clock origin across enable and clock-source changes.
+   Validate delayed timer startup/control edges and extend ordered observations to other devices without duplicate clocks or lost rollback.
    Validate full-buffer restart, page boundaries, live WAITCNT transitions, and cold-start costs.
    See [prefetch behavior and evidence](research/gamepak-prefetch.md); exact bus arbitration and timer/IRQ delays remain separate work.
 3. Validate keypad retrigger behavior with hardware tests and add remaining device registers; extend BIOS reset coverage as sound/serial support becomes available.

docs/testing.md

@@ -288,6 +288,10 @@ They verify timer IF reads/acknowledgements, preservation of other IF bits, defe
 Failures before fetch and after partial data work must discard staged time and requests. CPU-only APIs must not advance timer devices.
 Display-capture splits must not tick committed timers a second time. See [ordered timer accesses](research/ordered-timer-access.md).
 Bulk timer advancement is compared against an independent cycle-by-cycle reference for each prescaler and cascade configuration.
+Shared-divider tests cover every low-ten-bit phase, staggered enables, source changes, restarts, and cascade transitions.
+A separate literal edge simulation checks randomized control/reload/clock sequences without a per-timer phase accumulator.
+Maximum clock batches, HALT bounds, STOP/keypad retention, and CPU/DMA rollback across divider edges have original regressions.
+See [shared timer prescaler scope](research/timer-prescaler.md); delayed write and startup behavior remains unverified.
 Machine tests cover ARM/Thumb IRQ return, pending-request gating, acknowledgement, and the complete timer demo.
 Failed I/O block transfers are checked for partial register writes, hidden reload changes, and unintended IF acknowledgement.
 Status tests cover all modes, flag combinations, interrupt masks, field selection, privilege rules, and bank isolation.