FDS/OS 1.0
This commit is contained in:
+143
@@ -0,0 +1,143 @@
|
||||
# FDS Rust tools
|
||||
|
||||
[Documentation index](README.md) · [Implementation ledger](implementation-status.md)
|
||||
|
||||
M3 introduces `fds-common`, the `fds` command, and the `fds-stage0` diagnostic
|
||||
entry point. Both executables cross-build as static-musl AArch64 programs. The
|
||||
normal OS continues to use glibc; no target musl runtime package is added.
|
||||
|
||||
For native Linux software packaging and QEMU hotplug, use `make workstation`
|
||||
and the [workstation guide](workstation.md). Those Clap tools are host binaries;
|
||||
`make tooling` below builds the static ARM runtime tools.
|
||||
|
||||
## Build and test
|
||||
|
||||
After the [workstation setup](getting-started.md):
|
||||
|
||||
```sh
|
||||
make tooling
|
||||
make tooling-test
|
||||
```
|
||||
|
||||
The outputs are `out/fds`, `out/fds-stage0`, `out/fds-boottrace`, `out/fds-cartridged`, `out/fds-profile`, `out/fds-burn`, `out/fds-inspect`, `out/fds-eject`, `out/fds-power` and `out/fds-release`, with hashes and source-input
|
||||
records under `out/manifests/fds-tools*.sha256`. The tests run shared Rust unit
|
||||
tests on x86_64, inspect the ARM ELF files, then execute those actual ARM binaries
|
||||
with the project-local QEMU userspace emulator. No physical monitor or disk is
|
||||
opened by this test.
|
||||
|
||||
The M3 workspace members reuse the already-locked `serde`, `serde_json`,
|
||||
and `toml` dependencies: typed configuration, machine-readable output, and the
|
||||
specified cartridge format. No asynchronous runtime, OpenSSL library, libudev
|
||||
binding, C compiler dependency, or additional native library is introduced.
|
||||
|
||||
All Rust command-line interfaces use **Clap**, with typed commands, generated
|
||||
help, and argument validation before execution. The workspace shares the Clap
|
||||
dependency already used by Dasung; `Cargo.lock` pins version 4.6.7 and its derive
|
||||
support. It adds no shared runtime library. The dependency-free smoketest has no
|
||||
command-line interface. Test helpers also use Clap and build through Cargo.
|
||||
The [migration validation](clap-validation.md) records parser, full-image, VM
|
||||
and startup comparison evidence.
|
||||
|
||||
M9 adds media creation and confirmed writes; see [Media tools](media-tools.md)
|
||||
for its current validation state and the new SHA-256 dependency.
|
||||
M12 adds the base `fds-release` signature verifier and a workstation signer;
|
||||
see [Release signatures](releases.md) for key handling, verification and the
|
||||
Ed25519 dependency rationale.
|
||||
|
||||
## Find commands and options
|
||||
|
||||
Run these inside FDS (or prefix them with the emulator invocation below on the
|
||||
workstation):
|
||||
|
||||
```sh
|
||||
fds --help
|
||||
fds help format
|
||||
fds format data --help
|
||||
fds recovery repair --help
|
||||
fds machine --help
|
||||
fds-burn create --help
|
||||
fds-release verify --help
|
||||
```
|
||||
|
||||
Help is specific to the selected command. `-h` and `--help` print help without
|
||||
performing an operation; `--version` reports the executable version. Missing,
|
||||
unknown, duplicated, and conflicting arguments produce a usage error with exit
|
||||
status 2. Operational failures still come from the existing FDS safety checks.
|
||||
|
||||
`fds --json bays` and `fds bays --json` are equivalent. The installed aliases
|
||||
`fds-inspect`, `fds-eject`, and `fds-power` have their own generated help and
|
||||
accept the same relevant arguments as `fds inspect`, `fds eject`, and `fds power`.
|
||||
Bay selectors accept `1` through `12`, including the `BAY1` through `BAY12` form.
|
||||
|
||||
Use `--` to separate a managed program from FDS options:
|
||||
|
||||
```sh
|
||||
fds run 2 -- editor --help
|
||||
```
|
||||
|
||||
Here `--help` belongs to `editor`. Every argument after the separator is passed
|
||||
to the managed program unchanged, including `--json` and another `--`.
|
||||
Media writes still require the exact confirmation associated with the current
|
||||
cartridge insertion and image; accepting CLI syntax never authorizes a write.
|
||||
|
||||
## Inspect identity and cartridge metadata
|
||||
|
||||
Run the ARM programs through the existing container:
|
||||
|
||||
```sh
|
||||
./tools/in-void qemu-aarch64 "$PWD/out/fds" info
|
||||
./tools/in-void qemu-aarch64 "$PWD/out/fds" --json info
|
||||
./tools/in-void qemu-aarch64 "$PWD/out/fds" inspect \
|
||||
"$PWD/tests/fixtures/manifests/windowmaker.toml"
|
||||
```
|
||||
|
||||
`info` reports tool version, build target, kernel and the visible PID 1. In
|
||||
userspace emulation those kernel/process values describe the execution environment,
|
||||
not a booted FDS machine. Full-system boot remains a separate test.
|
||||
|
||||
Manifest inspection reads at most 64 KiB and rejects unknown keys, unsupported
|
||||
format versions, unsafe identifiers, terminal control characters, writable
|
||||
SYSTEM/PROGRAM/ENVIRONMENT media, and activation actions outside ENVIRONMENT.
|
||||
A profile name is declarative; validation does not execute or activate it.
|
||||
DATA requires writable media. `--json` gives parsed, validated metadata.
|
||||
|
||||
Unknown commands and invalid data return nonzero. Bay state and eject now come from the base cartridge daemon; see
|
||||
[Cartridge usage](cartridges.md) for available operations and remaining milestones.
|
||||
|
||||
## Stage-0 diagnostics
|
||||
|
||||
```sh
|
||||
./tools/in-void qemu-aarch64 "$PWD/out/fds-stage0" --help
|
||||
./tools/in-void qemu-aarch64 "$PWD/out/fds-stage0" --check-cmdline /path/to/cmdline
|
||||
```
|
||||
|
||||
Supported FDS kernel options are `fds.boot=normal|recovery` and `fds.debug=0|1`.
|
||||
Normal boot selects GPT `PARTNAME=FDS_SYSTEM`; recovery selects `FDS_RECOVERY`.
|
||||
Duplicate/unknown FDS options are rejected, while unrelated kernel options are
|
||||
left to the kernel. Read-only `--probe SYSFS_ROOT [FDS_SYSTEM|FDS_RECOVERY]`
|
||||
reports missing, unique, or ambiguous partitions from kernel-reported identities.
|
||||
It never chooses the first of multiple SYSTEMs and does not infer identity from
|
||||
`sdX` order.
|
||||
|
||||
With no arguments, stage0 now performs the [M4 boot path](boot.md) as root PID 1
|
||||
in the initramfs. It refuses that operation in an ordinary shell. The full-system
|
||||
boot matrix exercises root handoff; diagnostics alone do not establish a boot.
|
||||
M4 reuses the locked `libc` crate for direct Linux syscalls and adds no shared
|
||||
runtime dependency. The [M2 VM](init.md) remains a separate direct-root fixture.
|
||||
|
||||
## Boot-event reporting
|
||||
|
||||
M5 adds `fds boot-profile` (or `fds --json boot-profile`) for the current boot.
|
||||
`fds-boottrace` adopts stage0 events into volatile runtime storage and records
|
||||
the first console readiness; a restarted shell does not replace that timestamp.
|
||||
Missing events remain absent. See [Performance](performance.md) for event
|
||||
boundaries, saved-report comparison, and the greater-than-100 ms regression rule.
|
||||
|
||||
## Desktop, applications, and Ethernet
|
||||
|
||||
M8 adds `fds profiles`, `fds profile activate windowmaker`, `fds profile deactivate`,
|
||||
`fds network on|off`, and PROGRAM launches with `fds run N -- executable-name`.
|
||||
The standalone `fds-profile` is also a static ARM executable. Its root-only s6
|
||||
helpers create the authenticated X server and supervise the unprivileged desktop
|
||||
session; ordinary callers use the existing peer-checked control socket.
|
||||
See [Desktop and programs](desktop.md) for a complete usage walkthrough.
|
||||
Reference in New Issue
Block a user