61 lines
3.8 KiB
Markdown
61 lines
3.8 KiB
Markdown
# Workstation emulator and software cartridges
|
|
|
|
Software implementation and acceptance are complete; see the
|
|
[acceptance record](workstation-validation.md) and [user guide](workstation.md).
|
|
This follow-up extends the accepted 0.1.0 checkpoint. That signed release remains
|
|
unchanged and does not contain the new format or emulator interface. Physical
|
|
hardware acceptance remains deferred.
|
|
|
|
## Required result
|
|
|
|
- A Linux workstation CLI boots the real FDS kernel, initramfs and SYSTEM image
|
|
with QEMU, exposes its console, and controls twelve virtual USB cartridge bays.
|
|
- Cartridge image insertion and removal use QMP USB hotplug. Safe eject asks the
|
|
guest to release the cartridge; forced removal explicitly simulates pulling it.
|
|
- Software cartridges use GPT with exactly `1 + m` partitions. Partition 1 is
|
|
`FDS_METADATA`; partitions 2 through `m + 1` are `FDS_PAYLOAD02`, and so on.
|
|
All are read-only EROFS containers. This permits multiple software archives
|
|
in one partition without inventing a raw-partition archive container format.
|
|
- Metadata includes the cartridge identity and a catalogue locating every
|
|
software bundle, its version, architecture, commands, lengths and SHA-256.
|
|
Each software payload is an xz-compressed tarball, stored as
|
|
`bundles/<software-id>.tar.xz` in its declared payload partition.
|
|
- Workstation tools build software from explicit trusted recipes, package the
|
|
resulting trees, construct and verify a complete disk image, then separately
|
|
preview/confirm a whole-USB write and verify its readback. Building must not
|
|
depend on running on the Pi or on an Arch-specific container.
|
|
- The guest recognizes this layout, reports its software catalogue, and runs a
|
|
selected software command as the ordinary user. Archives never run build hooks
|
|
on the guest. Runtime extraction is bounded, verified and temporary; eject
|
|
and surprise removal stop consumers and release every associated resource.
|
|
- SYSTEM and writable DATA retain their boot/data layouts. Legacy PROGRAM
|
|
reading may remain for existing images, but newly built software cartridges
|
|
use the metadata-first multi-partition format.
|
|
|
|
## Acceptance gates
|
|
|
|
1. Typed Clap host CLIs, actionable help and Linux prerequisite diagnostics.
|
|
2. Real workstation builds of at least two software programs, including an
|
|
AArch64 executable; archive inspection and independent xz/tar checks.
|
|
3. `1 + m` images with multiple software packages sharing a partition as well
|
|
as packages in separate partitions; independent GPT/filesystem inspection.
|
|
4. Negative checks for overlapping/corrupt GPT, wrong catalogue mappings,
|
|
archive corruption, unsupported architecture, unsafe paths/types and size
|
|
limits. Existing image/write rejection tests remain passing.
|
|
5. Complete-image write/readback using disposable regular files, including a
|
|
larger target and confirmation/source/target-change rejection. Actual USB
|
|
writes are deferred until the user selects physical hardware.
|
|
6. Real FDS boot under the public emulator, insert, catalogue, run, safe eject,
|
|
reinsert, forced removal during execution, and cleanup/restart behavior.
|
|
Every software partition must be exercised, not just the first payload.
|
|
7. Required rootfs/native-init regression and relevant DATA, PROGRAM, media and
|
|
shutdown checks; English installation, usage, troubleshooting and format docs.
|
|
|
|
The QMP implementation follows the [QEMU reference](https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html),
|
|
including waiting for completed device deletion before releasing block nodes.
|
|
The Rust `tar` library supplies archive entry decoding; FDS imposes stricter
|
|
path, entry-type and size rules instead of trusting an archive's ownership or
|
|
permissions. The existing `xz` utility supplies streaming compression and
|
|
decompression with a memory limit. QEMU is host-only; no emulator or software
|
|
build daemon is added to the Pi boot graph.
|