feat: profile hatari on main and hatarib

emulators/hatari.yml

@@ -1,103 +1,166 @@
 emulator: Hatari
-type: standalone + libretro
-core_classification: frozen_snapshot
+type: 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-03-23"
-source_commit: "92e2874e664be40e1b51b97e0ff925a1aa917f22"
-core_version: "1.8"
+profiled_date: "2026-09-03"
+source_commit: "7fd34ccf34c6ea12b7f2b960b2f167d7f251892d"
+upstream_commit: "51ed9991101fdc4623b3b38ec16e5a170cf2dffa"
+core_version: "2.6.1-devel"
 display_name: "Atari - ST/STE/TT/Falcon (Hatari)"
 cores:
   - hatari
-  - hatarib
-systems: [atari-st, atari-ste, atari-tt, atari-falcon]
+systems:
+  - atari-st
+  - atari-ste
+  - atari-tt
+  - atari-falcon
 
-# Hatari requires a TOS ROM image to boot. The default filename is tos.img,
-# loaded from either system/ or system/hatari/tos/ (libretro core scans both).
-# EmuTOS (open source replacement) is detected via 'ETOS' magic at offset 0x2c.
-# Cartridge ROM is optional and loaded from szCartridgeImageFileName config.
+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.
 
-# TOS version/machine compatibility (enforced in tos.c TOS_CheckSysConfig):
-#   TOS 1.00-1.04  -> ST only, 68000
-#   TOS 1.06/1.62  -> STE only
-#   TOS 2.0x       -> ST/STE (patched for ST compatibility)
-#   TOS 3.0x       -> TT only, 68030+
-#   TOS 4.0x       -> Falcon only, 68020+
-#   EmuTOS         -> all machine types (no version constraint)
+  retro_init builds <system>/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:784). 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).
 
-# Libretro core search paths (libretro.c):
-#   1. <system>/tos.img (legacy default)
-#   2. <system>/hatari/tos/ directory (all .img/.rom/.tos files listed as options)
-# Core option "hatari_tosimage" selects which TOS image to use.
+  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: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, <system>/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).
 
 files:
-  # -- Primary TOS ROM (required) --
-  # At minimum one TOS image must be present. The most commonly used
-  # version is TOS 1.02, which is the default for Atari ST emulation.
-
   - name: "tos.img"
     path: "tos.img"
+    description: "Atari TOS ROM image"
     required: true
+    max_size: 1048576
+    validation: [size]
+    source_ref: "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"
     note: >
-      TOS ROM image. Any valid version (1.00 through 4.04) or EmuTOS works.
-      The core auto-detects version from the ROM header and adjusts machine type.
-      Default location is system/tos.img, additional images go in system/hatari/tos/.
-    source_ref: "src/tos.c:575-696, libretro/libretro.c:390-413"
+      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
+      <system>/tos.img exists.
 
-  # -- Cartridge ROM (optional) --
-  # External cartridge image, max 128 KB. Formats: .img, .rom, .stc
-  # Cannot be used together with GEMDOS HD emulation or extended VDI resolution.
+  - 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: "matches whichever image is installed as tos.img; EmuTOS releases ship one per ROM, Atari TOS has none"
+    source_ref: "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"
+    note: >
+      Read next to tos.img at every TOS load when present; the symbols
+      serve the built-in debugger.
 
   - name: "cartridge ROM"
-    path: null  # user-configured via szCartridgeImageFileName
+    path: null
+    config_key: "szCartridgeImageFileName"
+    description: "Atari ST cartridge image loaded at 0xFA0000"
     required: false
-    max_size: 131076  # 0x20004 (.stc with 4-byte header) or 0x20000 (raw)
+    min_size: 40
+    max_size: 131076
     validation: [size]
+    source_ref: "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"
     note: >
