libretro/emulators/hatari.yml

emulator: Hatari
type: standalone + libretro
core_classification: official_port
source: "https://github.com/libretro/hatari"
upstream: "https://github.com/hatari/hatari"
logo: "https://raw.githubusercontent.com/hatari/hatari/main/share/icons/hicolor/scalable/apps/hatari.svg"
profiled_date: "2026-09-17"
source_commit: "5831f66e05ae19435bd9d8ef1c6f9c93998ff6f4"
upstream_commit: "51ed9991101fdc4623b3b38ec16e5a170cf2dffa"
core_version: "2.6.1-devel"
display_name: "Atari - ST/STE/TT/Falcon (Hatari)"
cores:
  - hatari
systems:
  - atari-st
  - atari-ste
  - atari-tt
  - atari-falcon

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-404), reports library_name hatari and the
  HATARI_VERSION string 2.6.1-devel (src/retro/main_retro.c:218-219,
  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 took that file's metadata on
  2026-09-16 and keeps a tos.img firmware entry with the TOS 1.02 US MD5,
  which this code never checks.

  retro_init builds <system>/tos.img, records whether it exists and passes
  it as --tos (src/retro/main_retro.c:157-207). 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:250-261). The
  name is fixed by that check: the .rom and .tos fallbacks of File_Read
  (src/tos.c:60-66, src/file.c:312-353, src/file.c:544-583) are never
  reached under a frontend. A missing --tos file fails option parsing
  (src/options.c:1026-1079, src/options.c:1937-1945), but Main_ErrorExit only
  raises the quit flag in this build (src/retro/main_retro.c:478-490), so
  Main_Init carries on with bUseTos cleared and TOS_InitImage installs the
  built-in test stub of faketosData.c instead of reading a ROM
  (src/tos.c:43, src/tos.c:1112-1131, src/tos.c:1151-1162). Without a
  system directory Main_Init runs with no --tos, 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:305-356, CMakeLists.txt:422-434)
  and have_bios is never set. 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 and the image is
  not EmuTOS (src/retro/options.c:250-263, src/retro/options.c:784,
  src/tos.c:1220-1222). 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
  <tos>.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 <CONFDIR>/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:260-282, src/main.c:319-322, src/configuration.c:862-867,
  src/configuration.c:1061-1071, CMakeLists.txt:444-461). The boot core
  options are applied right after the command line, so the machine, DSP,
  CPU, FPU, memory and hatari_patch_tos keys of hatari.cfg are overwritten
  by them (src/main.c:328-330, src/retro/options.c:724-789). Every other
  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,
  RS232 and SCC host endpoints (src/configuration.c:509-543), all disabled
  by default (src/configuration.c:736-761) and opened by Midi_Host_Open,
  Printer_TransferByteTo, RS232_OpenCOMPort and SCC_Init_Channel when
  enabled (src/midi.c:342-367, src/printer.c:42-65, src/printer.c:89-106,
  src/rs232.c:175-246, src/scc.c:439-500). 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:94-182), 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:369-427, src/retro/harddisk.c:32-129).
  With a .gem, <system>/hatari/BOOT.ST is inserted into drive A when it
  exists (src/retro/harddisk.c:105-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-827). Savestates pass through
  hatari_savestate.tmp in the system directory
  (src/retro/main_retro.c:41, src/retro/main_retro.c:292-359). IPF support
  is compiled in from rsn8887/capsimg when ENABLE_STATIC_CAPSIMAGE is on
  (cmake/BuildDependencies.cmake:93-126). The Windows jobs build with it
  since September 2026 (.gitlab-ci-libretro.yml:101,
  .gitlab-ci-libretro.yml:109) and the static Vita, Wii, Wii U and Switch
  jobs turn it off (.gitlab-ci-libretro.yml:193, .gitlab-ci-libretro.yml:202,
  .gitlab-ci-libretro.yml:210, .gitlab-ci-libretro.yml:218).
  File access goes through the libretro VFS when the frontend provides it
  (src/retro/vfs.c:17-48, src/file.c:253-302, src/file.c:479-492), and a
  device-prefixed path such as ux0:/ counts as absolute (src/file.c:152-164).

  The standalone program is the SDL build of the upstream tree. Its default
  TOS image is tos.img in the data directory (src/configuration.c:810-812),
  which is the directory of the executable on Windows, ../Resources in the
  macOS bundle and ../share/hatari beside the bin directory elsewhere
  (src/paths.c:316-330, CMakeLists.txt:383-394). --tos and the
  szTosImageFileName key replace it. When no image loads, Main_InitSubsystems
  opens the settings dialog to pick one and exits with Failed to load TOS
  image if none is chosen (src/main.c:191-201). Nothing is compiled in as a
  fallback. The install rule copies a src/tos.img into the data directory
  when one is present at build time, the source tree carries none, and the
  release checklist puts the latest EmuTOS 1024k image in the binary
  packages (doc/release-checklist.txt:85-86). The Hatari home directory is
  ~/.config/hatari, Library/Application Support/Hatari or
  AppData\Local\Hatari under the user's home (src/paths.c:24-29,
  src/paths.c:201-274). hatari.cfg is read from <CONFDIR> and then from that
  home directory, or from the file -c names (src/main.c:256-278,
  src/configuration.c:862-867, src/options.c:1283-1289). hatari.nvram and
  auto.sav, restored only when bAutoSave is on, are kept there
  (src/falcon/nvram.c:282-294, src/configuration.c:727-733). The window
  icon is hatari-icon.bmp in the data directory (src/sdl/screen.c:707-716).
  --lilo boots a Linux kernel instead of TOS, vmlinuz and initrd in the data
  directory by default (src/configuration.c:816-824, src/options.c:2309-2323).
  IPF, RAW and CTR images need the capsimage library found at build time
  (CMakeLists.txt:185-188).

