gameboy-rust/docs/public-arm-tests.md

Pinned public ARM test

The headless runner now executes the unmodified ARM ROM from jsmolka/gba-tests. This is independent public test code, not a complete ARM7TDMI conformance suite or a new hardware measurement. The full public ARM test still fails. Compare/status and load/writeback alias errors are fixed; the next memory-access failure is recorded below.

Prepare and run

direnv exec . python3 tools/prepare_gba_tests.py /tmp/gba-public-arm
direnv exec . cargo run --locked --release -- --test-suite /tmp/gba-public-arm/suite.json > /tmp/gba-public-arm-report.json

The destination must not exist. Its parent directory must exist. Use a directory outside the repository or within the ignored roms/ directory. The adapter downloads pinned files over HTTPS and checks each byte count and SHA-256 digest before creating output. It retains the upstream MIT license, README, ARM sources, shared assembly includes, and the original ROM. It also writes suite.json and source-lock.json. The manifest references the ROM relative to its own directory. No source rewriting, header removal, binary patching, or expected-result adjustment occurs.

Python comes from the existing pinned Nix environment. No Python packages are required. The adapter bounds each download, sets a network timeout, and refuses existing output directories. A disk-write failure can leave partial output; choose a new destination for another attempt. Ordinary Rust and Python unit tests do not download or execute external ROMs.

For an offline copy of the selected upstream files:

direnv exec . python3 tools/prepare_gba_tests.py /tmp/gba-public-arm-offline --source-dir /path/to/gba-tests

Offline input must match every selected file in the lock. A directory from a different revision can fail verification. The adapter does not overwrite or modify the input tree.

Provenance and checkpoint

• Repository: jsmolka/gba-tests.
• Revision: a7113b67e63f83a9b321696ddd7042ccfad6c881.
• Upstream project license: MIT, copyright Julian Smolka. The license is retained with downloaded files.
• ROM: arm/arm.gba, 8,824 bytes.
• SHA-256: 77ee88662552bdc885c1080c0172ff119d54db791bd73b21808cf1ff1fe5b40e.
• All selected file hashes and sizes: tools/gba-tests-arm.lock.json.

This adapter uses the committed upstream binary, not a local rebuild. Upstream documents FASMARM as its assembler. No FASMARM build or source-to-binary reproduction was performed on Darwin. The binary's console header includes logo bytes. Do not copy the downloaded binary or header source into tracked files. Only original adapter code and provenance metadata are committed here.

The ARM source initializes r12 to zero before testing. Each failure path sets r12 to its test number and branches to eval. Successful execution falls through to the same label with r12 still zero. At this pinned revision, eval is 0x08001d4c, in ARM state. The ROM word there is the initial register save of the m_vsync macro. The source failure exits and their encoded branch targets were inspected against that address.

The manifest stops before executing eval and requires r12 == 0. This avoids depending on the result renderer, VBlank polling, or BIOS division used to print failure numbers. It does not bypass the ROM's startup code or any CPU tests. In particular, evaluation must stop before using a possibly invalid stack left by a failed mode-switch test. The instruction at the checkpoint is checked during preparation, in addition to whole-file hash verification.

The case budget is 1,000,000 successful machine steps, including our original BIOS boot. Timeouts, emulator diagnostics, and nonzero r12 all remain failures under the normal suite rules. Preparation does not mean the test passed. The current run exits nonzero and writes a failed JSON report.

Observed results on Darwin arm64

Before the compare/status fix:

• The ROM reaches eval after 579 successful steps.
• The assertion reports r12 = 234, in FIQ mode.
• Running beyond eval produces an unmapped stack access because the CPU incorrectly remains in FIQ mode.
• Upstream test 234 uses an ARM compare encoding with unused destination bits set to R15.

The CPU previously treated that encoding as an ordinary compare and only changed arithmetic flags. It now restores CPSR from the current mode's SPSR when one exists, without writing a result to PC. User/System forms still use ordinary test/compare flags because those modes have no SPSR. Original regressions cover all four test/compare operations, exception banks, flags, masks, operands, timing, conditions, and invalid saved modes. See CPU status behavior.

After the compare/status fix, before load/writeback alias support:

• Execution progresses past tests 234 and 235 and the PSR-transfer section.
• After 861 successful steps, the runner reports unsupported instruction 0xe5b00004 at 0x0800132c.
• This is LDR r0, [r0, #4]! in upstream test 360, with base and destination equal.
• The CPU is in System/ARM state, and r12 remains zero. The final completion checkpoint has not been reached.

After load/writeback alias support:

• Tests 360 and 361 complete without taking their failure paths.
• After 877 successful steps, the runner reports unmapped memory at 0x80000000.
• The current instruction is 0xe7b12060 at 0x08001384: LDR r2, [r1, r0, RRX]!, in test 362.
• With carry set and r0/r1 zero, the shifted offset correctly selects 0x80000000.
• The unsupported bus read prevents completion. r12 remains zero, but that alone is not a passing result.

Single-load aliases now retain the loaded value rather than the updated base. Original regressions also cover byte, halfword, and signed loads, every non-PC register bank, index modes, offsets, alignment, timing, and failures. The public halfword alias tests later in the ROM have not yet been reached; their source and mGBA's load ordering support the same rule. The next compatibility task is to verify high-address read behavior and implement the appropriate memory mapping or open-bus behavior. Do not bypass test 362, invent a return value, or weaken the result assertion. No public Thumb, timing, memory, BIOS, graphics, or unsafe suite has been claimed as passing. These results do not establish Pokémon Emerald compatibility.

References

• Pinned ARM entry and result flow.
• Pinned test/result macros.
• Tests 234 and 235.
• Load/writeback alias and shifted-offset tests.
• Halfword load/writeback alias expectations.
• Pinned license.