Firmware & Files (ROMEMUL)

This page describes the firmware of the SidecarTridge TOS and Kickstart emulators, v4.0.0, which runs on the ROM Emulator module.

Table of contents
  1. ROMEMUL volume
    1. Files on the volume
  2. Safe eject (important)
  3. FAT12 notes
    1. Copying files (macOS / Windows / Linux)
  4. Magic file and folder names
  5. Firmware updates

ROMEMUL volume

The ROM Emulator exposes its on-board flash as a USB mass-storage volume (FAT12), named ROMEMUL.

The module decides what to do each time it is powered on:

  • If a computer talks to it on the USB-C cable during its first 2 seconds, it opens the ROMEMUL volume and lights its orange (Volume) LED. It does not emulate the ROM meanwhile.
  • Otherwise it emulates the selected ROM image and lights its green (Emulation) LED.

USB power alone, from a charger or a cable without data, starts the emulation. A cable plugged in after the first 2 seconds is not noticed until the next power-on or reset, unless the module has nothing to emulate: then it keeps looking for a computer.

v4.0.0

Files on the volume

On a SidecarTridge TOS or Kickstart board you find these files in the root of ROMEMUL:

  • INDEX.HTM: opens the product’s documentation.
  • INFO.TXT: the firmware version and date, the microcontroller, the board variant, the board ID and the flash size. The firmware writes it only when the volume has none, so after a firmware update it still shows the old version until it is deleted.
  • CONFIG.TXT: the settings (bus timing, RESCUE_TIMEOUT, ACCELERATED_BUS and others). See the TOS or Kickstart Advanced Settings.
  • DEFAULT.TXT: the name of the default ROM image.
  • RESCUE.TXT: the name of the rescue ROM image, normally the ROM Rescue Switcher.
  • The ROM images themselves, the rescue switcher’s among them.
  • The host-side tools, product-specific:
    • SWITCHER.TOS on the TOS emulator;
    • the AMIGA folder on the Kickstart emulator, with SWITCHER.ADF, SWITCHER and SWITCHER.ST.

The firmware lists up to 64 ROM images, sorted by name, with names of up to 63 characters. It never takes for a ROM image the files above, folders, or files whose names start with a dot (.) or an underscore (_). Your operating system may add such hidden files; they are not used.

Safe eject (important)

As a rule of thumb, ALWAYS eject the ROMEMUL volume after making changes. The eject:

  1. flushes the FAT;
  2. makes the firmware rebuild its list of images, the default and rescue ones from DEFAULT.TXT and RESCUE.TXT, and its settings from CONFIG.TXT;
  3. leaves the module idle, with its LEDs off, until it is powered off or reset, unless one of the magic files below asks for something else.

FAT12 notes

  • The ROMEMUL volume uses FAT12 with a 4 KB cluster size.
  • File sizes may appear rounded up (4 KB steps). This is expected.
  • Writing runs at about 25 KB/s: every block is in the flash before the computer is told it is written. Reading runs at about 700 KB/s.

Copying files (macOS / Windows / Linux)

  • You can drag & drop files in most cases.
  • On macOS, Finder also creates hidden ._ files; they are ignored, but to avoid them copy from Terminal:
cp -R /path/to/ROM\ Images/* /Volumes/ROMEMUL/

On Linux, the mount point varies by distro:

cp -R /path/to/ROM\ Images/* /media/username/ROMEMUL/

Magic file and folder names

Two file (or folder) names trigger an action when the ROMEMUL volume is ejected. The file is deleted once the action is triggered.

  • REBOOT: after the eject, the module restarts emulating the default ROM image, with the USB cable still connected, and does not open the volume again.
  • RESET: after the eject, the module enters BOOTSEL mode and shows an RP2350 volume, ready for a new firmware.

v4.0.0

Before firmware v4.0.0, REBOOT opened the volume again.

Firmware updates

The ROM Emulator ships with firmware installed. Firmware files come in two kinds:

  • an update file, which replaces the firmware only and keeps the volume, the ROM images and the settings:
    • sidecartridge-tos-rp2350a-v4.0.0.uf2;
    • sidecartridge-kickstart-rp2350a-update-v4.0.0.uf2 (the same firmware);
  • full files, which rewrite all 16 MB with a new volume:
    • ...-emutos-192k-full-..., ...-emutos-256k-full-...;
    • ...-diagrom-full-....

The rp2350a files are for this module. A firmware built for another board does not run: the module blinks its green and orange LEDs together, and the right file installed from BOOTSEL mode fixes it.

Install a file by copying it to the RP2350 volume in BOOTSEL mode, or from webflash.sidecartridge.com. The TOS and Kickstart guides explain both.

A full file erases every image on the volume. Back up your ROMEMUL contents before installing one.

Previous: Hardware Integration Main Next: Firmware API