update docs
This commit is contained in:
@@ -0,0 +1,158 @@
|
||||
# Cartridge image tools
|
||||
|
||||
Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
|
||||
|
||||
|
||||
[Documentation index](README.md) · [Cartridge usage](cartridges.md)
|
||||
|
||||
For new software cartridges, use the [Linux workstation workflow](workstation.md):
|
||||
`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](m9-validation.md).
|
||||
Images built before M9 do not contain these commands. Build a new image to use
|
||||
them:
|
||||
|
||||
```sh
|
||||
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](getting-started.md). 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](cartridges.md).
|
||||
Unconfigured or ambiguous bays are refused. At the FDS console, inspect the target and eject any existing filesystem first:
|
||||
|
||||
```sh
|
||||
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:
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
```sh
|
||||
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](desktop.md).
|
||||
|
||||
`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
|
||||
|
||||
Prepare a directory containing a valid `FDS/CARTRIDGE.TOML`, plus the class's
|
||||
payload. The manifest format is described in [Cartridges](cartridges.md). Then:
|
||||
|
||||
```sh
|
||||
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](https://docs.rs/sha2/0.10.9/sha2/).
|
||||
|
||||
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](m9-validation.md) 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.
|
||||
Reference in New Issue
Block a user