0xrsydn/gameboy-rust
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(cartridge): add bounded terminal ROM loading

Browse source 
Load read-only raw ROM files with bounded size checks and original BIOS boot. Require a machine-step budget and report CPU state, STOP, and explicit diagnostics without opening a window. Keep file access in the desktop crate.

Cover argument parsing, Darwin paths, file boundaries, ARM/Thumb execution, DMA/IRQ budgets, HALT/STOP, and error reports. Document limits and usage. Verified on native Darwin arm64: debug/release workspace tests, core-only tests, Clippy, rustdoc, all ten window smoke tests, and a release raw-ROM run.
This commit is contained in:
0xrsydn 2026-10-05 18:57:16 +07:00
commit c256bf8ccd
13 changed files with 837 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

3
docs/hardware/bios.md
View file

@ -26,7 +26,8 @@ Minimal boot initializes:
It then enters `0x08000000` in ARM System mode with IRQ/FIQ masks clear.
It does not reproduce Nintendo's logo, cartridge-header checks, RAM clearing, boot delays, or full hardware initialization.
The executable still does not load game files.
The executable can load raw ROM files for [bounded terminal diagnostics](cartridge.md) using this boot sequence.
This does not establish game compatibility or complete BIOS behavior.
Supported software interrupt services:

64
docs/hardware/cartridge.md Normal file
View file

@ -0,0 +1,64 @@
# Cartridge files and terminal execution
The desktop executable can load raw ROM bytes and run a bounded diagnostic session.
This supports original test programs. It does not establish commercial-game compatibility.
```sh
direnv exec . cargo run --locked --release -- --rom path/to/original.gba --steps 100000
```
Both options are required. Their order does not matter.
`COUNT` must contain decimal digits and be between 1 and 100,000,000 inclusive.
Do not combine ROM mode with demo or help options. Bare file paths are not accepted.
Quote paths that contain spaces. File extensions do not affect loading.
## Loading and boot
`crates/desktop/src/cartridge.rs` owns file access, argument checks, execution limits, and reports.
The core remains independent of the filesystem and window library.
The loader opens a regular file read-only and accepts 4 bytes through 32 MiB inclusive.
It checks metadata before and after opening, then independently bounds the read to the limit plus one byte.
This bounds file content reads even if the file grows. It is not a filesystem race protection mechanism.
Directories and other non-regular files are rejected. Symlinks to regular files are accepted.
Paths retain their operating-system representation and appear quoted in diagnostics.
The host filesystem can reject filenames, including invalid UTF-8 on Darwin.
Bytes are not padded, patched, or written back.
The loader does not validate a cartridge header, logo, or checksum.
It does not decode archives or ELF executables. Supply a raw binary with an ARM instruction at offset zero.
Headerless original programs are accepted.
Reads past supplied cartridge bytes remain explicit memory errors, not open-bus values.
All three Game Pak ROM windows use the same supplied bytes and existing wait-state rules.
Cartridge writes, save devices, and cartridge peripherals remain unsupported.
The runner calls `bios::boot` with the loaded bytes.
The [original BIOS replacement](bios.md) executes its minimal boot before entering `0x08000000` in ARM System mode.
There is no command-line option for external BIOS files.
Unsupported services remain diagnostics. In particular, RegisterRamReset sound/serial flags, including `r0=0xff`, still fail.
## Execution limits and results
The budget counts successful machine steps, including BIOS boot instructions.
Each CPU instruction, IRQ entry, DMA unit, or HALT idle batch consumes one step.
The budget is not an instruction-only, cycle, frame, or wall-clock limit.
HALT continues advancing devices within the budget.
STOP returns immediately because terminal mode has no input source to wake the machine.
STOP on the final allowed step is reported as STOP, not as budget exhaustion.
A failed CPU or DMA step consumes no budget and retains the machine state from earlier successful steps.
The report includes:
- Quoted path, byte count, and requested step limit.
- Stop reason and successful-step counters by kind.
- Nominal emulated cycles, PC, CPSR, CPU mode, and ARM/Thumb state.
- HALT/STOP flags and all active registers r0–r15.
Exit status zero means the step limit was reached or STOP was entered.
It does not mean the program completed or passed a hardware test.
Invalid arguments, loading failures, output failures, and emulation diagnostics produce a nonzero exit status.
For emulation diagnostics, stdout contains the final machine state and stderr contains the core error.
ROM mode has no window, keyboard input, audio, saves, per-step trace, or real-time pacing.
It does not enable frame capture or validate rendered output.
Use the existing demos for window and input tests.
Only load files that you may lawfully use. Do not commit game ROMs or firmware.