oaknut-romfs 12.3.0__tar.gz

oaknut_romfs-12.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Smallshire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oaknut_romfs-12.3.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: oaknut-romfs
+Version: 12.3.0
+Summary: Python library for Acorn ROM Filing System (ROMFS) paged-ROM images
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-romfs
+Project-URL: Documentation, https://rob-smallshire.github.io/oaknut/disc/api/reference/romfs.html
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: oaknut-file>=10.0
+Requires-Dist: oaknut-discimage>=10.0
+Requires-Dist: oaknut-filesystem>=10.0
+Requires-Dist: oaknut-basic>=10.0
+Provides-Extra: cli
+Requires-Dist: oaknut-cli>=10.0; extra == "cli"
+Dynamic: license-file
+
+# oaknut-romfs
+
+Acorn ROM Filing System (ROMFS) support for the [oaknut](https://github.com/rob-smallshire/oaknut)
+family of packages.
+
+ROMFS is the filing system for paged ROMs on the BBC Micro and Acorn
+Electron — sideways ROMs and cartridges. It stores files in the same
+block layout as the Cassette Filing System (CFS), with the ROM image
+standing in for the tape: each file is a chain of CFS-format blocks
+carrying Acorn load and execution addresses, a block number, a length,
+a flag byte, and header and data CRCs, introduced by a standard
+paged-ROM service header.
+
+The medium is read-only ROM, so the filing system is flat: there are no
+directories, and a file's metadata is the load/exec pair plus a lock
+bit, exactly as on cassette.
+
+This package contributes ROMFS to the `oaknut.filesystem` extension axis,
+so ROMFS images are identified, listed and read through the `disc` CLI
+alongside the disc-based filing systems.
+
+## Status
+
+Pre-alpha. The package is being built up format-first: see
+[`docs/romfs-format-spec.md`](docs/romfs-format-spec.md) for the on-ROM
+byte layout and [`docs/architecture.md`](docs/architecture.md) for the
+package design and its mapping onto the `oaknut.filesystem` contract.
+
+## Installation
+
+```sh
+uv add oaknut-romfs
+```
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

oaknut_romfs-12.3.0/README.md

@@ -0,0 +1,37 @@
+# oaknut-romfs
+
+Acorn ROM Filing System (ROMFS) support for the [oaknut](https://github.com/rob-smallshire/oaknut)
+family of packages.
+
+ROMFS is the filing system for paged ROMs on the BBC Micro and Acorn
+Electron — sideways ROMs and cartridges. It stores files in the same
+block layout as the Cassette Filing System (CFS), with the ROM image
+standing in for the tape: each file is a chain of CFS-format blocks
+carrying Acorn load and execution addresses, a block number, a length,
+a flag byte, and header and data CRCs, introduced by a standard
+paged-ROM service header.
+
+The medium is read-only ROM, so the filing system is flat: there are no
+directories, and a file's metadata is the load/exec pair plus a lock
+bit, exactly as on cassette.
+
+This package contributes ROMFS to the `oaknut.filesystem` extension axis,
+so ROMFS images are identified, listed and read through the `disc` CLI
+alongside the disc-based filing systems.
+
+## Status
+
+Pre-alpha. The package is being built up format-first: see
+[`docs/romfs-format-spec.md`](docs/romfs-format-spec.md) for the on-ROM
+byte layout and [`docs/architecture.md`](docs/architecture.md) for the
+package design and its mapping onto the `oaknut.filesystem` contract.
+
+## Installation
+
+```sh
+uv add oaknut-romfs
+```
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

oaknut_romfs-12.3.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "oaknut-romfs"
+dynamic = ["version"]
+authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
+description = "Python library for Acorn ROM Filing System (ROMFS) paged-ROM images"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "oaknut-file>=10.0",
+    "oaknut-discimage>=10.0",
+    "oaknut-filesystem>=10.0",
+    "oaknut-basic>=10.0",
+]
+
+# The `cli` extra pulls the shared CLI toolkit so this package can
+# contribute `disc romfs` subcommands. The library core never imports it,
+# so a bare install stays CLI-free.
+[project.optional-dependencies]
+cli = ["oaknut-cli>=10.0"]
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-romfs"
+Documentation = "https://rob-smallshire.github.io/oaknut/disc/api/reference/romfs.html"
+Repository = "https://github.com/rob-smallshire/oaknut"
+Issues = "https://github.com/rob-smallshire/oaknut/issues"
+
+# Filesystem contributed to the oaknut.filesystem axis — discovered at
+# runtime via this entry point, so the detector ships with the format it
+# detects.
+[project.entry-points."oaknut.filesystem"]
+acorn-romfs = "oaknut.romfs.filesystem:AcornROMFS"
+
+# Admin subcommands contributed to the `disc` CLI on the oaknut.command axis:
+# `disc romfs <subcommand>`. Loaded only with the [cli] extra.
+[project.entry-points."oaknut.command"]
+romfs = "oaknut.romfs.cli:romfs"
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.romfs.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_romfs-12.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oaknut_romfs-12.3.0/src/oaknut/romfs/__init__.py

@@ -0,0 +1,46 @@
+"""Acorn ROM Filing System (ROMFS).
+
+ROMFS is Acorn's filing system for *paged ROMs* — the sideways ROM and
+cartridge format used on the BBC Micro and Acorn Electron. It stores
+files in the same block layout as the Cassette Filing System (CFS): the
+backing store is simply a linear ROM image rather than a tape, so a
+file is a chain of CFS-format blocks (load/exec addresses, block number,
+length, flag byte, header and data CRCs) preceded by a standard paged-ROM
+service header.
+
+Because the medium is read-only ROM the filing system is flat — there are
+no directories — and a file's metadata is the Acorn load/exec pair plus a
+lock bit, exactly as on cassette. This package adapts that on-ROM format
+to the :mod:`oaknut.filesystem` extension contract so ROMFS images are
+identifiable, listable and readable through the ``disc`` CLI alongside the
+disc-based filing systems.
+
+See ``docs/romfs-format-spec.md`` for the on-ROM byte layout and
+``docs/architecture.md`` for how the native API maps onto the
+``oaknut.filesystem`` plug-in interface.
+"""
+
+from __future__ import annotations
+
+from oaknut.romfs.crc import crc16_ccitt
+from oaknut.romfs.exceptions import (
+    CRCError,
+    NotAROMFSError,
+    ROMFSError,
+    ROMFullError,
+    TruncatedROMError,
+)
+from oaknut.romfs.romfs import ROMFS, ROMFSFile
+
+__version__ = "12.3.0"
+
+__all__ = [
+    "ROMFS",
+    "ROMFSFile",
+    "ROMFSError",
+    "NotAROMFSError",
+    "CRCError",
+    "TruncatedROMError",
+    "ROMFullError",
+    "crc16_ccitt",
+]

oaknut_romfs-12.3.0/src/oaknut/romfs/block.py

@@ -0,0 +1,142 @@
+"""The CFS block-header codec — parse and serialise one ROMFS block.
+
+A ROMFS file is a chain of Cassette Filing System blocks. A *header
+block* begins with the sync byte ``&2A`` followed by the fields modelled
+by :class:`BlockHeader`; *continuation* blocks within a multi-block file
+use a single ``&23`` marker instead of a header and are implicitly 256
+data bytes. The filing system ends with a single ``&2B`` byte.
+
+This module owns the byte-level header format (field layout, flag bits,
+CRC placement). Walking a chain into files and assembling files into a
+chain lives one layer up, in :mod:`oaknut.romfs.romfs`. See
+``docs/romfs-format-spec.md`` §2.
+"""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass
+
+from oaknut.romfs.crc import crc16_ccitt
+from oaknut.romfs.exceptions import CRCError, TruncatedROMError
+
+#: A header block starts with this synchronisation byte (``'*'``).
+SYNC_BYTE = 0x2A
+#: A continuation (data-only) block within a multi-block file (``'#'``).
+INTER_BLOCK_MARKER = 0x23
+#: A single byte marking the end of the filing-system data (``'+'``).
+END_OF_FILESYSTEM = 0x2B
+
+#: Flag bit: this is the last block of its file.
+FLAG_LAST = 0x80
+#: Flag bit: this block carries no data (mkromfs sets it; Acorn does not —
+#: test ``block_length == 0`` rather than this bit to detect an empty file).
+FLAG_EMPTY = 0x40
+#: Flag bit: the file is *RUN-only — a form of copy protection. The MOS
+#: refuses to ``*LOAD`` / ``*EXEC`` / ``CHAIN`` it (only ``*RUN``); the OS
+#: calls this "locked", but it is read-protection, not the disc filing
+#: systems' delete-lock (see ``oaknut.file.Access.X``).
+FLAG_RUN_ONLY = 0x01
+
+#: Maximum file-name length (characters), excluding the NUL terminator.
+MAX_NAME_LENGTH = 10
+#: A full block carries this many data bytes; a continuation block always does.
+BLOCK_DATA_SIZE = 256
+
+# Fixed-size part of the header following the NUL-terminated name:
+# load (4), exec (4), block number (2), block length (2), flag (1),
+# end-of-file address (4). The two-byte header CRC follows.
+_FIXED = struct.Struct("<IIHHBI")
+
+
+@dataclass(frozen=True)
+class BlockHeader:
+    """The header of one CFS block, in decoded form.
+
+    The multi-byte integer fields are stored little-endian on the ROM; the
+    trailing header CRC (handled by :meth:`to_bytes` / :meth:`parse`) is
+    stored big-endian. *end_address* is the paged-ROM address of the byte
+    just past this file — i.e. where the next file begins.
+    """
+
+    name: str
+    load_address: int
+    exec_address: int
+    block_number: int
+    block_length: int
+    flag: int
+    end_address: int
+
+    @property
+    def is_last(self) -> bool:
+        """Whether this is the final block of its file (flag bit 7)."""
+        return bool(self.flag & FLAG_LAST)
+
+    @property
+    def is_empty(self) -> bool:
+        """Whether the block carries no data (length 0)."""
+        return self.block_length == 0
+
+    @property
+    def is_run_only(self) -> bool:
+        """Whether the file is *RUN-only / copy-protected (flag bit 0)."""
+        return bool(self.flag & FLAG_RUN_ONLY)
+
+    def field_bytes(self) -> bytes:
+        """The header bytes the CRC is taken over: name through end address.
+
+        This is everything after the sync byte and before the header CRC.
+        """
+        return (
+            self.name.encode("latin-1")
+            + b"\x00"
+            + _FIXED.pack(
+                self.load_address,
+                self.exec_address,
+                self.block_number,
+                self.block_length,
+                self.flag,
+                self.end_address,
+            )
+        )
+
+    def to_bytes(self) -> bytes:
+        """The full on-ROM header: sync byte, fields, big-endian header CRC."""
+        fields = self.field_bytes()
+        crc = crc16_ccitt(fields)
+        return bytes([SYNC_BYTE]) + fields + crc.to_bytes(2, "big")
+
+    @classmethod
+    def parse(cls, buf, offset: int = 0) -> tuple["BlockHeader", int]:
+        """Parse a header block at *offset* (which must hold the sync byte).
+
+        Returns ``(header, data_offset)`` where *data_offset* is the offset
+        of the block's data, just past the two-byte header CRC. Raises
+        :class:`CRCError` if the stored header CRC does not match, and
+        :class:`TruncatedROMError` if the buffer ends mid-header.
+        """
+        view = memoryview(buf)
+        if offset >= len(view) or view[offset] != SYNC_BYTE:
+            raise TruncatedROMError(f"no block sync byte at offset {offset}")
+        name_start = offset + 1
+        nul = buf.find(b"\x00", name_start)
+        if nul < 0:
+            raise TruncatedROMError("unterminated block-header name")
+        fixed_start = nul + 1
+        crc_start = fixed_start + _FIXED.size
+        crc_end = crc_start + 2
+        if crc_end > len(view):
+            raise TruncatedROMError("block header runs past the end of the ROM")
+        name = bytes(view[name_start:nul]).decode("latin-1")
+        load, execa, block_number, block_length, flag, end_address = _FIXED.unpack(
+            view[fixed_start:crc_start]
+        )
+        stored_crc = int.from_bytes(view[crc_start:crc_end], "big")
+        computed = crc16_ccitt(view[name_start:crc_start])
+        if stored_crc != computed:
+            raise CRCError(
+                f"header CRC mismatch for {name!r}: "
+                f"stored &{stored_crc:04X}, computed &{computed:04X}"
+            )
+        header = cls(name, load, execa, block_number, block_length, flag, end_address)
+        return header, crc_end

oaknut_romfs-12.3.0/src/oaknut/romfs/cli.py

@@ -0,0 +1,76 @@
+"""ROMFS contributed ``disc`` commands.
+
+The ``disc romfs`` command group, contributed to the CLI on the
+``oaknut.command`` axis (see ``docs/dev/contributed-commands.md``). It holds
+the ROMFS-specific paged-ROM *header* properties that do not fit the generic
+mount model — the copyright string and the binary version byte — as simple
+getters and setters on an existing image. Creating an image is the generic
+``disc create``; this group only queries and tweaks header metadata.
+
+This module imports Click and is loaded only when ``oaknut-romfs`` is
+installed with its ``[cli]`` extra; the library core never imports it.
+Errors raised as :class:`~oaknut.romfs.exceptions.ROMFSError` are reported
+by the CLI's shared error boundary.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+_IMAGE = click.argument("image", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+
+
+@click.group()
+def romfs() -> None:
+    """Acorn ROM Filing System administration."""
+
+
+@romfs.command(name="get-copyright")
+@_IMAGE
+def get_copyright_command(image: Path) -> None:
+    """Print the paged-ROM copyright string of IMAGE."""
+    from oaknut.romfs.romfs import get_copyright
+
+    click.echo(get_copyright(image.read_bytes()))
+
+
+@romfs.command(name="set-copyright")
+@_IMAGE
+@click.argument("copyright")
+def set_copyright_command(image: Path, copyright: str) -> None:
+    """Set the paged-ROM copyright string of IMAGE (must begin "(C)").
+
+    A same-length string is written in place. A different length moves the
+    service handler, so the ROM is rebuilt — done only for a created-style
+    ROM (no language entry, nothing after the filing system); other ROMs are
+    refused to avoid disturbing their code.
+    """
+    from oaknut.romfs.romfs import set_copyright
+
+    image.write_bytes(set_copyright(image.read_bytes(), copyright))
+
+
+@romfs.command(name="get-version")
+@_IMAGE
+def get_version_command(image: Path) -> None:
+    """Print the paged-ROM binary version byte of IMAGE."""
+    from oaknut.romfs.romfs import get_version
+
+    click.echo(get_version(image.read_bytes()))
+
+
+@romfs.command(name="set-version")
+@_IMAGE
+@click.argument("version")
+def set_version_command(image: Path, version: str) -> None:
+    """Set the paged-ROM binary version byte of IMAGE (0-255).
+
+    VERSION honours a base prefix, like the address commands: ``0x`` hex
+    (e.g. ``0x80``), ``0o`` octal, ``0b`` binary, or a plain decimal value.
+    """
+    from oaknut.file import parse_address
+    from oaknut.romfs.romfs import set_version
+
+    image.write_bytes(set_version(image.read_bytes(), parse_address(version)))

oaknut_romfs-12.3.0/src/oaknut/romfs/crc.py

@@ -0,0 +1,34 @@
+"""The CRC used by ROMFS / Cassette Filing System blocks.
+
+Both the block header CRC and the block data CRC are CRC-16/XMODEM:
+polynomial ``0x1021``, initial value ``0x0000``, processed
+most-significant-bit first with no input/output reflection. On the ROM the
+16-bit result is stored **big-endian** (most-significant byte first),
+unlike the little-endian multi-byte integer fields of the header.
+
+See ``docs/romfs-format-spec.md`` §3.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+_POLYNOMIAL = 0x1021
+
+
+def crc16_ccitt(data: Iterable[int]) -> int:
+    """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``.
+    """
+    crc = 0
+    for byte in data:
+        crc ^= byte << 8
+        for _ in range(8):
+            if crc & 0x8000:
+                crc = ((crc << 1) ^ _POLYNOMIAL) & 0xFFFF
+            else:
+                crc = (crc << 1) & 0xFFFF
+    return crc

oaknut_romfs-12.3.0/src/oaknut/romfs/exceptions.py

@@ -0,0 +1,49 @@
+"""Exception hierarchy for oaknut.romfs.
+
+All ROMFS-specific exceptions derive from :class:`ROMFSError`, which in
+turn derives from the shared :class:`~oaknut.file.exceptions.FSError` base
+(a ``DataError``). The CLI boundary reads an exception's ``exit_code`` to
+decide its exit status, so each subclass pins a specific :class:`ExitCode`.
+
+Hierarchy::
+
+    FSError (oaknut.file.exceptions, a DataError)
+    └── ROMFSError
+        ├── NotAROMFSError      (ExitCode.DATA_ERR)
+        ├── CRCError            (ExitCode.DATA_ERR)
+        ├── TruncatedROMError   (ExitCode.DATA_ERR)
+        └── ROMFullError        (ExitCode.CANT_CREATE)
+"""
+
+from __future__ import annotations
+
+from exit_codes import ExitCode
+from oaknut.file.exceptions import FSError
+
+
+class ROMFSError(FSError):
+    """Base exception for all ROMFS errors."""
+
+
+class NotAROMFSError(ROMFSError):
+    """The image is not a recognisable ROMFS paged ROM."""
+
+    _exit_code = ExitCode.DATA_ERR
+
+
+class CRCError(ROMFSError):
+    """A stored header or data CRC does not match the computed value."""
+
+    _exit_code = ExitCode.DATA_ERR
+
+
+class TruncatedROMError(ROMFSError):
+    """The ROM ends in the middle of a block header or its data."""
+
+    _exit_code = ExitCode.DATA_ERR
+
+
+class ROMFullError(ROMFSError):
+    """The files no longer fit within the ROM's capacity."""
+
+    _exit_code = ExitCode.CANT_CREATE