oaknut.romfs

The Acorn ROM Filing System: files stored in a paged ROM (a sideways ROM or cartridge) for the BBC Micro and Acorn Electron. A ROMFS image holds files in Cassette Filing System block format behind a standard paged-ROM header, so the filing system is flat: no directories, and each file carries load and execution addresses and a lock bit. A game spread over several ROMs is a ROMFSSet.

Every name documented here is importable directly from oaknut.romfs.

The filesystem

class oaknut.romfs.ROMFS(files, *, rom_type, header_title, version, copyright, image, data_offset, fs_end, complete, leading_fragment=None, trailing_fragment=None)

An Acorn ROM Filing System image, parsed into its files.

Parameters:
classmethod from_bytes(buf)

Parse a ROMFS image from buf (bytes-like).

Raises NotAROMFSError if no valid ROMFS block is found, and CRCError on a corrupt block. A member of a multi-ROM set parses with the part of any file it shares with a neighbouring ROM held in leading_fragment / trailing_fragment rather than in files. A ROM with no &2B terminator — a truncated or damaged image — does not raise: it parses to an incomplete ROMFS (is_complete is False) holding the complete files it could read, with any dangling trailing file dropped.

Return type:

ROMFS

property files: tuple[ROMFSFile, ...]

All files in catalogue order, including any leading title block.

property title_block: ROMFSFile | None

The leading zero-length title block, or None.

By convention the first file is a zero-length marker naming the disc. Acornsoft wraps the name in asterisks (*Hopper01*); the BBC Master demos use a bare name (DEMO-A); some ROMs (Zalaga) have none, beginning directly with a real file. Detection is therefore positional — a zero-length first file — not name-based.

property data_files: tuple[ROMFSFile, ...]

The files excluding any leading title block.

property rom_type: int

The paged-ROM type byte (bit 7 set marks the service entry).

property has_service_entry: bool

Whether the ROM type byte advertises a service entry.

property header_title: str

The paged-ROM header title (shown by *HELP).

property version: int

The binary version byte from the paged-ROM header.

property copyright: str

The paged-ROM copyright string (begins (C)).

property title: str

The filing-system title (the *…* title block, unwrapped).

Empty when the image has no title block (as on the BBC Zalaga ROM), which is the title *. displays.

property data_offset: int

Offset at which the filing-system data begins within the image.

property is_complete: bool

Whether the block chain reaches this ROM’s &2B end marker.

False marks a truncated or damaged image: the chain ran to the end of the ROM, or into bytes that are not a block, without a terminator. Such an image is read as far as its complete files and is treated as read-only. A member of a multi-ROM set is complete — each member ends with its own &2B — even when a file continues into the next ROM; see is_set_member.

property leading_fragment: ROMFSFragment | None

The end of a file begun in the previous ROM of a set, or None.

property trailing_fragment: ROMFSFragment | None

The start of a file continued in the next ROM of a set, or None.

property continues_from_previous: bool

Whether this ROM begins mid-file, continuing the previous ROM.

property continues_in_next: bool

Whether this ROM ends mid-file, continuing in the next ROM.

property is_set_member: bool

Whether this ROM shares a file with a neighbouring ROM of a set.

Such a ROM is one piece of a larger filing system: rewriting it would move or drop the part of the file it shares, breaking the whole set, so it is never rebuilt. A member whose files all end cleanly is indistinguishable from a standalone ROM, so this is False for it.

property is_plain: bool

Whether nothing but padding follows the filing system.

A plain ROMFS holds only the filing system: everything after the &2B end marker is a single padding byte to the end of the ROM. A composite ROM carries opaque content after the filing system — typically a service handler answering *HELP (service call &09) or a co-resident language. The writer preserves that content, and the mount treats a composite ROM as read-only to avoid corrupting it. See docs/romfs-format-spec.md.

with_files(files)

A copy with its files replaced, keeping the same ROM container.

The header/handler prefix, header metadata and image size are carried over; to_bytes() lays the new chain out within the same ROM, so the result re-parses as the same kind of image. Refused with ROMFSError for a ROM that shares a file with a neighbouring ROM (is_set_member).

Parameters:

files (tuple[ROMFSFile, ...])

Return type:

ROMFS

to_bytes()

Serialise to a whole ROM image of the original size.

The header/handler prefix is preserved verbatim, the file chain and &2B end marker are rebuilt, and any opaque trailing content (a language ROM’s code, as in Countdown To Doom) is kept at its original address. The padding run immediately after the original &2B is the only space the filing system may grow into; exceeding it raises ROMFullError. An incomplete image cannot be serialised (there is no whole filing system to write back); that raises ROMFSError.

Return type:

bytes

class oaknut.romfs.ROMFSFile(name, load_address, exec_address, run_only, data, end_address=0, flag_extra=0)

One file stored in a ROMFS image.

data is the whole file, reassembled across its blocks. end_address is the paged-ROM address just past the file, as stored in its headers. run_only is the copy-protection bit (flag bit 0): a *RUN-only file the MOS will not *LOAD / *EXEC / CHAIN. The OS calls it “locked”, but it is read-protection, distinct from the disc filing systems’ delete-lock (oaknut.file.Access.L) — canonically owner E without R (oaknut.file.Access.is_run_only).

