a9493d4cc6
Snapshot mapped PC+8 bytes for ARM data reads in the documented unused ranges. Preserve strict host/fetch/Thumb/DMA diagnostics, missing-ROM errors, existing write rules, and nominal timing. Add original regressions and document the bounded model. The unmodified pinned jsmolka ARM ROM now reaches its verified checkpoint with r12=0 in debug and release: 1344 steps and 11257 nominal cycles. No ROM, manifest, or assertion changes. Validated on Darwin arm64: 842 workspace tests in debug and release; 773 core/demo tests separately; Python adapter tests; native ROM windows; all ten demo window smoke tests; fmt, clippy, and rustdoc.
60 lines
3.4 KiB
Markdown
60 lines
3.4 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/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.
|