171 lines
9.5 KiB
Markdown
171 lines
9.5 KiB
Markdown
# Understanding FDS/OS
|
||
|
||
Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
|
||
|
||
|
||
[Documentation index](README.md) · [Roadmap](roadmap.md) · [Glossary](glossary.md)
|
||
|
||
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](getting-started.md) and [Boot images](boot.md) to try the VM.
|
||
|
||
## Three things to keep separate
|
||
|
||
1. **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.
|
||
2. **The machine firmware layer** lives on the Pi's internal NVMe. It supplies the
|
||
kernel, early boot program, recovery environment, and hardware configuration.
|
||
3. **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.
|
||
|
||
```text
|
||
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](cartridges.md).
|
||
|
||
## 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](packages.md).
|
||
|
||
## 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](workstation.md) and
|
||
[format contract](software-format.md).
|
||
|
||
## 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](internal-storage.md).
|
||
|
||
| 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](boot.md) for the sequence, [Services](services.md) for responsibilities,
|
||
and [Performance](performance.md) 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](m12-validation.md). The
|
||
independent [recovery environment](recovery.md) 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](boot.md) for the current builders and their acceptance boundary.
|
||
See [M1 rootfs](rootfs.md) to use the current filesystem archive. Consult the [roadmap](roadmap.md) for acceptance
|
||
boundaries and the [master plan](master-plan.md) for the complete specification.
|