Hatari - RetroBIOS¶


Type	libretro
Classification	Official ports
Source	https://github.com/libretro/hatari
Upstream	https://github.com/hatari/hatari
Version	2.6.1-devel
Profiled	2026-09-03
Cores	hatari
Systems	atari-st, atari-ste, atari-tt, atari-falcon

Technical notes

The main branch of libretro/hatari is the upstream Hatari tree with its experimental libretro target in src/retro, which upstream added in January 2026, plus the port commits that follow the merge base recorded as upstream_commit: VFS, disk control, core options and hard disk loading. It builds as hatari_libretro (.gitlab-ci-libretro.yml:10-11, src/CMakeLists.txt:371-402), reports library_name hatari and the HATARI_VERSION string 2.6.1-devel (src/retro/main_retro.c:219-220, src/includes/version.h:8). The .info shipped in the tree declares no firmware (share/libretro/info/libretro-hatari.info); the hatari_libretro.info in libretro-core-info still describes the 1.8 port and its tos.img MD5, which this code never checks.

retro_init builds /tos.img, records whether it exists and passes it as --tos (src/retro/main_retro.c:157-204); when it is absent a frontend message is shown and retro_run only refreshes the framebuffer (src/retro/main_retro.c:186-189, src/retro/main_retro.c:251-262). The name is fixed by that check: the .rom and .tos fallbacks of File_Read (src/tos.c:61-67, src/file.c:298-339, src/file.c:530-569) are never reached under a frontend. Without a system directory Main_Init runs with no --tos and the TOS path falls back to tos.img in the Hatari data directory derived from the executable location (src/configuration.c:810-812, src/paths.c:299-331, CMakeLists.txt:418-430). TOS_LoadImage strips the 256-byte (34-byte for 4.92) loader of a RAM TOS, detects EmuTOS by ETOS at offset 0x2c, refuses images below 0x40 bytes, above 1 MB, with a version outside 0x100-0x6FF or a load address other than 0xE00000 or 0xFC0000, and coerces machine type and CPU to the TOS version unless the image is a 512 KB or larger EmuTOS (src/tos.c:976-1097, src/tos.c:838-969). ROM patches apply when the hatari_patch_tos option is on (src/retro/options.c:250-263, src/retro/options.c:783). No TOS is embedded. Because nSymbolsAutoLoad defaults to SYM_AUTOLOAD_DEBUGGER (src/configuration.c:621, src/includes/configuration.h:29-31), every TOS load also reads a .sym symbol table when one exists (src/tos.c:1094, src/debug/symbols.c:1095-1113, src/debug/symbols.c:1002-1020, src/debug/symbols.c:372-407).

The Hatari home directory is the RetroArch save directory (src/paths.c:236-250). Configuration is read from /hatari.cfg, /etc on Unix and the current directory on Windows, then from hatari.cfg in that home directory, before the --tos argument is applied (src/main.c:256-278, src/main.c:315-318, src/configuration.c:862-867, src/configuration.c:1061-1071, CMakeLists.txt:440-457). Every section is honoured: the cartridge image (src/configuration.c:487-493), floppy images, GEMDOS directories and ACSI, SCSI and IDE images (src/configuration.c:362-364, src/configuration.c:375-483), MIDI, printer and RS232 host endpoints (src/configuration.c:509-543), all disabled by default (src/configuration.c:736-761) and opened by Midi_Host_Open, Printer_TransferByteTo and RS232_OpenCOMPort when enabled (src/midi.c:342-367, src/printer.c:42-65, src/printer.c:89-106, src/rs232.c:175-230). szMappingFileName is parsed (src/configuration.c:256) but the port's Keymap_LoadRemapFile is empty (src/retro/keymap.c:222-224); only the SDL build reads a keymap file (src/sdl/keymap.c:701). The autosave snapshot is restored by M68000_Start (src/m68000.c:332-348), which the port never calls. TT and Falcon NVRAM is hatari.nvram in the home directory, read at NvRam_Init and written at exit (src/falcon/nvram.c:282-294, src/falcon/nvram.c:334-337).

