Understanding FDS/OS

Development reference and historical context. For current operating instructions, use the user manual. Acceptance applies only to the source and artifacts identified in each record.

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.

9.5 KiB Raw Blame History Unescape Escape