-      External cartridge image. Loaded to address 0xFA0000.
-      STC format images (0x20004 bytes) have a 4-byte header that is stripped.
-      Mutually exclusive with GEMDOS hard disk emulation and extended VDI.
-    source_ref: "src/cart.c:53-88"
+      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.
 
   - name: "BOOT.ST"
     path: "hatari/BOOT.ST"
+    description: "Boot floppy inserted with GEMDOS hard disk folders"
     required: false
+    source_ref: "src/retro/harddisk.c:78-129, src/retro/main_retro.c:393-396"
+    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; no canonical contents"
+    source_ref: "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"
     note: >
-      Floppy image used for GEMDOS HD bootstrapping with .gem files.
-      Libretro port addition (not in upstream Hatari).
-    source_ref: "libretro/libretro.c:1669"
+      Read from <CONFDIR>/hatari.cfg and then from hatari.cfg in the
+      RetroArch save directory, before the --tos argument is applied.
 
-# Supported TOS versions (from patch table in tos.c):
-#   0x100 - TOS 1.00 (ST, 68000 only, no VDI extensions)
-#   0x102 - TOS 1.02 (ST, most common for gaming)
-#   0x104 - TOS 1.04 (ST, adds autostart support)
-#   0x106 - TOS 1.06 (STE only)
-#   0x162 - TOS 1.62 (STE only)
-#   0x205 - TOS 2.05 (STE native, patched for ST)
-#   0x206 - TOS 2.06 (STE/ST)
-#   0x306 - TOS 3.06 (TT, 68030+)
-#   0x400 - TOS 4.00 (Falcon, 68020+)
-#   0x401 - TOS 4.01 (Falcon)
-#   0x402 - TOS 4.02 (Falcon)
-#   0x404 - TOS 4.04 (Falcon)
-#   0x492 - TOS 4.92 (RAM TOS variant)
-
-# TOS ROM sizes (typical):
-#   192 KB (0x30000) - TOS 1.0x (loaded at 0xFC0000)
-#   256 KB (0x40000) - TOS 2.0x+ (loaded at 0xE00000)
-#   Up to 1 MB       - maximum accepted by the loader
-
-# File extensions scanned: .img, .rom, .tos
-
-notes:
-  emutos_note: >
-    EmuTOS is a free open-source TOS replacement that works with all machine types.
-    Hatari detects it via the 'ETOS' signature at ROM offset 0x2c and skips
-    machine-type enforcement and ROM patches.
-  gemdos_boot_note: >
-    When using GEMDOS hard disk mode with .gem files, the core also loads
-    system/hatari/BOOT.ST as a floppy image for bootstrapping.
-  libretro_path_note: >
-    The libretro core checks system/tos.img first for backward compatibility,
-    then scans system/hatari/tos/ for additional TOS images exposed as core options.
+  - 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; no canonical contents"
+    source_ref: "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"
+    note: >
+      Read from the RetroArch save directory at NvRam_Init; a short read
+      keeps the built-in defaults. Saved back on exit.

emulators/hatarib.yml

