felis/fds-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
felis
2026-09-22 13:23:34 +08:00
parent 99bc3d15c5
commit 8a4788fca8
126 changed files with 7198 additions and 2425 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cartridges.md
+71 -170
View File
@@ -1,197 +1,98 @@
# Using cartridges and configuring bays
# Use cartridges and run programs
[Documentation index](README.md) · [Boot images](boot.md) · [Services](services.md)
A bay number identifies a physical slot, from `01` through `12`. It stays tied
to the slot rather than the order in which Linux discovers USB disks.
M6 adds the base `fds-cartridged` service, twelve bay states, USB hardware
recognition, strict metadata inspection, read-only storage mounts and eject.
Its [ARM VM acceptance checks passed](m6-validation.md). [Writable DATA integration](data.md) has passed M7 software acceptance;
[desktop/program activation](desktop.md) passed M8 and [media creation tools](media-tools.md)
passed M9 software acceptance. [M10 ordered shutdown](power.md) has passed software acceptance.
| Cartridge | Role |
| --- | --- |
| SYSTEM | Supplies the read-only operating system used at boot |
| PROGRAM | Supplies applications and their runtime dependencies |
| DATA | Stores your writable files at `/data` |
| ENVIRONMENT | Requests an installed desktop profile, such as WindowMaker |
## Inspect the current machine
## Inspect a bay
At the FDS console:
Insert the cartridge, then run:
```sh
fds bays
fds bay 3
fds cartridge 3
fds --json bays
fds bay 01
```
The ordinary `fds` user can use these commands. `bays` shows all twelve bays,
including empty and unconfigured ones. `cartridge` includes validated metadata
and the current mount path. `--json` exposes a versioned machine-readable report.
`fds rescan` explicitly refreshes inventory; normal insert/remove events trigger
refresh automatically. The console does not wait for the inventory scan.
USB discovery takes place asynchronously. `fds bay` shows its state, identity,
mount location, running process count and software catalogue. `fds --json bay 01`
returns structured details, including command aliases. `fds rescan` refreshes
the inventory. No application starts merely because a PROGRAM cartridge is inserted.
| State | Meaning and next action |
| --- | --- |
| UNCONFIGURED | No measured controller/port mapping exists for this bay |
| EMPTY | Configured bay with no detected USB device |
| HARDWARE | USB device without storage; catalog name or VID/PID is shown |
| UNRECOGNIZED STORAGE | Storage exists but no named FDS partition is available |
| MOUNTED READ ONLY | Manifest validated; filesystem available at the displayed path |
| MOUNTED READ WRITE | Active DATA is writable at `/data`; eject before removal |
| PROTECTED | The active SYSTEM root; eject is refused |
| AMBIGUOUS | Multiple devices or named partitions match; nothing is selected arbitrarily |
| ERROR | Inspection, mounting or metadata validation failed; read the diagnostic |
| SAFE | The requested unmount succeeded; remove the cartridge |
| EMPTY | No cartridge is detected |
| MOUNTED READ ONLY | Contents are available; PROGRAM commands can run |
| MOUNTED READ WRITE | DATA is active at `/data` |
| SAFE | Storage is released; remove the cartridge |
| PROTECTED | This cartridge supplies the running SYSTEM; shut down before removal |
| UNCONFIGURED | The physical slot needs a bay mapping |
| ERROR / AMBIGUOUS | Read the detail; correct the media or mapping before use |
An unrecognized storage state may briefly appear while the kernel discovers its
partitions. It is not permission to remove a device being used elsewhere.
Errors and ambiguous media never produce SAFE. An additional mount of the same filesystem also blocks managed eject until
it is unmounted.
## Run a software command
## Calibrate the physical bay map
The shipped `/etc/fds/bays.toml` is deliberately empty: no Pi bay wiring has yet
been measured. This produces UNCONFIGURED states, not invented assignments.
1. On the assembled machine, insert one known USB device into one physical bay.
2. Run `fds topology`. This diagnostic explicitly shows controller/port paths;
ordinary bay commands omit those implementation details.
3. Record that path and repeat for each bay. Test both USB 2 and USB 3 devices,
because their companion root hubs can have different logical port paths.
4. Put the measured map in your machine configuration directory and build the
[internal image](internal-storage.md), or use `fds machine install DIRECTORY`
from recovery and reboot. Machine settings persist independently of SYSTEM.
The packaged `/etc/fds/` files are fallback defaults for missing/invalid internal
storage; `fds machine status` shows which source is active.
5. Verify all twelve devices together, in different insertion orders and after
reboot. That physical acceptance remains deferred.
A **syntax example only**, using identities that must be replaced by observations:
```toml
[front]
hub = "platform/example-controller:usb2/1"
[front.ports]
1 = 1
2 = 2
3 = 3
4 = 4
5 = 5
6 = 6
[front_superspeed]
hub = "platform/example-controller:usb3/1"
[front_superspeed.ports]
1 = 1
2 = 2
3 = 3
4 = 4
5 = 5
6 = 6
```
`hub` names the controller and parent port chain. Its numbered `ports` map the
next downstream port to a bay number from 1 through 12. Additional groups can
map the rear hub. Explicit USB 2/3 aliases may refer to the same bay; duplicate
ports, overlapping parent/child mappings, and duplicate bays within one hub are
rejected. If two devices simultaneously match aliases for one bay, it becomes
AMBIGUOUS. A hub inserted into a cartridge bay with multiple downstream devices
also needs an explicit future composite-device policy; M6 refuses to guess.
The identity excludes the Linux USB bus number and `/dev/sdX` enumeration order.
It includes the controller's sysfs path, USB protocol generation and port chain.
Moving a hub to another controller or changing wiring requires recalibration.
## Storage formats and metadata
| Class | GPT partition name | Filesystem and current behavior |
| --- | --- | --- |
| SYSTEM | FDS_SYSTEM | EROFS; current root is protected, additional media read-only |
| DATA | FDS_DATA | ext4; inspected read-only first, then activated at `/data` under the M7 policy |
| PROGRAM | FDS_METADATA + FDS_PAYLOAD02… | Metadata and xz bundles in `1+m` EROFS partitions; see [software format](software-format.md) |
| Legacy PROGRAM | FDS_PROGRAM | Existing single EROFS application tree; still readable |
| ENVIRONMENT | FDS_ENVIRONMENT | EROFS; declarative selection of a trusted built-in profile |
| UTILITY | FDS_UTILITY | EROFS; inspection only, no automatic actions |
| HARDWARE | None required | VID/PID, optional serial, device/interface class and bay |
Storage contains `/FDS/CARTRIDGE.TOML`. For example:
```toml
format = 1
[cartridge]
id = "fds.windowmaker"
name = "WINDOW SYSTEM"
class = "environment"
version = "0.1"
[media]
writable = false
[activation]
profile = "windowmaker"
```
The manifest class must match the GPT partition name. SYSTEM, PROGRAM and
ENVIRONMENT are read-only; DATA declares writable media during the initial read-only inspection. Unknown keys, root commands, unsafe identifiers, control
characters, symlink metadata and nonregular metadata files are rejected.
The parser accepts at most 64 KiB. No `/FDS/autorun.sh` is run.
Inspect a standalone manifest with `fds inspect /path/to/CARTRIDGE.TOML`.
For mounted storage, `fds cartridge N` reports the daemon's validated copy.
Media is inspected in a root-only staging directory, then published at
`/run/fds/media/NN` after validation, with nodev, nosuid and noexec. Device
major/minor and kernel disk sequence are checked before mounting an opened
block-device descriptor, preventing stale enumeration names from selecting a
replacement disk.
## Eject a mounted cartridge
For the included hello/report cartridge:
```sh
fds eject 2
hello 'Hello from my cartridge'
report
fds run 01 -- demo.hello:hello 'Hello from my cartridge'
```
Leave any shell working directory inside that cartridge and close files first.
SAFE is emitted only after an ordinary unmount succeeds. Busy mounts return an
error; forced or lazy unmount is never used to declare safe removal. Once SAFE,
the daemon keeps that insertion unmounted until removal and reinsertion, including
across a service restart. Its root-owned volatile marker is tied to the kernel
disk sequence, so a replacement disk is not mistaken for ejected media.
The active SYSTEM cannot be ejected. Swap SYSTEM only after shutting down.
Direct commands run in the foreground with your terminal, input/output streams,
arguments, working directory and exit code. Pipes and redirection work normally.
`fds run` starts a managed background program and prints its PID; its output is
written to `/run/log/cartridged/current`. Both forms run as the ordinary FDS user
and are tracked for cartridge removal.
Pulling a mounted cartridge without eject is surprise removal. The daemon clears
its inventory and detaches a vanished read-only mount where needed; that cleanup
is not a successful eject. [M7 DATA handling](data.md) extends ejection to writable DATA, consumer
tracking and syncfs. The temporary `/home/fds` remains usable without DATA and is lost at
power-off.
New cartridges run directly from read-only payload partitions. They require no
program extraction or compilation on FDS. The stable `/run/fds/bin` directory is
already in the console and terminal PATH, so existing shells see inserted commands.
## Hardware recognition
If cartridges export the same command name, the lowest numbered bay wins.
Within a bay, the first software selector in lexical order wins. System commands
appear earlier in PATH and retain their usual meanings. To select a specific
cartridge command, use its qualified alias:
Edit `packages/fds-cartridged/files/hardware-catalog.toml`, then rebuild SYSTEM.
Entries name devices, never executable actions:
```toml
[[device]]
name = "MY SERIAL ADAPTER"
vendor = "1234"
product = "5678"
# Optional exact restrictions:
serial = "UNIT-1"
class = "02"
```sh
b01:demo.hello:hello 'Explicit bay and software'
fds run 01 -- demo.hello:hello
```
Replace these example IDs with observed values. Device or interface class may
match `class`. Multiple matching catalog entries produce an error; unknown
hardware remains identified by VID/PID without being mistaken for empty media.
Dasung control remains in the independent base monitor service.
Legacy PROGRAM media uses `b01:COMMAND` for a qualified direct alias. Commands
are removed on eject/unplug; a shared name falls back to the next available bay.
After the final cartridge is removed, a shell may remember the old executable
path; `hash -r` clears Bash's command cache.
## Implementation and diagnostics
## Eject safely
The daemon subscribes to kernel USB/block events before taking its first snapshot.
A receive-buffer overflow causes a fresh snapshot. IPC uses a bounded Unix socket
at `/run/fds/control.sock`, mode 0660 and group `fds`, with peer UID checks for
root and the ordinary FDS user. Slow clients have individual deadlines and do not
block other clients. No asynchronous runtime or new external Rust dependency is
introduced: the existing std, libc, serde, serde_json and toml components suffice.
```sh
cd "$HOME"
fds eject 01
fds bay 01
```
Root diagnostics: `s6-svstat /run/service/cartridged` and
`cat /run/log/cartridged/current`. Logs are bounded and volatile. Restart through
`s6-rc -l /run/s6-rc -d change cartridged`, then the corresponding `-u` command.
Close users of cartridge mounts first; restart cleanup refuses busy leftovers.
Eject stops managed programs, flushes writable storage and releases its mounts.
Remove the cartridge after **SAFE** is reported. If eject fails, close files,
shells or extra mounts using that cartridge and retry. Never treat a timeout as
permission to pull writable media. Use `fds poweroff` to stop the whole computer;
swap the running SYSTEM only after shutdown.
On the build host, `make cartridge-test` runs fixtures and full virtual USB tests.
These exercise actual kernel events and mounts but cannot establish physical
wiring, USB power stability, or Pi port behavior. M11 expands to twelve-device
stress, and physical calibration must be recorded separately.
The [control panel](desktop.md) provides the same safe-eject action. For writable
storage behavior, see [DATA and files](data.md).
## Configure physical bay numbering
Run `fds topology` with one identifiable USB device inserted in each slot in
turn. Record the controller/hub topology for both USB 2 and USB 3 connections,
then map those stable identities in the machine's `bays.toml`. Do not map
`/dev/sda` names or enumeration order. The emulator supplies its own known map.
Use [machine settings](internal-storage.md) to validate, export and install the
configuration. The detailed wiring/calibration procedure is in the
[hardware engineering reference](developer/cartridges.md).