Document unified image creation inspection and flashing
@@ -110,6 +110,12 @@ 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](Flashing#create-a-cartridge-image). 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](Developer-Cartridges). Then:
|
||||
|
||||
|
||||
@@ -32,6 +32,13 @@ installed by `make workstation-install`. `make workstation-binaries` preserves
|
||||
the generic Linux build. Stopped emulator directories support a fresh boot while
|
||||
retaining logs, DATA overlays and archived cartridge mappings.
|
||||
|
||||
`fds-flash` consolidates workstation creation, inspection and flashing. It reuses
|
||||
the `fds-burn` library for prepared DATA/ENVIRONMENT/SYSTEM trees, with typed
|
||||
Clap `create` subcommands and native e2fsprogs/erofs-utils. `inspect` handles
|
||||
complete internal and cartridge images without a destination. The Pi's existing
|
||||
`fds-burn` worker and bay-control interface remain in the target package.
|
||||
New PROGRAM creation continues through `fds-cartridge` and installed Void trees.
|
||||
|
||||
`fds-flash` installs complete internal and cartridge GPT images. Its interactive
|
||||
mode requires terminal confirmation; unattended mode binds a specific image
|
||||
SHA-256 and target identity. Installation includes exclusive block access,
|
||||
|
||||
+95
-4
@@ -6,11 +6,16 @@ include_toc: true
|
||||
|
||||
[Home](Home) · [Real hardware](Hardware-Setup) · [Workstation tools](Workstation) · [Release verification](Releases)
|
||||
|
||||
`fds-flash` installs a complete FDS disk image from a Linux workstation. It has
|
||||
`fds-flash` creates, inspects and installs FDS disk images from a Linux workstation. It has
|
||||
an interactive guide and an unattended mode for scripts. It validates the image,
|
||||
checks the destination, writes it, flushes it, reads the written bytes back, and
|
||||
relocates the backup GPT automatically when the destination is larger.
|
||||
You no longer need the manual `dd`, `cmp` and `sfdisk` installation sequence.
|
||||
Cartridge images and the internal disk use the same flashing command. The
|
||||
workstation image operations previously documented as `fds-burn create` and
|
||||
`fds-burn inspect` are now available under `fds-flash`. The workstation package
|
||||
does not install a separate `fds-burn`; the Pi retains that service worker and
|
||||
its bay-control interface.
|
||||
|
||||
## Install the tool
|
||||
|
||||
@@ -30,13 +35,25 @@ make workstation-binaries
|
||||
out/workstation/fds-flash --help
|
||||
```
|
||||
|
||||
Build as an ordinary user. Only physical disk writes require root. The examples
|
||||
Build as an ordinary user. Physical disk writes require root. The examples
|
||||
below use the checkout binary; substitute `fds-flash` after package installation.
|
||||
The flasher adds no crates or external runtime utilities: it uses the existing
|
||||
Inspection and flashing add no crates or external runtime utilities: they use the existing
|
||||
Clap, serde/JSON, SHA-256 and libc dependencies plus Linux block-device APIs.
|
||||
The Python commands in the scripting example only read saved JSON; Python is
|
||||
not required by the installed flasher.
|
||||
|
||||
Image creation uses `e2fsprogs` for DATA and `erofs-utils` for ENVIRONMENT/SYSTEM.
|
||||
These optional package dependencies supply the filesystem builders and checkers:
|
||||
|
||||
```sh
|
||||
sudo pacman -S --needed e2fsprogs erofs-utils
|
||||
```
|
||||
|
||||
`fds-flash create` calls those native utilities in `/usr/bin`; it does not use
|
||||
`fds-cartridge`'s optional Void tool runners. Creating DATA or ENVIRONMENT images
|
||||
from your own files runs as an ordinary user. A prepared SYSTEM root can require
|
||||
privileges to read protected files and preserve its intended ownership.
|
||||
|
||||
## Choose the correct image
|
||||
|
||||
| Image | Destination |
|
||||
@@ -57,6 +74,57 @@ Use an uncompressed, complete FDS GPT disk image. The raw `fds-boot.img` and
|
||||
system images and 4 KiB logical-sector destinations are rejected. A disk must
|
||||
have 512-byte logical sectors and enough space for the complete image.
|
||||
|
||||
## Create a cartridge image
|
||||
|
||||
Creation writes a new regular image file. It does not select or write a disk.
|
||||
Start with a directory containing a valid `FDS/CARTRIDGE.TOML` manifest and the
|
||||
files to include. For example, create a small DATA image:
|
||||
|
||||
```sh
|
||||
mkdir -p out/my-data-tree/FDS
|
||||
cat >out/my-data-tree/FDS/CARTRIDGE.TOML <<'EOF'
|
||||
format = 1
|
||||
[cartridge]
|
||||
id = "my.data"
|
||||
name = "My data"
|
||||
class = "data"
|
||||
version = "1.0"
|
||||
[media]
|
||||
writable = true
|
||||
EOF
|
||||
printf 'Hello from DATA\n' >out/my-data-tree/hello.txt
|
||||
out/workstation/fds-flash create data out/my-data-tree out/my-data.img --size-mib 128
|
||||
out/workstation/fds-flash inspect out/my-data.img
|
||||
sudo ./out/workstation/fds-flash --image out/my-data.img
|
||||
```
|
||||
|
||||
`--size-mib` sets the DATA filesystem size (default 128 MiB, minimum 32 MiB).
|
||||
The complete image is slightly larger because it includes GPT metadata and
|
||||
alignment. Its filesystem root belongs to FDS UID/GID 1000. The output must be
|
||||
outside the source tree and must not already exist.
|
||||
|
||||
For other prepared trees:
|
||||
|
||||
```sh
|
||||
out/workstation/fds-flash create environment environment-tree environment.img
|
||||
out/workstation/fds-flash create system prepared-root system.img
|
||||
```
|
||||
|
||||
The manifest class must match. ENVIRONMENT needs a read-only manifest with an
|
||||
`[activation]` profile; see [the manifest reference](Developer-Cartridges).
|
||||
SYSTEM needs a complete prepared FDS root, including native init, cartridge
|
||||
management and Dasung. Normal OS builds should use `make rootfs PROFILE=cli`
|
||||
and `make system-card PROFILE=cli`; the creation command does not install packages.
|
||||
|
||||
Build new PROGRAM cartridges with [fds-cartridge](Workstation#build-the-example-cartridge),
|
||||
then inspect or flash the resulting complete image with `fds-flash`.
|
||||
`create program` is intentionally unavailable: new software uses installed Void
|
||||
package trees, while existing legacy images remain readable and flashable.
|
||||
|
||||
Append `--json` to any `create` command for a result with `status: "created"`.
|
||||
`inspection` contains the image path, geometry and SHA-256. Progress and utility
|
||||
diagnostics go to stderr; creation failures return a nonzero exit status.
|
||||
|
||||
## Interactive mode
|
||||
|
||||
Keep the Pi powered off while preparing its NVMe. Connect only the intended
|
||||
@@ -99,6 +167,18 @@ alternative disk. Release the intended disk yourself and rerun if it is blocked.
|
||||
|
||||
## Inspect without writing
|
||||
|
||||
Inspect an image without a connected disk or root privileges:
|
||||
|
||||
```sh
|
||||
out/workstation/fds-flash inspect out/fds-internal.img
|
||||
out/workstation/fds-flash inspect out/my-data.img --json
|
||||
```
|
||||
|
||||
This checks the same geometry and basic filesystem signatures as flashing and
|
||||
reports the complete image's SHA-256. JSON uses `status: "inspected"` and the
|
||||
same `inspection` object as creation. It accepts internal and all cartridge
|
||||
image classes. For PROGRAM software contents, also use `fds-cartridge inspect`.
|
||||
|
||||
List physical disks and reasons they are unavailable:
|
||||
|
||||
```sh
|
||||
@@ -188,7 +268,8 @@ the media, and continue with [first boot](Hardware-Setup#6-power-on-and-reach-th
|
||||
|
||||
`--file-target` is only for existing disposable regular files, as an ordinary user.
|
||||
It is never inferred from a path, and root use of this test mode is rejected.
|
||||
`make flash-test` covers the public CLI, interactive terminal confirmation,
|
||||
`make flash-test` requires e2fsprogs and covers DATA creation, independent filesystem
|
||||
readback, inspection without a disk, the public CLI, interactive terminal confirmation,
|
||||
unattended bindings, cancellation, changed inputs, corruption, and exact/larger
|
||||
destinations. `make flash-vm-test` also exercises block-device writes and failures
|
||||
on isolated virtual NVMe/USB disks. These tests do not write host block devices.
|
||||
@@ -220,4 +301,14 @@ record paths and package-validation evidence are recorded locally in
|
||||
`out/logs/flash-workstation-regression.log`. The existing frozen 0.1.0 release
|
||||
was not modified.
|
||||
|
||||
The subsequent workstation-command consolidation was checked with the actual
|
||||
native `fds-flash`: DATA creation, inspection without a target, unattended file
|
||||
flashing, independent ext4 content readback, and rejection of invalid or existing
|
||||
outputs. ENVIRONMENT and prepared SYSTEM creation were checked with real EROFS
|
||||
filesystems and independent extraction, using project-local filesystem utilities
|
||||
inside a private namespace. The small SYSTEM source was an inert test fixture;
|
||||
this check does not establish bootability. The ARM virtual NVMe/USB flashing and
|
||||
failure checks also passed after the shared inspection refactor. Evidence for
|
||||
this revision is recorded in `out/manifests/fds-flash-consolidation-validation.json`.
|
||||
|
||||
Linux interface reference: [kernel block-device ABI](https://www.kernel.org/doc/html/latest/admin-guide/abi-stable.html).
|
||||
|
||||
+13
-4
@@ -27,12 +27,20 @@ install packages. `make workstation-install` builds that package and invokes
|
||||
remove it later with `sudo pacman -R fds-tools`. The exact latest package path is
|
||||
recorded in `out/workstation/package-path.txt`.
|
||||
|
||||
The package requires glibc, GCC runtime libraries and xz. EROFS, bubblewrap and
|
||||
QEMU are optional package dependencies because the tools can use the project-local
|
||||
Void runners instead. For all features using native Arch utilities, install:
|
||||
Use `fds-cartridge` to build PROGRAM software images, `fds-emulator` to run FDS,
|
||||
and `fds-flash` to create DATA/ENVIRONMENT/SYSTEM images from prepared trees,
|
||||
inspect complete images, and write any supported image to a disk. Workstation
|
||||
`fds-burn` image operations are consolidated into `fds-flash`; there is no
|
||||
separate `/usr/bin/fds-burn` in this package. See [image creation and flashing](Flashing).
|
||||
|
||||
The package requires glibc, GCC runtime libraries and xz. Filesystem utilities,
|
||||
bubblewrap and QEMU are optional dependencies for their respective features.
|
||||
`fds-cartridge` and `fds-emulator` can use project-local Void runners;
|
||||
`fds-flash create` requires native filesystem utilities. For all features using
|
||||
native Arch utilities, install:
|
||||
|
||||
```sh
|
||||
sudo pacman -S --needed bubblewrap erofs-utils qemu-system-aarch64 qemu-img
|
||||
sudo pacman -S --needed bubblewrap erofs-utils e2fsprogs qemu-system-aarch64 qemu-img
|
||||
```
|
||||
|
||||
On other Linux distributions, install Rust, a C linker, Make, Python 3 and Git,
|
||||
@@ -51,6 +59,7 @@ prepared Void checkout are still separate source-build prerequisites.
|
||||
| --- | --- |
|
||||
| Prepared writable Void `void-packages` checkout and native XBPS utilities | Build source packages and install their AArch64 runtime dependencies |
|
||||
| `mkfs.erofs`, `fsck.erofs` | Create and inspect read-only payload filesystems |
|
||||
| `mkfs.ext4`, `e2fsck` from e2fsprogs | Create DATA images with `fds-flash create data` |
|
||||
| `bwrap` | Inspect filesystems and install package trees in a user namespace |
|
||||
| `xz` | Read older software cartridges and package/source archives |
|
||||
| `qemu-system-aarch64`, `qemu-img` | Run the emulator and create writable DATA overlays |
|
||||
|
||||
Reference in New Issue
Block a user