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
NotAROMFSErrorif no valid ROMFS block is found, andCRCErroron a corrupt block. A member of a multi-ROM set parses with the part of any file it shares with a neighbouring ROM held inleading_fragment/trailing_fragmentrather than infiles. A ROM with no&2Bterminator — a truncated or damaged image — does not raise: it parses to an incomplete ROMFS (is_completeis False) holding the complete files it could read, with any dangling trailing file dropped.- Return type:
- 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 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 is_complete: bool¶
Whether the block chain reaches this ROM’s
&2Bend 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; seeis_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 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
&2Bend 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. Seedocs/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 withROMFSErrorfor a ROM that shares a file with a neighbouring ROM (is_set_member).
- to_bytes()¶
Serialise to a whole ROM image of the original size.
The header/handler prefix is preserved verbatim, the file chain and
&2Bend 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&2Bis the only space the filing system may grow into; exceeding it raisesROMFullError. An incomplete image cannot be serialised (there is no whole filing system to write back); that raisesROMFSError.- Return type:
- 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;0for files this library creates, which follow the Acornsoft convention. Thelast(&80) and*RUN-only (&01) bits are not held here — they are derived from the block position and run_only respectively.- Parameters:
- 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
&2Bend-of-ROM marker into the next-lower ROM, which resumes with a header for the next block (seedocs/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 byROMFSSet.raw holds the fragment’s on-ROM bytes verbatim, so the member it came from re-serialises byte-exact.
- Parameters:
- 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
&2Bend-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.filesjoins such a file back into oneROMFSFileat the place it starts. Membership and order are given explicitly; they are never inferred from file names. Seedocs/romfs-format-spec.md§7.- Parameters:
members (Iterable[ROMFS])
- classmethod from_images(images)¶
Parse a set from ROM images given highest socket first.
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-lockLnever 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-lockLnever 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,memoryviewor any iterable of integers in0..255. The empty input has CRC0x0000; the canonical check stringb"123456789"has CRC0x31C3.
Exceptions¶
- exception oaknut.romfs.ROMFSError(*args, exit_code=None)¶
Base exception for all ROMFS errors.
- exception oaknut.romfs.NotAROMFSError(*args, exit_code=None)¶
The image is not a recognisable ROMFS paged ROM.
- exception oaknut.romfs.CRCError(*args, exit_code=None)¶
A stored header or data CRC does not match the computed value.
- exception oaknut.romfs.TruncatedROMError(*args, exit_code=None)¶
The ROM ends in the middle of a block header or its data.