9.3 KiB
Understanding FDS/OS
Documentation index · Roadmap · Glossary
FDS/OS is designed for a Raspberry Pi 5 portable computer whose operating system, user data, applications, and optional environments can be carried on removable cartridges. Its central design question is: what must stay with the machine, and what should move with the user?
Status: M0–M12 software checks cover the cross-build, configured ARM rootfs, native init, Pi kernel/initramfs/SYSTEM images, ordinary-user console, cartridge management, writable DATA, desktop/network activation and verified media writing. Ordered shutdown, twelve-device virtual stress and independent recovery have passed software acceptance. M12 internal storage, development tools and signature verification have also passed software checks. The signed local 0.1.0 release passed two complete offline builds and archive verification. Physical Pi boot and wiring remain deferred. Use Your first build and Boot images to try the VM.
Three things to keep separate
- The build workstation is an x86_64 Arch Linux computer. It downloads tools, compiles ARM software, checks artifacts, assembles the rootfs, and boots the ARM VM.
- The machine firmware layer lives on the Pi's internal NVMe. It supplies the kernel, early boot program, recovery environment, and hardware configuration.
- The removable operating environment comes from cartridges. SYSTEM supplies the OS root filesystem; DATA supplies persistent user files; other cartridges supply programs, configuration, or physical USB hardware.
Build workstation
Arch x86_64
├── Void build container → aarch64 glibc packages
└── Rust toolchain → static AArch64 FDS executables
│
└── Pi kernel + initramfs + SYSTEM → ARM VM checks
Pi 5 machine (planned)
Internal NVMe Removable bays
├── FDS_BOOT ───────────────→ SYSTEM: read-only OS
├── FDS_RECOVERY DATA: user files
└── FDS_INTERNAL PROGRAM / ENVIRONMENT / hardware
machine configuration
The Void build container on the workstation is not the Pi's root filesystem. It may contain build dependencies that must never appear in the final FDS image. Likewise, a successful ARM package build does not prove that a Pi can boot it.
Why cartridges change the operating model
A conventional writable root filesystem combines the installed OS, local changes, and often user data on one disk. FDS separates their lifetimes:
- A SYSTEM image is built and validated as a unit. Updating means preparing and swapping to a new SYSTEM cartridge; retaining the previous one enables rollback.
- A DATA cartridge follows the user. With no DATA cartridge, the home is temporary memory-backed storage, so it does not survive power loss.
- A PROGRAM cartridge supplies a self-contained application image. It does not install arbitrary files into SYSTEM.
- An ENVIRONMENT cartridge selects a known configuration such as WindowMaker. In version 1, the desktop software itself is already present in SYSTEM.
This requires explicit safe-eject behavior: removable does not mean safe to pull while an application is writing. See Cartridges.
Two library strategies
Both software groups target Linux on AArch64. They differ in how they obtain the C runtime and other libraries, not in which processor runs them.
| Software group | Build target | Runtime approach | Reason |
|---|---|---|---|
| Ordinary Linux packages | Void aarch64 |
glibc, usually shared libraries | Compatibility with the GNU userland, Xorg, WindowMaker, compilers, and third-party packages |
| FDS-owned control tools | Rust aarch64-unknown-linux-musl |
Static musl by default | Early boot and control programs can run without the installed glibc loader or version |
M0 demonstrates these with GNU hello and fds-smoketest, respectively. A static
FDS executable still needs a compatible Linux kernel; static linkage does not
turn it into firmware or a standalone OS. Future dependencies using C/C++ FFI
will need their own musl cross-build assessment.
The project does not switch the whole distribution to musl. XBPS target packages
remain aarch64, not aarch64-musl. The downloaded host XBPS tools happen to
be static musl for x86_64 so they can run on Arch; their libc is independent of
the target package ABI. See Packages.
Workstation software and emulation
Native Linux fds-cartridge builds software from trusted recipes, packages xz
tarballs, and creates a complete GPT image with metadata partition 1 plus payload
partitions. It verifies that image before a separately confirmed whole-USB write.
Native fds-emulator boots the FDS kernel/initramfs/SYSTEM in QEMU and exposes
twelve virtual USB bays. Writable DATA uses separate overlays; source images
stay unchanged. These tools are host programs, independent of the target's ABI.
The guest performs bounded verification and temporary extraction, then runs a selected software command as UID 1000. It does not compile software or run installation hooks from cartridges. See the walkthrough and format contract.
Storage and writable state
M4 builds the actual FAT32 boot partition and GPT/EROFS SYSTEM cartridge. M5 provides the temporary home. M6 adds managed read-only cartridge mounts. The M12 internal BOOT/RECOVERY/INTERNAL builder and persistent settings are described in Internal storage.
| Location | Intended content | Write policy |
|---|---|---|
Internal FDS_BOOT (FAT32) |
Pi boot files, kernel, DTBs, initramfs | Managed machine boot content |
Internal FDS_RECOVERY (EROFS) |
Independent recovery OS | Read-only recovery image |
Internal FDS_INTERNAL (ext4) |
Bay map, hardware configuration, diagnostics | Persistent machine state; no ordinary user files |
Cartridge FDS_SYSTEM (EROFS) |
OS root filesystem | Read-only; replace image instead of in-place updates |
Software FDS_METADATA + FDS_PAYLOAD02… (EROFS) |
Catalogue and xz software archives | Read-only; extracted executable caches are temporary |
Cartridge FDS_DATA (ext4) |
User home and/or /data |
Persistent user writes |
/run, /tmp, /var/tmp, /var/log |
Runtime state, temporary files, logs | tmpfs; volatile |
| Home without DATA | Temporary user session | tmpfs; volatile |
Writable DATA uses /data; /home/fds stays temporary.
The table describes the final storage roles. Use the image builders rather than
applying this layout to an existing workstation disk.
Boot and service responsibilities
The Pi boots its kernel and small initramfs from internal NVMe. A static Rust
fds-stage0 locates a partition named FDS_SYSTEM, mounts its EROFS filesystem,
and transfers control to native s6 in the new root.
The console should become usable as soon as its own prerequisites are ready.
It must not wait for the network, desktop, all 12 USB devices, or a complete
cartridge catalog. fds-cartridged handles hotplug, physical bay mapping and
metadata, and activates known desktop profiles from validated ENVIRONMENT media.
See Boot for the sequence, Services for responsibilities, and Performance for targets and how they will be measured.
Trust and ownership boundaries
Cartridge metadata describes a cartridge; it is not permission to run supplied scripts as root. Known profiles and hardware mappings belong to the OS. Ordinary programs should run with ordinary user privileges. An unrecognized device should not become trusted merely because it appears in a USB bay.
Package customization belongs in project-owned packages/fds-* overlays.
Upstream Void tracked files remain unchanged at a recorded source commit.
M0 checks this boundary automatically. Source pins and artifact hashes improve
traceability. Exact selected input snapshots, offline reproduction and local
release signing have passed M12 acceptance. The
independent recovery environment is implemented and tested.
Where implementation starts and stops
Today the active sources also include rust/dasungd/, its package overlay, and
s6/source/ for the base monitor service. make dasung builds its static ARM
executable, XBPS package, and a service database for validation. The monitor
service is independent of GUI and cartridge profiles. M2 includes these in a rootfs with native s6 init and a generic ARM VM test.
M3 adds the FDS CLI and shared Rust contracts. M4 adds the Pi kernel, Rust
initramfs, GPT/EROFS SYSTEM and FAT32 boot partition. Its actual stage0 handoff
and media insertion/recovery paths run in a generic ARM VM. Physical Pi
validation remains deferred. M5 adds the ordinary console and boot tracing; M6
adds the cartridge daemon. M7–M11 add writable DATA, desktop/network profiles,
verified media writing, ordered shutdown and virtual USB stress. M12 adds recovery,
internal machine storage and release preparation.
Use Boot images for the current builders and their acceptance boundary. See M1 rootfs to use the current filesystem archive. Consult the roadmap for acceptance boundaries and the master plan for the complete specification.