Table of Contents

Cartridge image tools

Images and cartridge writes
Existing DATA and ENVIRONMENT creation
Build a regular image from a prepared directory
Dependencies and current evidence

include_toc

include_toc
true

Cartridge image tools

Development reference and historical context. For current operating instructions, use the user manual. Acceptance applies only to the source and artifacts identified in each record.

Documentation index · Cartridge usage

For new software cartridges, use the Linux workstation workflow: fds-cartridge builds xz bundles and a complete metadata-first 1+m GPT image, then previews and verifies a whole-drive write. Software image creation is not an on-Pi operation. The commands below cover existing target media management and legacy compatibility.

Historical M9 software acceptance verified image creation for all four classes, confirmed virtual USB writes, and boot of a newly written SYSTEM. Physical media and Pi testing remain deferred; see validation evidence. Images built before M9 do not contain these commands. Build a new image to use them:

make rootfs PROFILE=cli
make rootfs-test
make system-card PROFILE=cli
make media-image-test
make media-test

Run these build commands on the x86_64 host from the repository root, after the first-build prerequisites. The integration checks use disposable virtual disks. The fds examples below run at the ARM FDS console; the static ARM executables do not run directly on an x86_64 shell. For an interactive console, use make console-vm; its initial bay map is deliberately unconfigured, so use the tests for the complete virtual write workflow.

Images and cartridge writes

An image is a regular file containing a complete GPT and its filesystems. Legacy classes use one partition; current software media use metadata plus payload partitions. Creating one does not touch a disk. Writing one selects a physical bay and requires a confirmation tied to that insertion, image hash and operation identifier.

Configure the physical bay map first using the cartridge guide. Unconfigured or ambiguous bays are refused. At the FDS console, inspect the target and eject any existing filesystem first:

fds inspect BAY04
fds eject BAY04
fds burn system /data/fds-system-cli.img BAY04

Do not eject a blank disk: it has no mounted filesystem. The running SYSTEM, internal BOOT/RECOVERY/INTERNAL partitions, mounts, swap and device-mapper holders are protected. The tools support 512-byte logical sectors. A larger target keeps the image's filesystem size; GPT backup metadata moves to the actual disk end. Unused space is not a secure erase of old data.

All cartridge eject requests are refused while a media operation is active. This keeps a source DATA filesystem attached while the worker holds its image file. Finish or cancel the operation first, then eject the source normally.

The preview shows the bay, model, serial when available, kernel insertion number, capacity, image class and SHA-256. Type the complete displayed phrase to proceed. There is no generic --yes switch. A wrong phrase, changed image or different insertion is rejected. Completion requires a flush, cache invalidation, readback, and valid final partition tables. A failed or interrupted write never reports SAFE.

For scripts, fds --json burn CLASS IMAGE BAY04 stops at the prepared preview. Use its exact id and confirmation fields with:

fds burn confirm OPERATION_ID 'EXACT PHRASE FROM PREVIEW'
fds burn status OPERATION_ID
fds burn wait OPERATION_ID
fds burn cancel OPERATION_ID

wait waits for a terminal result; confirm or cancel from another console if the operation is still awaiting confirmation. Cartridge status remains available while the worker hashes or writes. Confirmation expires after five minutes. Removing/reinserting media invalidates its insertion identity. A service restart records an unfinished operation as failed, leaving it unmounted.

Existing DATA and ENVIRONMENT creation

Use a writable working directory with enough free space for both a filesystem image and its GPT wrapper. /home/fds is temporary RAM storage; /data is better for large images, provided the source DATA is not the cartridge being overwritten.

cd /home/fds
fds format data BAY04 --label FELIS
fds format environment BAY04 --profile windowmaker --label 'WINDOW SYSTEM'

Each command first creates an image, then presents the same explicit confirmation. Labels are the display names shown by FDS; fixed GPT partition names identify the cartridge class. DATA uses ext4 and normally fills the target's available whole MiB. Use --size-mib 512 to choose a smaller filesystem. Its root belongs to the ordinary FDS user. Create PROGRAM software bundles on the workstation using the linked workflow; target PROGRAM creation now reports that requirement. ENVIRONMENT stores only a declarative profile. See Desktop usage.

fds burn data BAY04 --label FELIS is the same creation workflow. fds-inspect and fds-eject are static aliases of the corresponding fds commands.

Build a regular image from a prepared directory

On a Linux workstation, these image operations are consolidated into fds-flash create and fds-flash inspect in the fds-tools package. See the current guide. The fds-burn commands below remain available in the target FDS system; they are not a separate workstation installation.

Prepare a directory containing a valid FDS/CARTRIDGE.TOML, plus the class's payload. The manifest format is described in Cartridges. Then:

fds-burn create data data-tree data.img --size-mib 128
fds-burn create environment environment-tree environment.img
fds-burn create system prepared-root system.img
fds inspect image system.img

The output must be outside the source directory, and existing output files are never replaced. SYSTEM requires a complete prepared FDS root, including native init, cartridge management and Dasung; preserve its intended ownership, file modes, capabilities and prebuilt caches. On the build host, the normal supported SYSTEM workflow remains make rootfs PROFILE=cli followed by make system-card. fds format system prepared-root BAY04 combines prepared-root construction with the confirmed write workflow. It does not install packages or change the running read-only SYSTEM.

SYSTEM construction must be able to read every source file, including protected account files, while preserving root ownership and capabilities. Run that construction step from a privileged maintenance session with a correctly prepared tree. The normal FDS console is UID 1000 and does not gain access to protected source files merely by invoking fds-burn. The ordinary user's supported workflow is to burn an already-built SYSTEM image. The VM acceptance test separately exercises privileged SYSTEM creation and ordinary-user confirmed writing, then boots the result.

Dependencies and current evidence

The new static Rust crate uses pinned sha2 0.10.9 for streaming image hashes. Its digest/block-buffer/crypto-common/generic-array/typenum dependencies provide the hashing primitives; cpufeatures selects CPU implementations and version_check is a build helper. These eight additions are locked in Cargo.lock; no glibc, OpenSSL, async runtime or network client is added to an FDS executable. Upstream SHA-2 API.

Filesystem construction uses the already-installed glibc erofs-utils and e2fsprogs; the retained legacy preparation code uses GNU cp from coreutils. These are explicit fds-cli package dependencies, and fds-cartridged depends on fds-cli for its worker. They add no packages to the existing base selection. The static tool creates and verifies GPT itself. A read-only loop inside a private mount namespace lets the worker validate the filesystem and manifest before confirmation. The filesystem checker runs as UID 1000 through a private, already-open read-only device handle; cartridge code is never executed.

The M9 validation report records the actual ARM construction, virtual USB writes, independent GPT/filesystem checks and SYSTEM boot evidence. Writer unit tests also cover source mutation, readback corruption, cancellation and overlapping backup relocation on slightly larger targets. Physical flash behavior and power-loss testing remain deferred.

FDS/OS

Home · Overview · All pages

Start here

Use the computer

Install and maintain

Build and contribute

Home · All pages · Edit the wiki · Source repository

Maintained directly in the fds-os.wiki repository. Historical acceptance applies only to the source and artifacts identified in each record.