docs: define general GBA usability milestones

This commit is contained in:
0xrsydn 2026-10-06 22:23:28 +07:00
commit f7c29429e3
3 changed files with 54 additions and 1 deletions

View file

@ -169,6 +169,12 @@ Writes to cartridge addresses return errors instead of modeling cartridge hardwa
## Next steps
Follow the [general GBA usability roadmap](usability-roadmap.md).
Prioritize repeatable homebrew gameplay, demonstrated compatibility failures, cartridge saves, and audio.
The goal is usable emulation across games, not an Emerald-specific implementation.
The remaining hardware-validation backlog includes:
1. Extend shared fetch samples to verified general-bus data-access history and unsupported fetch regions.
General DMA open-bus reads and sub-instruction arbitration remain separate from retained channel data and local IWRAM lanes.
Keep unknown history diagnostic until fetch ordering and latch ownership have independent coverage.
@ -183,7 +189,7 @@ Writes to cartridge addresses return errors instead of modeling cartridge hardwa
3. Validate keypad retrigger behavior with hardware tests and add remaining device registers; extend BIOS reset coverage as sound/serial support becomes available.
Validate STOP entry/wake edges and add external wake sources and remaining DMA device modes.
4. Replace nominal sprite work limits with verified individual fetch timing; add background fetch timing and per-pixel composition.
5. Validate more original/public test ROMs through the window; add audio, cartridge hardware, and saves before testing Emerald compatibility.
5. Validate more original/public test ROMs through the window. Expand compatibility evidence across independent programs.
Keep the emulator core independent of window and audio libraries.
Treat Nintendo DS support as a separate project phase.

46
docs/usability-roadmap.md Normal file
View file

@ -0,0 +1,46 @@
# General GBA usability roadmap
The goal is a general-purpose GBA emulator, not a port of one game.
Pokémon Emerald is one possible future compatibility target. It does not define hardware behavior.
Nintendo DS support remains a separate phase.
## Usability criteria
A usable release must demonstrate these results with several lawfully obtained games:
- Boot into a menu and enter gameplay without an unsupported-hardware diagnostic.
- Present stable graphics in the native Darwin window.
- Respond to button presses, held buttons, and releases.
- Preserve supported cartridge saves across process restarts without damaging existing files.
- Produce audio through an isolated host output layer.
- Exit cleanly and report unsupported behavior clearly.
A bounded run without a diagnostic is not proof of playability.
A test pass establishes only the configured assertions, not complete game compatibility.
## Work order
1. Establish repeatable gameplay checks using licensed public homebrew.
Add VBlank completion, button schedules, and captured-pixel assertions to the ROM suite runner.
2. Exercise menus and gameplay in the native window. Record the exact ROM revision and checksums.
3. Select another independent program. Fix demonstrated boot, graphics, or input failures with original regressions.
4. Implement cartridge save devices and safe host persistence. Verify saving and reloading across processes.
5. Implement audio devices and host output. Keep host dependencies outside `gba-core`.
6. Expand the compatibility matrix across games and hardware features.
Refine timing when independent tests or gameplay failures show a requirement.
SRAM, Flash, and EEPROM require different protocols. Supporting one does not establish support for the others.
Audio needs device clocks, mixing, and buffering; accepting sound-register writes alone is not audio support.
The detailed hardware limits remain in [status.md](status.md).
## Development loop
For each feature, inspect the source and hardware evidence, then write original regression tests.
Implement the smallest general behavior that satisfies the requirement.
Run focused tests, workspace validation, and relevant native-window checks through `direnv exec .`.
Update behavior notes and compatibility evidence. Save a semantic jj change with its own bookmark.
Then select the next demonstrated requirement without waiting for another confirmation.
Stop for missing access, a necessary product decision, or a destructive operation that needs approval.
Do not replace unsupported hardware with game-specific patches or silent register stubs.
Keep external ROMs, firmware, implementation source, and assets outside version control.