6e736c634b
Add --suite bios with hash-verified upstream files and the ARM evaluation checkpoint at 0x08000248. Preserve the r12=0 assertion, original BIOS boot, and all test bytes. Add synthetic adapter and CLI regressions. On Darwin arm64 the public ROM fails test 1 in debug and release after 64 steps and 543 nominal cycles. Document that this tests protected reads of Nintendo firmware opcodes, not general BIOS service compatibility. Online and offline preparation agree; 39 Python tests pass. Core behavior is unchanged.
63 lines
3.7 KiB
Markdown
63 lines
3.7 KiB
Markdown
# gameboy-rust
|
||
|
||
Game Boy family emulation in Rust, written from scratch.
|
||
The Game Boy Advance (GBA) is the first and currently only system.
|
||
|
||
**This cannot run Pokémon Emerald or other commercial games yet.**
|
||
It is an emulator foundation: an ARM7TDMI interpreter, memory bus, timers, DMA, Mode 0–5 video, and an original BIOS replacement.
|
||
The included demos run original ARM test programs through the emulated hardware.
|
||
Raw ROM files can run in terminal sessions or a window with keyboard input. Audio and saves are not implemented.
|
||
|
||
## Layout
|
||
|
||
| Crate | Purpose |
|
||
| --- | --- |
|
||
| `crates/gba-core` | Platform-independent GBA emulator. No external Rust dependencies. |
|
||
| `crates/gba-demos` | Original test programs that drive the core. |
|
||
| `crates/desktop` | Native window frontend on minifb. Builds the `gameboy-rust` executable. |
|
||
|
||
## Quick start
|
||
|
||
macOS on Apple Silicon is the verified platform. Install Nix (with flakes) and direnv, then:
|
||
|
||
```sh
|
||
direnv allow .
|
||
direnv exec . cargo run --locked --release -- --tile-demo
|
||
direnv exec . cargo test --locked
|
||
```
|
||
|
||
Arrows scroll, Q rotates, W zooms, Z flips, X changes priority, Enter resets, and Escape exits.
|
||
Run `direnv exec . cargo run --locked -- --help` to list all modes.
|
||
For original ROM files, use `--rom path/to/original.gba --window`, or `--steps 100000` instead of `--window` for terminal diagnostics.
|
||
See [cartridge loading](docs/hardware/cartridge.md) for limits and report meanings.
|
||
Use `--test-suite suite.json` for [repeatable headless ROM assertions](docs/rom-tests.md).
|
||
|
||
## Documentation
|
||
|
||
| Document | Contents |
|
||
| --- | --- |
|
||
| [docs/status.md](docs/status.md) | What works today, deliberate limits, and next steps |
|
||
| [docs/demos.md](docs/demos.md) | Every demo, its command, and its controls |
|
||
| [docs/development.md](docs/development.md) | Nix, direnv, and macOS build notes |
|
||
| [docs/testing.md](docs/testing.md) | Validation commands and what the test suites cover |
|
||
| [docs/rom-tests.md](docs/rom-tests.md) | Headless ROM suites, completion checks, assertions, and JSON reports |
|
||
| [docs/public-arm-tests.md](docs/public-arm-tests.md) | Pinned public ARM test, preparation command, results, and limits |
|
||
| [docs/public-thumb-tests.md](docs/public-thumb-tests.md) | Pinned public Thumb test, result protocol, and compatibility baseline |
|
||
| [docs/public-memory-tests.md](docs/public-memory-tests.md) | Pinned public memory test, results, and video-byte coverage limits |
|
||
| [docs/public-bios-tests.md](docs/public-bios-tests.md) | Pinned BIOS read-protection test and firmware-specific failure |
|
||
| [docs/architecture.md](docs/architecture.md) | Crate boundaries and a file-by-file map |
|
||
| [docs/hardware/cpu.md](docs/hardware/cpu.md) | ARM/Thumb execution rules, modes, exceptions, and timing |
|
||
| [docs/hardware/cartridge.md](docs/hardware/cartridge.md) | ROM loading, window/input controls, original ROM generator, and diagnostics |
|
||
| [docs/hardware/bios.md](docs/hardware/bios.md) | The original BIOS replacement and each supported service |
|
||
| [docs/hardware/timers-irq.md](docs/hardware/timers-irq.md) | Timers, interrupt registers, HALT/STOP, and power control |
|
||
| [docs/hardware/dma.md](docs/hardware/dma.md) | DMA channels, triggers, and timing |
|
||
| [docs/hardware/display-timing.md](docs/hardware/display-timing.md) | Display clock, status, IRQs, and scanline capture |
|
||
| [docs/hardware/video.md](docs/hardware/video.md) | Backgrounds, sprites, mosaic, windows, color effects, and input |
|
||
| [docs/references.md](docs/references.md) | External hardware references and emulator sources consulted |
|
||
|
||
Coding agents should start with [AGENTS.md](AGENTS.md).
|
||
|
||
## Legal
|
||
|
||
All demo content and the BIOS replacement are original. No Nintendo code or assets are included.
|
||
Only use game ROMs that you may lawfully use. Do not commit game ROMs, BIOS files, or game assets.
|