@@ -0,0 +1,208 @@
+emulator: hatariB
+type: libretro
+core_classification: community_fork
+source: "https://github.com/bbbradsmith/hatariB"
+upstream: "https://github.com/hatari/hatari"
+profiled_date: "2026-09-03"
+source_commit: "e9bbbd5fb35076402dc6b3c8ee3259e1809001cf"
+upstream_commit: "6a8e26d69fb32d61efd398dc1ad9a77122400034"
+core_version: "0.5"
+display_name: "Atari - ST/STE/TT/Falcon (hatariB)"
+cores:
+  - hatarib
+systems:
+  - atari-st
+  - atari-ste
+  - atari-tt
+  - atari-falcon
+
+notes: |
+  hatariB carries Hatari 2.6.1 in its hatari/ directory, every change
+  fenced by __LIBRETRO__ (DEVELOP.md:7-14, DEVELOP.md:44-48), and
+  builds as hatarib (makefile.libretro:1-3, core/core.c:1134); the
+  upstream_commit is the v2.6.1 tag the tree was taken from. The core
+  reads and writes through core_file.c, using the libretro VFS when the
+  frontend offers version 3 (core/core_file.c:747-790). Hatari's own
+  directory strings are replaced by <nopath> (hatari/src/paths.c:339-350),
+  hatari.cfg is never read because Main_LoadInitialConfig calls
+  core_config_init instead (hatari/src/main.c:984-1012,
+  core/core_config.c:1421-1426), and printer, RS232 and keymap file
+  settings keep their disabled defaults with no option to change them
+  (hatari/src/configuration.c:728, hatari/src/keymap.c:63,
+  hatari/src/keymap.c:699-718).
+
+  At retro_set_environment the core looks for <system>/tos.img and lists
+  every entry of <system>/hatarib/, up to 128 files and 16 directories
+  (core/core_file.c:13-14, core/core_file.c:791-851). Those lists fill the
+  hatarib_tos, hatarib_cartridge and hatarib_hardimg options, 100 values
+  each: TOS candidates end in .img, .rom, .bin or .tos, cartridges in .img,
+  .rom, .bin or .cart, hard disks are any file or subdirectory
+  (core/core_config.c:11, core/core_config.c:1299-1366). The TOS option
+  defaults to <tos.img> when the file exists and to EmuTOS 192uk otherwise
+  (core/core_config.c:68-92, core/core_config.c:1306-1321); the four
+  special values select tos.img or one of the built-in images, any other
+  value is a path under the system directory
+  (core/core_config.c:1094-1117). TOS_LoadImage copies the built-in image
+  or reads the file with core_read_file_system and caches it
+  (hatari/src/tos.c:45-63, hatari/src/tos.c:1028-1078); a failed load
+  raises a notification and halts the CPU instead of leaving
+  (hatari/src/tos.c:1080-1086, hatari/src/tos.c:1250-1262,
+  core/core.c:419-433, hatari/src/main.c:903-922). Validation is
+  upstream's (hatari/src/tos.c:1114-1160), but TOS_CheckSysConfig only
+  warns and never switches machine or CPU (hatari/src/tos.c:859-1000). The
+  hatarib_emutos_region and hatarib_emutos_framerate options rewrite the
+  OS header word of an EmuTOS image (hatari/src/tos.c:1351-1365,
+  core/core_config.c:1163-1169). Symbols_LoadTOS still runs
+  (hatari/src/tos.c:1193) but resolves <tos>.sym against the process
+  working directory, so nothing is read from the system directory.
+
+  The three EmuTOS images are EmuTOS 1.4 built from the hatarib-custom-140
+  branch of bbbradsmith/emutos, which lets DESKTOP.INF and NEWDESK.INF be
+  loaded, and are compiled in through emutos/bin_to_h.py
+  (DEVELOP.md:10, README.md:305-307).
+
+  A cartridge is read with core_read_file_system from the option value
+  (hatari/src/cart.c:40, hatari/src/cart.c:57-100) and disabled with
+  GEMDOS hard disk emulation, extended VDI or OS tracing
+  (hatari/src/cart.c:108-147). A permanent hard disk comes from
+  system/hatarib through hatarib_hardimg and hatarib_hardtype, GEMDOS
+  folder, ACSI, SCSI or IDE (core/core_config.c:186-233,
+  core/core_config.c:1000-1057, core/core_config.c:1151-1162); temporary
+  ones are content with an .acsi, .ahd, .vhd, .scsi, .shd, .ide or .gem
+  extension or lines of an M3U (core/core_disk.c:16-23,
+  core/core_disk.c:676-713, core/core_disk.c:782-785,
+  core/core_config.c:1059-1087). Images open through core_file_open_hard
+  (hatari/src/hdc.c:903, hatari/src/hdc.c:961-963,
+  hatari/src/ide.c:663-666) and GEMDOS folders through core_scandir_hard
+  (hatari/src/gemdos.c:663, hatari/src/gemdos.c:761,
+  hatari/src/gemdos.c:1321); hard disks are write protected by default
+  (hatari/src/configuration.c:918). Floppy content is ST, MSA, DIM, STX,
+  IPF or CTR, also inside a ZIP, ZST or GZ, or an M3U or M3U8 list with
+  #BOOTA, #BOOTB, #AUTO and #RES directives (core/core_disk.c:14-24,
+  core/core_disk.c:202-384, core/core_disk.c:444-559,
+  core/core_disk.c:621-670). Before the original image the core takes a
+  same-named copy from the save directory and, for STX, a .wd1772 overlay
+  there (core/core_disk.c:787-814); modified disks are written back to
+  the save directory (core/core_disk.c:1154-1226, hatari/src/st.c:93,
+  hatari/src/msa.c:417, hatari/src/floppy_stx.c:451). #AUTO and #RES
+  write a virtual INF file to system/hatarib.tmp
+  (hatari/src/inffile.c:761) and, when booting from a GEMDOS C: folder,
+  read the DESKTOP.INF, NEWDESK.INF or EMUDESK.INF found there
+  (hatari/src/inffile.c:598-667). MIDI goes through the libretro MIDI
+  interface (core/core.c:485-545, hatari/src/midi.c:593-700); Midi_Host_Open
+  no longer opens files (hatari/src/midi.c:346-424).
+
+files:
+  - name: "tos.img"
+    path: "tos.img"
+    description: "Atari TOS ROM image, default when present"
+    required: false
+    has_builtin: true
+    max_size: 1048576
+    validation: [size]
+    source_ref: "core/core_file.c:791-851, core/core_config.c:68-92, core/core_config.c:1094-1117, core/core_config.c:1306-1321, hatari/src/tos.c:1028-1160"
+    note: >
+      Any TOS 1.00 to 4.04, TOS 0.00, a RAM TOS or EmuTOS. Further images
+      go in system/hatarib/ with an .img, .rom, .bin or .tos extension and
+      are selected with the hatarib_tos option; without tos.img the
+      built-in EmuTOS 192uk is the default.
+
+  - name: "etos1024k.img"
+    description: "EmuTOS 1.4 1024 KB image, all machine types"
+    required: false
+    embedded: true
+    size: 1048576
+    md5: 1cb3775c4775bad75d24447a90a2890b
+    sha1: 38dc8baf5224229df55e7d0804b6b7b6bacfc7a0
+    sha256: 757c571b98b955887ea6d9034513555f4263040420e9d2195cd0c6f8de06c451
+    crc32: 118b35b4
+    source_ref: "emutos/bin_to_h.py:1-30, hatari/src/tos.c:45-63, hatari/src/tos.c:1038-1046, core/core_config.c:76, core/core_config.c:1096-1116"
+    note: >
+      Compiled into the core from emutos/etos1024k.img and never opened at
+      run time. Built from the hatarib-custom-140 branch of
+      bbbradsmith/emutos; hashes are of the file in the repository.
+
+  - name: "etos192uk.img"
+    description: "EmuTOS 1.4 192 KB UK image, 50 Hz, default TOS"
+    required: false
+    embedded: true
+    size: 196608
+    md5: 5f5730d9b557c44ddb9bc410ce2925d8
+    sha1: ef3a3ccffcb317bff7d0dceca0abacefc3a58abc
+    sha256: 5c679e6b1b8ed178fa079e4957ed66f9277094f0fe0a5b50c8cbea041e220250
+    crc32: fe4c3ff1
+    source_ref: "emutos/bin_to_h.py:1-30, hatari/src/tos.c:45-63, hatari/src/tos.c:1038-1046, core/core_config.c:77, core/core_config.c:91, core/core_config.c:1096-1116"
+    note: >
+      Compiled into the core from emutos/etos192uk.img and never opened at
+      run time. Selected when no tos.img exists and no other image is
+      chosen. Built from the hatarib-custom-140 branch of
+      bbbradsmith/emutos; hashes are of the file in the repository.
+
+  - name: "etos192us.img"
+    description: "EmuTOS 1.4 192 KB US image, 60 Hz"
+    required: false
+    embedded: true
+    size: 196608
+    md5: 796f62574413bc59ca767063b3184f90
+    sha1: bb98cd8a50df53afecfe183b049eda4014fc0d05
+    sha256: ccccc420908012e03b4b38b8ed4530923bb04f27ab189eb2c694bf7e8509b666
+    crc32: 18030f9a
+    source_ref: "emutos/bin_to_h.py:1-30, hatari/src/tos.c:45-63, hatari/src/tos.c:1038-1046, core/core_config.c:78, core/core_config.c:1096-1116"
+    note: >
+      Compiled into the core from emutos/etos192us.img and never opened at
+      run time. Built from the hatarib-custom-140 branch of
+      bbbradsmith/emutos; hashes are of the file in the repository.
+
+  - name: "cartridge ROM"
+    path: null
+    config_key: "hatarib_cartridge"
+    description: "Atari ST cartridge image loaded at 0xFA0000"
+    required: false
+    min_size: 40
+    max_size: 131076
+    validation: [size]
+    source_ref: "core/core_config.c:166-185, core/core_config.c:1145-1149, core/core_config.c:1332-1344, core/core_file.c:256-259, hatari/src/cart.c:40, hatari/src/cart.c:57-100, hatari/src/cart.c:108-147"
+    note: >
+      Any file of system/hatarib/ with an .img, .rom, .bin or .cart
+      extension. Raw images up to 0x20000 bytes or .stc images of exactly
+      0x20004 bytes whose 4-byte header is skipped. Replaced by the
+      built-in GEMDOS trampoline whenever GEMDOS hard disk emulation,
+      extended VDI or OS tracing is on.
+
+  - name: "hatarib.nvram"
+    path: "hatarib.nvram"
+    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 when the content closes; no canonical contents"
+    source_ref: "hatari/src/falcon/nvram.c:97, hatari/src/falcon/nvram.c:111-117, hatari/src/falcon/nvram.c:127-170, hatari/src/falcon/nvram.c:178-205, hatari/src/falcon/nvram.c:317-330, hatari/src/falcon/nvram.c:371-374, hatari/src/falcon/nvram.h:54-58, core/core_file.c:273-277, core/core_file.c:319-322"
+    note: >
+      Read from the system directory at NvRam_Init for the TT and Falcon
+      machines only; a read shorter than 50 bytes keeps the built-in
+      defaults. Written back when the core shuts down.
+
+  - name: "capsimg.so"
+    path: null
+    description: "CAPSImage 5.1 shared library for IPF and CTR floppy images, Linux, macOS, Android and Raspberry Pi builds"
+    required: false
+    source_ref: "hatari/src/floppy_ipf.c:320-331, hatari/src/floppy_ipf.c:632-640, hatari/src/floppy_ipf.c:686-744, hatari/src/floppy_ipf.c:752-764, hatari/CMakeLists.txt:246, hatari/cmake/config-cmake.h:99-101, DEVELOP.md:56, DEVELOP.md:59"
+    note: >
+      Opened with dlopen on the first IPF or CTR read, from the dlopen
+      search path or next to the core, and required to export the CAPS
+      functions the core imports; without it those images are refused
+      with a notification and every other format still works.
+      rsn8887/capsimg publishes one build per platform under this name.
+
+  - name: "capsimg.dll"
+    path: null
+    description: "CAPSImage 5.1 shared library for IPF and CTR floppy images, Windows build"
+    required: false
+    source_ref: "hatari/src/floppy_ipf.c:320-331, hatari/src/floppy_ipf.c:632-640, hatari/src/floppy_ipf.c:686-744, hatari/src/floppy_ipf.c:752-764, DEVELOP.md:56"
+    note: >
+      Opened with LoadLibrary on the first IPF or CTR read, from the
+      RetroArch directory or the library search path; without it those
+      images are refused with a notification and every other format still
+      works.