Skip to main content

Overlayed Filesystem

Spectranext's local XFS filesystem is made from multiple storage layers that appear as one directory tree:

  • System ROMFS: built-in, read-only files shipped with the firmware.
  • RAMFS: 4MB of temporary storage backed by PSRAM.
  • Flash: 4MB of persistent storage in external flash.

You do not mount these layers separately. The normal local filesystem mount, xfs://ram/, exposes them at once.

%mount "xfs://ram/"
%cat

The result is an overlayed filesystem: built-in system files, committed flash files, and temporary RAM files are shown together, opened through the same paths, and used through the normal Spectranet VFS calls.

Why These Layers?​

RAMFS is fast and disposable. It is good for quick iteration, test output, downloads, generated data, and program scratch files. Files uploaded from your computer are temporary by default, so development stays frictionless.

Flash is permanent. When a file should survive reset or power loss, commit it to flash. This is useful for favorite TAP files, tools, configuration generated by your own programs, or anything you want ready at a moment's notice.

ROMFS is built into the firmware. It is used for files Spectranext itself provides, such as bundled tools under /sys/bin. These files are always available after boot and do not consume your writable RAM or flash storage.

Lookup Rules​

When a program reads or stats a path, XFS checks the overlay from top to bottom:

  1. If the path exists in ROMFS, the built-in version is used.
  2. Otherwise, if the path exists in flash, the committed version is used.
  3. Otherwise, if the path exists in RAM, the temporary version is used.
  4. If it exists in no layer, the operation returns a normal not-found error.

Directory listings merge the layers. Built-in entries are reported first, followed by committed flash entries, followed by RAM entries that are not hidden by an entry of the same name in an earlier layer.

Built-In Read-Only Folders​

Some folders are supplied by Spectranext and are read-only from the user's point of view. The most visible one is:

/sys/bin

This folder contains bundled programs and utilities. For example, the built-in Spectrum-side file browser is loaded from there by the launcher and by %browser.

You can list and read files from a built-in folder just like any other XFS path:

%cat "/sys/bin"
%tapein "/sys/bin/browser.tap" : LOAD ""

You cannot upload, delete, rename, or overwrite files inside a read-only folder. If you try to copy a file into /sys/bin, the operation fails with a not-writable/read-only filesystem error. This is expected: those files are part of the firmware image, not user storage.

Use another folder for your own files, such as the root directory or a folder you create yourself:

%mkdir "games"

Write Rules​

New user files are temporary by default. If a program creates notes.txt and there is no built-in or committed flash file with that name, XFS creates it in RAM.

If a path already exists in ROMFS, it cannot be opened for writing. If a path already exists in flash, opening that same path for writing opens the flash-backed file. This lets committed files be updated in place without creating a hidden RAM copy.

Delete operations remove the path from writable layers. Built-in ROMFS files cannot be deleted, so they remain visible after delete attempts.

Committing Files​

Committing copies a file or directory from RAM to flash and removes the RAM source. After that, the same path remains visible through the same mount, but it is backed by persistent storage.

Open the Spectranext File Browser, upload the files you want, select a temporary file, and click Commit To Flash.

Committed files are shown with a storage indicator in the file list.

Example Workflow​

  1. Upload game.tap from the Browser or with spx.
  2. Run it from XFS while iterating.
  3. When it is worth keeping, commit it to flash.
  4. Keep using the same filename and the same mount point.

There is no /flash directory, no separate persistent mount, and no change required in programs that already open files from XFS. Built-in system files simply appear at their normal paths.

Storage State​

XFS reports whether a listed or statted entry comes from RAM or flash. Tools use this to show whether a file is temporary or committed.

  • 0: RAM-backed temporary file.
  • 1: Flash-backed committed or built-in read-only file.

This state is metadata about the overlay layer, not part of the filename. A committed file still uses the same path it had before it was committed.