Content is a floppy image, an .m3u list parsed relative to its own directory (src/retro/disk_control.c:96-184), an .ide image put on the IDE master, a .vhd image put on ACSI 0 or a .gem marker naming a GEMDOS directory (src/retro/main_retro.c:370-424, src/retro/harddisk.c:32-129). With a .gem, /hatari/BOOT.ST is inserted into drive A when it exists (src/retro/harddisk.c:104-127). A disk whose name ends in A pulls the sibling ending in B into drive B (src/floppy.c:300-343, src/floppy.c:385-388), and an STX image reads its .wd1772 overlay from the same directory (src/floppies/stx.c:807-825). Savestates pass through hatari_savestate.tmp in the system directory (src/retro/main_retro.c:41, src/retro/main_retro.c:293-357). IPF support is compiled in from rsn8887/capsimg when ENABLE_STATIC_CAPSIMAGE is on (cmake/BuildDependencies.cmake:93-126); the Windows and Vita CI jobs turn it off (.gitlab-ci-libretro.yml:97, .gitlab-ci-libretro.yml:105, .gitlab-ci-libretro.yml:189). File access goes through the libretro VFS when the frontend provides it (src/retro/vfs.c:17-49, src/file.c:239-286, src/file.c:465-478).

6 files | 1 required, 5 optional | 2 in repo, 4 missing

tos.img required in repo
Atari TOS ROM image

Size: max 1.0 MB
Validation: size
Source: src/retro/main_retro.c:157-204, src/retro/main_retro.c:251-262, src/options.c:1937-1945, src/tos.c:61-67, src/tos.c:976-1097, src/tos.c:838-969, src/file.c:298-339
Platforms: batocera, lakka, recalbox, retroarch, retrobat, retrodeck, retropie, romm
Any TOS 1.00 to 4.04, TOS 0.00, a RAM TOS or EmuTOS. The file must carry this exact name: retro_init only enables emulation when /tos.img exists.

tos.sym optional missing user_provided
Symbol table for the TOS image, nm-style text or a program symbol table

Source: src/tos.c:1094, src/debug/symbols.c:1095-1113, src/debug/symbols.c:1002-1020, src/debug/symbols.c:372-407, src/configuration.c:621, src/includes/configuration.h:29-31
Read next to tos.img at every TOS load when present; the symbols serve the built-in debugger.

cartridge ROM optional missing
Atari ST cartridge image loaded at 0xFA0000

Size: min 40 B, max 128.0 KB
Validation: size
Source: src/cart.c:39-46, src/cart.c:52-88, src/cart.c:97-105, src/cart.c:115-141, src/configuration.c:487-493, src/configuration.c:814
Config key: szCartridgeImageFileName
Set through hatari.cfg. Raw images up to 0x20000 bytes or .stc images of exactly 0x20004 bytes whose 4-byte header is skipped; extensions .img, .rom and .stc are tried when the configured path is missing. Replaced by the built-in GEMDOS trampoline whenever GEMDOS hard disk emulation, extended VDI or OS tracing is on.

BOOT.ST optional in repo
Boot floppy inserted with GEMDOS hard disk folders

Path: hatari/BOOT.ST
Source: src/retro/harddisk.c:78-129, src/retro/main_retro.c:393-396
Inserted into drive A when the content is a .gem file.

hatari.cfg optional missing user_provided
Hatari configuration file

Source: src/main.c:256-278, src/main.c:315-318, src/configuration.c:862-867, src/configuration.c:1061-1071, src/paths.c:236-250, CMakeLists.txt:440-457
Read from /hatari.cfg and then from hatari.cfg in the RetroArch save directory, before the --tos argument is applied.

hatari.nvram optional missing user_provided built-in fallback
TT and Falcon NVRAM contents, 50 bytes

Size: min 50 B
Validation: size
Source: src/falcon/nvram.c:96-97, src/falcon/nvram.c:116-141, src/falcon/nvram.c:148-171, src/falcon/nvram.c:282-294, src/falcon/nvram.c:334-337, src/paths.c:236-250, src/main.c:204
Read from the RetroArch save directory at NvRam_Init; a short read keeps the built-in defaults. Saved back on exit.

Generated on 2026-09-14T09:03:09Z