flag_extra preserves the block-flag bits this class does not otherwise model — chiefly the &40 “no data” bit the New Advanced User Guide example sets on a zero-length block, which Acorn’s own ROMs leave clear. Captured on parse and re-emitted on serialise so a round-trip is byte-exact; 0 for files this library creates, which follow the Acornsoft convention. The last (&80) and *RUN-only (&01) bits are not held here — they are derived from the block position and run_only respectively.

Parameters:
property length: int

The file length in bytes (the *. total-length column).

property last_block_number: int

The block number of the file’s final block (the *. first column).

Equals the number of 256-byte blocks minus one; zero for an empty file or any file of 256 bytes or fewer.

class oaknut.romfs.ROMFSFragment(name, load_address, exec_address, run_only, first_block_number, block_count, data, ends_file, end_address, flag_extra, raw)

The part of a file held by one member ROM of a multi-ROM set.

A file’s block chain may run past the &2B end-of-ROM marker into the next-lower ROM, which resumes with a header for the next block (see docs/romfs-format-spec.md §7). A ROM that ends mid-file carries a trailing fragment (starting at block 0, not ending the file); a ROM that begins mid-file carries a leading fragment (starting at a block number above 0). A fragment is not a file in its own right: it is joined to its neighbours by ROMFSSet.

raw holds the fragment’s on-ROM bytes verbatim, so the member it came from re-serialises byte-exact.

Parameters:
property starts_file: bool

Whether this fragment holds the file’s first block.

property next_block_number: int

The block number the fragment’s continuation must start with.

class oaknut.romfs.ROMFSSet(members)

The filing system of several ROMs read as one, in socket order.

The MOS reads the RFS ROMs from the highest socket down, moving to the next-lower ROM at each &2B end-of-ROM marker, so a set’s catalogue is the members’ files in that order — and a file may run from one member into the next. files joins such a file back into one ROMFSFile at the place it starts. Membership and order are given explicitly; they are never inferred from file names. See docs/romfs-format-spec.md §7.

Parameters:

members (Iterable[ROMFS])

classmethod from_images(images)

Parse a set from ROM images given highest socket first.

Parameters:

images (Iterable)

Return type:

ROMFSSet

property members: tuple[ROMFS, ...]

The member ROMs, highest socket first.

property files: tuple[ROMFSFile, ...]

Every file in the set in catalogue order, spanning files joined.

The ROMFS access convention maps a file’s CFS flag byte to and from the Access word (see AccessConvention).

class oaknut.romfs.AcornROMFSAccessConvention

ROMFS access: readable, or *RUN-only.

An ordinary file reads as owner read (R). A run-only file reads as owner execute without read (E), the Acorn access byte’s own representation of run-only (BeebWiki, File access). Writing makes a file run-only exactly when the access is run-only, so the disc filing systems’ delete-lock L never does: a locked DFS file copied onto a ROM stays loadable.

oaknut.romfs.ACORN_ROMFS_ACCESS = <oaknut.romfs.access.AcornROMFSAccessConvention object>

readable, or *RUN-only.

An ordinary file reads as owner read (R). A run-only file reads as owner execute without read (E), the Acorn access byte’s own representation of run-only (BeebWiki, File access). Writing makes a file run-only exactly when the access is run-only, so the disc filing systems’ delete-lock L never does: a locked DFS file copied onto a ROM stays loadable.

Type:

ROMFS access

Block CRCs

oaknut.romfs.crc16_ccitt(data)

Return the CRC-16/XMODEM of data (any iterable of byte values).

Accepts bytes, bytearray, memoryview or any iterable of integers in 0..255. The empty input has CRC 0x0000; the canonical check string b"123456789" has CRC 0x31C3.

Parameters:

data (Iterable[int])

Return type:

int

Exceptions

exception oaknut.romfs.ROMFSError(*args, exit_code=None)

Base exception for all ROMFS errors.

Parameters:
  • args (object)

  • exit_code (Optional[ExitCode])

Return type:

None

exception oaknut.romfs.NotAROMFSError(*args, exit_code=None)

The image is not a recognisable ROMFS paged ROM.

Parameters:
  • args (object)

  • exit_code (Optional[ExitCode])

Return type:

None

exception oaknut.romfs.CRCError(*args, exit_code=None)

A stored header or data CRC does not match the computed value.

Parameters:
  • args (object)

  • exit_code (Optional[ExitCode])

Return type:

None

exception oaknut.romfs.TruncatedROMError(*args, exit_code=None)

The ROM ends in the middle of a block header or its data.

Parameters:
  • args (object)

  • exit_code (Optional[ExitCode])

Return type:

None

exception oaknut.romfs.ROMFullError(*args, exit_code=None)

The files no longer fit within the ROM’s capacity.

Parameters:
  • args (object)

  • exit_code (Optional[ExitCode])

Return type:

None