FDS/OS 1.0
This commit is contained in:
@@ -0,0 +1,167 @@
|
||||
# Understanding FDS/OS
|
||||
|
||||
[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.
|
||||
Reference in New Issue
Block a user