mirror of
https://github.com/libretro/virtualjaguar-libretro.git
synced 2026-11-07 04:36:00 -10:00
Joseph MattielloandClaude Sonnet 5.5
d4242dc295
The desktop app can now choose the exact boot ROM / CD BIOS file the core runs, boot a BIOS on its own and import a BIOS file. Root causes (maintainer report: BIOS import/scanning and booting the BIOS for CD is broken; Auto does not allow booting a local file): - biosUse() compared names and folders case-sensitively while classifyBios() does not, so JAGCD.BIN / ATARI - JAGUAR CD/ were labelled 'rename it' on volumes where the core finds them. - A BIOS dropped on the window was run as a cartridge; the only BIOS action was a copy under a fixed name, which a cart boot ROM ignores unless Cart BIOS Type = Custom and BIOS (Cartridges) = Real. - CD Boot Mode / BIOS options were reachable only through the generic Core options tab, which is empty before a load and hides the CD options while a cartridge runs (update_option_visibility); no-content boot could only enter the CD BIOS. Adds bios.h/.cpp and bios_ui.cpp (Settings > BIOS, the top of the BIOS & system tab, tile menu: Use / Boot / Copy), CoreHost support for the new private calls, config keys bios.cart / bios.cd, drop and dialog import into system/bios/, File > Boot BIOS, and --boot-bios / --cart-bios / --cd-bios / --expect-bios (headless BIOS-only boots). Tests: bios_unit, bios_e2e, smoke_boot_cd_bios, smoke_boot_cart_rom. Refs #838 Refs #833 Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
90 lines
5.3 KiB
Markdown
90 lines
5.3 KiB
Markdown
# BIOS and boot ROMs
|
|
|
|
**No BIOS files are required.** Both Jaguar console boot ROMs (Series K and Model M)
|
|
and both Jaguar CD BIOSes (retail and developer) are embedded in the core
|
|
(`src/bios/`). External images are an optional override for people who want a
|
|
specific revision.
|
|
|
|
Moved here from the top-level README. Behaviour below is from `libretro.c`
|
|
(`stage_cart_boot_rom`, `load_external_cart_boot_rom`, `load_external_cd_bios`,
|
|
`try_load_cd_bios_file`) and `libretro_core_options.h`; the core logs which image it
|
|
staged and where it came from at every boot, so check the frontend log first.
|
|
|
|
## Boot modes
|
|
|
|
- **Cartridges.** `BIOS (Cartridges)` (`virtualjaguar_bios`) chooses between the HLE
|
|
BIOS (default: the core does the boot setup itself and skips the boot animation) and
|
|
the real boot ROM. GPU-only / jagcrypt carts (the BootIntro demos) turn the real boot
|
|
ROM on even when this is set to HLE, because they contain no 68K program for the HLE
|
|
path to start.
|
|
- **CD discs.** `CD Boot Mode` (`virtualjaguar_cd_boot_mode`) chooses between the HLE CD
|
|
BIOS (default) and a real CD BIOS (`Real BIOS`; `Auto` currently behaves the same).
|
|
It overrides the cartridge setting for CD content. Audio-only (Red Book) discs always
|
|
use the real BIOS. If a real-BIOS mode is selected but no CD BIOS can be staged, the
|
|
core falls back to HLE.
|
|
|
|
## Cartridge boot ROM
|
|
|
|
`Cart BIOS Type` (`virtualjaguar_bios_type`, restart required) picks the console boot
|
|
ROM used on the real-BIOS cartridge path:
|
|
|
|
| Setting | Image |
|
|
| --- | --- |
|
|
| `Series K` (default) | The original Jaguar boot ROM. Embedded. |
|
|
| `Model M` | The later revision (patch address `$4804`) most size-coded BootIntros target. Embedded; an optional `jagboot_m.rom` in the root of the `system` directory replaces it. The core reads the first 128 KiB and uses the file if that read succeeds, so a file of 128 KiB or more is accepted (anything beyond 128 KiB is ignored) and a shorter file is skipped in favour of the embedded image. It is read as-is, with no checksum or identification step (`libretro.c`, `stage_cart_boot_rom`). |
|
|
| `Custom` | A 128 KB image loaded from the `system` directory. |
|
|
|
|
For `Custom`, the core searches these names in this order, and for each name tries
|
|
`system/`, then `system/Atari - Jaguar/`, then `system/jaguar/`:
|
|
|
|
`jagboot.rom`, `boot.rom`, `boot0.rom`, `[BIOS] Atari Jaguar (World).j64`,
|
|
`[BIOS] Atari Jaguar Stubulator '94 (World).j64`,
|
|
`[BIOS] Atari Jaguar Stubulator '93 (World).j64`
|
|
|
|
Filename is the outer loop, so a `jagboot.rom` in a subfolder wins over a `boot0.rom`
|
|
in the root. The file must be exactly 128 KB. Any content is accepted: the CRC32 is
|
|
only used to log the name of a recognized dump (Series K, Model M, Stubulator '93,
|
|
Stubulator '94); an unrecognized image loads with a warning. If `Custom` is selected
|
|
and nothing usable is found, the core logs a warning and uses the embedded Series K.
|
|
|
|
## CD BIOS override
|
|
|
|
Only in the real-BIOS CD path. A CD BIOS file in the `system` directory takes
|
|
precedence over the embedded images. The `CD BIOS Type` option chooses which
|
|
file is tried first (see below) and, when no usable file is found, which embedded
|
|
image is used. Accepted names:
|
|
|
|
| Type | Filenames |
|
|
| --- | --- |
|
|
| Retail | `[BIOS] Atari Jaguar CD (World).j64` / `.rom` / `.bin` |
|
|
| Developer | `[BIOS] Atari Jaguar Developer CD (World).j64` / `.rom` / `.bin` |
|
|
| Generic | `jaguarcd_bios.bin`, `jagcd_bios.bin`, `jaguarcd.bin`, `jagcd.bin`, `Jaguar CD BIOS.rom`, `Jaguar CD BIOS.bin` |
|
|
|
|
Search order: the selected `CD BIOS Type`'s names first, then the generic names, then
|
|
the other type's names. Within each of those three groups the core walks the
|
|
directories (`system/`, `Atari - Jaguar/`, `Atari - Jaguar CD/`, `jaguar/`,
|
|
`jaguarcd/`) and, inside each directory, the names. Unlike the cartridge search,
|
|
directory is the outer loop within a group, so a root-level file beats a subfolder
|
|
file of an earlier name in the same group. A lone file of the "wrong" type still beats
|
|
the embedded image.
|
|
|
|
The filename only decides what is tried first. The contents decide what is accepted:
|
|
|
|
| Outcome | Condition |
|
|
| --- | --- |
|
|
| Recognized | Exactly 256 KiB and CRC32 matches the retail or developer dump. Loaded and logged by its real revision, whatever the file is called. |
|
|
| Unrecognized | Exactly 256 KiB, unknown CRC32, but the big-endian run address at offset `$404` lies in `$800000-$840000`. Loaded with a warning naming the file as the prime suspect if boot black-screens. |
|
|
| Rejected | Wrong size, short read, or a run address outside that window. Skipped. |
|
|
|
|
If real-BIOS boots misbehave, remove or rename any BIOS files in `system/` to fall back
|
|
to the known-good embedded images.
|
|
|
|
## Standalone app: choosing a file
|
|
|
|
The desktop app (`app/`) can hand the core an exact BIOS file by path instead of relying on the names above:
|
|
Settings > BIOS, or a tile's menu in the library's BIOS & system tab (**Use as the Cart boot ROM / CD BIOS**), and
|
|
**Import BIOS file...** / dropping a BIOS on the window. It uses a private call that RetroArch never answers
|
|
(`docs/app-frontend-extension.md`); the core validates the file the same way (exactly 128 KiB boot ROM or 256 KiB
|
|
CD BIOS) and falls back to the search above if it refuses. **Boot the CD BIOS (no disc)** and **Boot this ROM
|
|
(empty slot)** start the console with nothing inserted. See `app/README.md`.
|