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/recovery.md
+6 -37
View File
@@ -1,15 +1,9 @@
# Recovery and rollback
[Documentation index](README.md) · [Boot images](boot.md) · [Media tools](media-tools.md) · [EEPROM](eeprom.md)
[Documentation index](README.md) · [Boot images](developer/boot.md) · [Write cartridges](workstation.md#write-a-cartridge-to-usb) · [EEPROM](eeprom.md)
Recovery is a separate, read-only FDS image. It contains native s6, Bash, GNU
utilities, XBPS, filesystem tools, the static FDS tools, and the base Dasung
controller. It does not need files or programs from a SYSTEM cartridge.
The software workflow is covered by `make recovery-test`; physical Pi recovery remains deferred.
The [complete internal disk](internal-storage.md) includes this recovery image;
its guide separates verified image construction from deferred physical
installation. The build commands below create ordinary files and do not write a
host disk.
FDS recovery is an independent maintenance system on internal storage. It can
inspect a failed SYSTEM, check DATA and help prepare replacement cartridges.
## Build the recovery image
@@ -18,16 +12,8 @@ From the repository root, run these commands sequentially:
```sh
make recovery
make rootfs-test
make recovery-test
```
The full VM test also needs the Pi kernel/initramfs and a known-good CLI SYSTEM
image. On a fresh checkout, build those first with `make rootfs PROFILE=cli`,
`make rootfs-test`, `make initramfs`, and `make system-card PROFILE=cli`, then
run the recovery sequence above. Run builds and VM tests sequentially because
they share the same project-local Void environment.
`make recovery` builds the `recovery` rootfs profile independently, configures all
packages and caches at image construction time, then creates EROFS. Its outputs
are:
@@ -54,9 +40,7 @@ Stage0 can enter recovery in two ways:
Restore normal mode when maintenance is complete.
Stage0 requires exactly one readable `FDS_RECOVERY` partition and mounts it
read-only. It does not silently choose between duplicate partitions. The ARM VM
suite supplies disposable virtual partitions; physical firmware/NVMe/display
behavior must still be checked on the Pi.
read-only. It does not silently choose between duplicate partitions.
The local prompt is:
@@ -94,10 +78,6 @@ inactive SYSTEM mounts read-only under `/run/fds/media/NN`; `fds bay N` reports
the actual path. A bad filesystem or manifest produces an error instead of
running anything from the cartridge.
An empty bay configuration produces `UNCONFIGURED`, not guessed bay numbers.
See [Cartridges](cartridges.md) for calibration. Permanent machine configuration
on `FDS_INTERNAL` is part of the remaining M12 work.
## Check and repair DATA
Start with a read-only check. For example, for DATA in bay 2:
@@ -112,10 +92,6 @@ disk exclusively, verifies GPT and the kernel partition identity, and invokes
`e2fsck -f -n`. It does not repair the filesystem. A clean result leaves DATA
unmounted and reports `SAFE TO REMOVE`.
If DATA was explicitly activated writable, eject that session first. Close any
shell whose current directory is on DATA and any other reader before checking;
an ordinary busy-unmount failure is reported, never bypassed with lazy unmount.
If the check reports problems, review its log and preserve a backup where
possible. Preview the repair with:
@@ -133,13 +109,6 @@ repairs and stops when manual judgement is required. It then flushes the device,
invalidates its block cache, and runs a second `e2fsck -f -n`. Only a successful
verification produces `DATA REPAIRED AND VERIFIED` and `SAFE TO REMOVE`.
The checker uses a temporary kernel loop device backed by the already verified
partition descriptor. This lets `e2fsck` take its own exclusive device claim
while FDS retains the physical whole-disk reservation. The loop is removed
automatically when its last descriptor closes. This uses the existing kernel
loop driver, `libc` crate and base `e2fsprogs`; no new package or Rust dependency
is introduced.
Failed or interrupted checks/repairs retain a quarantine record across cartridge
daemon restarts for the same insertion. They do not inherit an earlier SAFE
status. The checker holds the disk reservation and is killed if its supervising
@@ -175,7 +144,7 @@ fds burn system /run/fds/media/02/fds-system-cli.img BAY04
Use the actual source mount shown by `fds bay 2`. If the destination already
contains a mounted cartridge, run `fds eject 4` first. The burn preview identifies
the source checksum, destination capacity/model/serial and confirmation command.
Follow [Media creation and writing](media-tools.md) for confirmation and status commands.
Follow [Media creation and writing](developer/media-tools.md) for confirmation and status commands.
Completion requires device flush, readback and GPT verification. Recovery uses
the same protected writer as the main system: it refuses mounted destinations,
active root storage and disks containing internal FDS partition names.
@@ -199,7 +168,7 @@ and boot events with checksums. Its output is temporary unless copied to a
healthy DATA cartridge after explicitly activating that DATA with `fds data use N`.
Do not activate the damaged cartridge merely to save a report. Eject writable
DATA after copying, or let `fds poweroff` perform the normal verified shutdown.
See [Shutdown](power.md) when shutdown reports a blocking DATA error.
See [Shutdown](developer/power.md) when shutdown reports a blocking DATA error.
Recovery is independent of SYSTEM, but it still depends on working internal
boot storage, the kernel and firmware. An external rescue medium is required