Repository navigation
test(ppu): lock in the confirmed mid-scanline HDMA compositor bug - #36
Conversation
Adds a regression-baseline acceptance test for the off-by-one-line HDMA/compositor timing bug documented in docs/ppu.md's "Mid-scanline/ HDMA-driven register timing" section: RustySNES's end-of-line compositor reads register state at dot 340, AFTER that same line's own HDMA run at dot 276 has already fired, so an HDMA-driven per-line register write meant to take effect starting line V+1 instead lands on line V itself. crates/rustysnes-core/tests/mid_scanline_hdma_baseline.rs is a minimal, self-authored hand-assembled 65C816 reproduction (mirroring the pattern already used for rewind/run-ahead's synthetic per-frame tests): HDMA drives $2100 (INIDISP master brightness) with a single transition partway through the frame, alternating full-brightness (backdrop renders white) and force-off (backdrop renders black). No BG/OBJ layer is enabled -- every pixel falls through to the backdrop color (Ppu::layer_color's !p.opaque path), so this isolates the exact compositor-vs-HDMA dot-timing bug with zero tilemap/tileset setup. The test locks in the CURRENT confirmed-buggy transition position (last-white row 99, first-black row 100) -- derived from the bug's mechanism analysis and empirically confirmed on the first run, not guessed. It does not assert correct hardware behavior; a second test confirms the reproduction is deterministic across fresh runs. When the real fix lands, this specific assertion is expected to flip to (100, 101) as a deliberate, reviewed golden-vector update. No production code changed (rustysnes-ppu, rustysnes-core untouched outside this new test file). Full workspace test suite (cargo test --workspace) and the complete golden/oracle suite (--features test-roms) both verified green -- zero regressions. Updates docs/ppu.md's "What a future investigation/fix needs" section with a new "Regression-baseline groundwork (landed)" subsection, and to-dos/VERSION-PLAN.md's v0.5.0 bullet to note this closes most of the "no dedicated test ROM" gap -- the cross-crate scheduler/PPU timing- communication design remains the real outstanding work.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a regression-baseline test (mid_scanline_hdma_baseline.rs) and updates documentation across CHANGELOG.md, docs/ppu.md, and VERSION-PLAN.md to lock in the current, known off-by-one-line HDMA/compositor timing bug. The reviewer suggests strengthening the test assertions by ensuring the sanity check strictly verifies a single transition and by comparing the entire framebuffers for the determinism test.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
There was a problem hiding this comment.
Pull request overview
Adds a new regression-baseline test that intentionally captures RustySNES’s currently confirmed mid-scanline HDMA/compositor off-by-one-line timing bug, providing a stable acceptance vector that will deliberately flip once the real fix lands. This supports the emulator’s accuracy/determinism goals by locking in the known-buggy behavior in a minimal, self-contained reproduction while documenting the mechanism and next steps.
Changes:
- Add a new
rustysnes-coreintegration test that boots a tiny synthetic LoROM and asserts the known-buggy brightness-transition row boundary driven by HDMA to$2100. - Document the new baseline test and how it maps to the investigated mechanism in
docs/ppu.md, and reflect the groundwork in planning notes. - Update the changelog to record the addition of this regression-baseline test.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| to-dos/VERSION-PLAN.md | Notes that regression-baseline groundwork for the mid-scanline HDMA/compositor issue is now in place. |
| docs/ppu.md | Adds a “Regression-baseline groundwork” section describing the new test and the expected assertion flip when fixed. |
| crates/rustysnes-core/tests/mid_scanline_hdma_baseline.rs | New minimal synthetic-ROM-based test locking in the currently confirmed buggy transition position and a determinism sanity check. |
| CHANGELOG.md | Records the newly added regression-baseline test under Unreleased additions. |
- The "sanity" check only verified each row was either white or
black, not that there was exactly ONE transition -- an alternating
noisy pattern would have passed. Now asserts every row up to and
including last_white is white, every row after is black.
- The determinism test only compared the derived (last_white,
first_black) tuple; now compares the full framebuffer for a
stronger guarantee.
- Fixed a grammar gap in the CHANGELOG entry ("off-by-one the
mechanism..." -> "off-by-one-line shift the mechanism...").
Summary
crates/rustysnes-core/tests/mid_scanline_hdma_baseline.rs: a regression-baseline acceptance test for the off-by-one-line HDMA/compositor timing bug this session's v0.5.0 research confirmed (docs/ppu.md§Mid-scanline/HDMA-driven register timing)$2100(INIDISP brightness) with a single transition partway through the frame; no BG/OBJ setup needed (a disabled-layers screen renders pure backdrop color, isolating the exact compositor-vs-HDMA dot-timing bug)rustysnes-ppu/rustysnes-coreuntouched outside this new test filedocs/ppu.mdandto-dos/VERSION-PLAN.mdto reflect this groundwork; closes most of the "no dedicated test ROM" gap flagged as blocking a future fixWhen the real fix lands, this specific assertion is expected to flip to
(100, 101)as a deliberate, reviewed golden-vector update — that's the fix's acceptance test.Test plan
cargo fmt --all --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspace(base suite, zero regressions)cargo test --workspace --features test-roms(full golden/oracle suite, zero regressions)mid_scanline_hdma_transition_is_one_line_early_current_known_bugandmid_scanline_hdma_probe_is_deterministic_across_fresh_runspass🤖 Generated with Claude Code