# 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.