0xrsydn 08c8705904 test(cpu): integrate pinned public Thumb compatibility suite

Add --suite thumb while retaining default ARM preparation. Verify hashes, the Thumb-to-ARM evaluation bridge, and the result checkpoint; retain upstream provenance outside tracked files. Expand offline synthetic adapter and CLI regressions.

Darwin arm64 baseline: the unmodified Thumb ROM reaches ARM eval at 0x08000934 after 771 steps with r7=229 in debug and release. ARM remains passing. Online/offline preparation agrees and all 21 Python tests pass. CPU behavior is unchanged.

2026-10-05 20:40:37 +07:00

3.8 KiB

Raw Blame History

AGENTS.md

Orientation for coding agents. This is a map, not a rulebook: use your judgment, and read the linked doc for the area you are touching rather than everything.

What this is

gameboy-rust is a from-scratch Game Boy family emulator in Rust. The Game Boy Advance comes first; other systems (GB, GBC) may follow as separate cores. It cannot run commercial games yet. See docs/status.md for what works, what is deliberately missing, and what is next.

Crates

crates/gba-core: the emulator (CPU, memory bus, I/O, timers, DMA, video, BIOS replacement). Keep it free of external dependencies and of window, audio, clock, and file-system code, so it stays portable to WebAssembly.
crates/gba-demos: original ARM test programs and frame runners that drive the core.
crates/desktop: minifb frontend and the gameboy-rust binary. Host-specific code belongs here.

docs/architecture.md has a file-by-file map.

Commands

Run through direnv so the Nix toolchain and macOS build flags apply:

direnv exec . cargo test --locked                                  # everything
direnv exec . cargo test --locked -p gba-core -p gba-demos         # skip the window dependency
direnv exec . cargo clippy --locked --all-targets -- -D warnings
direnv exec . cargo fmt --all
direnv exec . cargo run --locked --release -- --tile-demo          # --help lists all modes

Window smoke tests (--*-smoke-test) need a logged-in desktop session. Details are in docs/testing.md.

Where to read

Working on	Read
ARM/Thumb instructions, modes, exceptions, timing	docs/hardware/cpu.md
Pinned public ARM/Thumb tests and compatibility results	docs/public-arm-tests.md, docs/public-thumb-tests.md
ROM test suites, assertions, and JSON reports	docs/rom-tests.md
ROM files, window execution, and terminal diagnostics	docs/hardware/cartridge.md
BIOS services (SWI)	docs/hardware/bios.md
Timers, IE/IF/IME, HALT/STOP	docs/hardware/timers-irq.md
DMA	docs/hardware/dma.md
VCOUNT/DISPSTAT, HBlank/VBlank, row capture	docs/hardware/display-timing.md
Backgrounds, sprites, mosaic, windows, blending, input	docs/hardware/video.md
Demos and key mapping	docs/demos.md
Build environment, minifb workarounds	docs/development.md

Where to write

Behavior notes for a subsystem go in its docs/hardware/*.md file. Add a new file there when a new subsystem arrives (audio, cartridge, saves).
Sources you consulted, including web searches, go in docs/references.md, or in a "References" section of the subsystem doc when the link explains one specific behavior.
Update docs/status.md when a feature lands or a limit goes away.
Keep README.md short: overview, quick start, and the docs index.
Avoid hard-coded test counts in prose; they go stale with every change.

Conventions

Version control is jj (colocated with git). History is a linear stack with one bookmark per change, named feature/<topic> or refactor/<topic>.
Commit messages follow Conventional Commits, for example feat(bios): implement SoftReset restart service.
New behavior comes with tests. Core integration tests live in crates/gba-core/tests/.
The core currently reports unsupported hardware behavior as explicit errors rather than guessing. Prefer that to silent approximations, and note the gap in the docs.
Everything in the repo is original. Do not add Nintendo BIOS code, game ROMs, or game assets.

3.8 KiB Raw Blame History