Skip to content

Wiki - RetroBIOS

Technical documentation for the RetroBIOS toolchain.

Pages are grouped by what you came to do. For users walks through installing and checking files. Technical reference describes how the toolchain behaves, one subject per page. For contributors is task-oriented: each page takes one job from start to finish.

For users

  • Getting started - installation, BIOS directory paths per platform, verification
  • FAQ - common questions, troubleshooting, hash explanations

If you just want to download BIOS packs, see the home page.

Technical reference

  • Architecture - directory structure, data flow, platform inheritance, pack grouping, security, edge cases, CI workflows
  • Tools - CLI reference for every script, pipeline usage, scrapers
  • Advanced usage - custom packs, target filtering, truth generation, emulator verification, offline workflow
  • Verification modes - how each platform verifies BIOS files, severity matrix, resolution chain
  • Data model - database.json structure, indexes, file resolution order, YAML formats
  • Troubleshooting - diagnosis by symptom: missing BIOS, hash mismatch, pack issues, verify errors

See also dump provenance for how the collection lines up against the No-Intro, Redump and TOSEC catalogs.

For contributors

  • Profiling guide - create an emulator profile from source code, YAML field reference
  • Adding a platform - scraper, registry, YAML config, exporter, target scraper, install detection
  • Adding a scraper - plugin architecture, BaseScraper, parsers, target scrapers
  • Testing guide - run tests, fixture pattern, how to add tests, CI integration
  • Release process - CI workflows, large files, manual release

See contributing for submission guidelines.

Community

Glossary

  • BIOS - firmware burned into console hardware, needed by emulators that rely on original boot code
  • firmware - system software loaded by a console at boot; used interchangeably with BIOS in this project
  • HLE - High-Level Emulation; software reimplementation of BIOS functions, avoids needing the original file
  • hash - fixed-length fingerprint of a file's contents; this project uses MD5, SHA1, SHA256, CRC32, and Adler-32
  • platform - a distribution that packages emulators (RetroArch, Batocera, Recalbox, EmuDeck, etc.)
  • core - an emulator packaged as a libretro plugin, loaded by RetroArch or compatible frontends
  • profile - a YAML file in emulators/ documenting one core's BIOS requirements, verified against source code
  • system - a game console or computer being emulated (e.g. sony-playstation, nintendo-gameboy-advance)
  • pack - a ZIP archive containing all BIOS files needed by a specific platform
  • ground truth - the emulator's source code, treated as the authoritative reference for BIOS requirements
  • cross-reference - comparison of emulator profiles against platform configs to find undeclared files
  • scraper - a script that fetches BIOS requirement data from an upstream source (System.dat, es_bios.xml, etc.)
  • exporter - a script that converts ground truth data back into a platform's native format
  • target - a hardware architecture that a platform runs on (e.g. switch, rpi4, x86_64, steamos)
  • variant - an alternative version of a BIOS file (different revision, region, or dump), stored in .variants/
  • required - a file the core needs to function; determined by source code behavior
  • optional - a file the core functions without, possibly with reduced accuracy or missing features
  • hle_fallback - flag on a file indicating the core has an HLE path; absence is downgraded to INFO severity
  • severity - the urgency of a verification result: OK (verified), INFO (negligible), WARNING (degraded), CRITICAL (broken)
  • status - the outcome of a single file check: ok, untested (present, hash not the expected one), or missing
  • discrepancy - a file that passes the platform check but fails the emulator's own size or hash validation
  • shared group - a file group in _shared.yml that several platforms include, carrying the destination a core expects
  • data directory - a whole directory tree a core needs (Dolphin Sys/, PPSSPP assets), cached in data/, not indexed in the database
  • storage tier - where a file comes from: embedded (in bios/), external (downloaded at build), user_provided
  • truth - platform-shaped data generated from emulator profiles, used to diff against what the platform declares
  • dump catalog - a preservation project (Redump, No-Intro, TOSEC) publishing DATs of verified hardware dumps
  • provenance - the catalogs that list a file, joined into the database by hash; an annotation, never an authority
  • manifest - the JSON file list per platform in install/, consumed by install.py