files:
  - name: "tos.img"
    path: "tos.img"
    description: "Atari TOS ROM image"
    required: true
    min_size: 64
    max_size: 1048576
    validation: [size]
    aliases: [tos100fr.img, tos100us.img, tos102.img, tos102de.img, tos102fr.img, tos102uk.img, tos104.img, tos104de.img, tos104es.img, tos104fr.img, tos104uk.img, tos104us.img, tos106.img, tos106de.img, tos106es.img, tos106fr.img, tos106uk.img, tos106us.img, tos162de.img, tos162fr.img, tos162uk.img, tos162us.img, tos205de.img, tos205es.img, tos205fr.img, tos205it.img, tos205us.img, tos206.img, tos206de.img, tos206fr.img, tos206uk.img, tos206us.img, tos306de.img, tos306uk.img, tos400.img, tos402.img, tos404.img, st.img, ste.img, megaste.img, tt.img, falcon.img, emutos.img]
    source_ref: "source src/retro/main_retro.c:157-207, source src/retro/main_retro.c:250-261, source src/options.c:1937-1945, source src/configuration.c:489, source src/tos.c:60-66, source src/tos.c:976-1097, source src/tos.c:838-969, source src/file.c:312-353, upstream src/configuration.c:810-812, upstream src/paths.c:316-330, upstream CMakeLists.txt:383-394, upstream src/main.c:191-201, upstream src/reset.c:66-68, upstream src/file.c:275-308, upstream src/file.c:481-520, upstream src/CMakeLists.txt:74, upstream src/CMakeLists.txt:386-393"
    note: >
      Any TOS 1.00 to 4.04, TOS 0.00, a RAM TOS or EmuTOS. The file must
      carry this exact name in the libretro build: retro_init only enables
      emulation when <system>/tos.img exists. The standalone program opens
      tos.img in its data directory unless --tos or the szTosImageFileName
      key of hatari.cfg names another file. A missing name is retried with
      its extension replaced by .img, .rom and .tos, so tos.rom and tos.tos
      stand in for the default, and a .gz or archive is unpacked first. The
      program exits when no image loads and none is picked in the settings
      dialog (src/options.c:1937-1940, src/configuration.c:489,
      src/tos.c:983, src/main.c:191-201). The aliases are the names the platform launchers
      give it. Batocera passes tos<version><language>.img from the BIOS
      root, trying the chosen version then each machine's list and the
      languages us, uk, de, es, fr, it, nl, ru, se and none in turn
      (configgen generators/hatari/hatariGenerator.py:74-75, 158-193).
      Recalbox writes atarist/st.img, ste.img, megaste.img, tt.img or
      falcon.img by machine, then tos.img, then emutos.img, and emutos.img
      for any content whose path names emutos
      (configgen generators/hatari/hatariGenerator.py:151-167). RetroBat
      writes hatari/tos/ followed by the hatari_tos option, tos206.img,
      tos106.img, tos104.img, tos102.img or emutos.img, and tos.img at the
      BIOS root otherwise (emulatorlauncher Generators/Hatari.Generator.cs:144-154).

  - name: "tos.sym"
    path: "tos.sym"
    description: "Symbol table for the TOS image, nm-style text or a program symbol table"
    required: false
    storage: user_provided
    unsourceable: "one table per TOS build, valid only beside the image it was linked with: each EmuTOS release archive carries the table of its ROM, etos512k.sym beside etos512k.img, and Atari TOS has none"
    source_ref: "source src/tos.c:1094, source src/debug/symbols.c:1095-1113, source src/debug/symbols.c:1002-1020, source src/debug/symbols.c:372-407, source src/configuration.c:621, source src/includes/configuration.h:29-31, source src/retro/main_retro.c:182-194"
    note: >
      The name is the TOS image path with its last three characters
      replaced by sym, and the image path is always tos.img here: retro_init
      passes <system>/tos.img as --tos and no other image name reaches the
      loader, so a table named after another image, emutos.sym beside
      emutos.img, is never opened. nSymbolsAutoLoad gates the read. Its
      default is not off and no core option changes it, so the table is read
      at every TOS load when present. The standalone program derives the
      name the same way from the image it opens, tos.sym beside the default
      tos.img in its data directory. The symbols serve the built-in
      debugger.

  - name: "cartridge ROM"
    path: null
    config_key: "szCartridgeImageFileName"
    description: "Atari ST cartridge image loaded at 0xFA0000"
    required: false
    min_size: 40
    max_size: 131076
    validation: [size]
    source_ref: "source src/cart.c:41-47, source src/cart.c:53-88, source src/cart.c:97-104, source src/cart.c:114-142, source src/configuration.c:487-493, source src/configuration.c:814, upstream src/options.c:1951-1959"
    note: >
      Set through hatari.cfg, or with --cartridge in the standalone
      program. 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, program autostart or OS tracing
      is on.

  - name: "BOOT.ST"
    path: "hatari/BOOT.ST"
    description: "Boot floppy inserted with GEMDOS hard disk folders"
    required: false
    mode: libretro
    source_ref: "source src/retro/harddisk.c:78-129, source src/retro/main_retro.c:391-395"
    note: "Inserted into drive A when the content is a .gem file."

  - name: "hatari.cfg"
    path: null
    description: "Hatari configuration file"
    required: false
    storage: user_provided
    unsourceable: "user settings in Hatari's INI format, with no canonical contents"
    source_ref: "upstream src/main.c:260-282, source src/main.c:319-322, source src/main.c:328-330, source src/configuration.c:862-867, source src/configuration.c:1061-1071, upstream src/paths.c:236-250, source CMakeLists.txt:444-461, upstream src/options.c:1283-1289, upstream src/paths.c:24-29"
    note: >
      Read from <CONFDIR>/hatari.cfg and then from hatari.cfg in the
      RetroArch save directory, before the --tos argument and the boot
      core options are applied. The standalone program reads the second
      file from its home directory, ~/.config/hatari on Linux, or from the
      file -c names.

  - name: "hatari.nvram"
    path: null
    description: "TT and Falcon NVRAM contents, 50 bytes"
    required: false
    has_builtin: true
    min_size: 50
    validation: [size]
    storage: user_provided
    unsourceable: "machine state the emulator writes itself at exit, with no canonical contents"
    source_ref: "source src/falcon/nvram.c:96-97, source src/falcon/nvram.c:116-141, source src/falcon/nvram.c:148-171, source src/falcon/nvram.c:282-294, source src/falcon/nvram.c:334-337, upstream src/paths.c:236-250, source src/main.c:208, upstream src/paths.c:24-29"
    note: >
      Read from the RetroArch save directory at NvRam_Init, and from the
      Hatari home directory in the standalone program. A short read keeps
      the built-in defaults. Saved back on exit.

  - name: "keymap file"
    path: null
    mode: standalone
    config_key: "szMappingFileName"
    description: "Host key to ST scancode remapping table, text"
    required: false
    storage: user_provided
    unsourceable: "user settings in Hatari's keymap text format, with no canonical contents"
    source_ref: "upstream src/configuration.c:256, upstream src/configuration.c:719, upstream src/options.c:2236-2242, upstream src/main.c:178, upstream src/change.c:419-422, upstream src/sdl/keymap.c:47, upstream src/sdl/keymap.c:701-725"
    note: >
      Named by --keymap or the szMappingFileName key, empty by default.
      Read at start and again when the setting changes. A missing file logs a
      warning and keeps the default mapping.

  - name: "hatari-icon.bmp"
    path: null
    mode: standalone
    description: "Window icon"
    required: false
    bundled: true
    size: 630
    md5: f5e9c46fbbdc660d024a1bdd286a05ef
    sha1: 48be1de23a980bca15a8ed3cb92917340e43bbee
    sha256: 0e083a340ad2e522de94e5121565a4730f99d6ee3638c74f5a2c3be579529155
    crc32: 1639262c
    source_ref: "upstream src/sdl/screen.c:707-716, upstream src/CMakeLists.txt:386-389"
    note: >
      Loaded with SDL_LoadBMP from the data directory when the window is
      created. Without it the window keeps the default icon. Installed
      from src/hatari-icon.bmp, whose hashes these are.