felis/fds-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
felis
2026-09-22 13:23:34 +08:00
parent 99bc3d15c5
commit 8a4788fca8
126 changed files with 7198 additions and 2425 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/internal-storage.md
+10 -43
View File
@@ -1,11 +1,11 @@
# Internal storage and machine settings
[Documentation index](README.md) · [Boot images](boot.md) · [Recovery](recovery.md)
[Documentation index](README.md) · [Boot images](developer/boot.md) · [Recovery](recovery.md)
The internal NVMe supplies the Pi's firmware boot files, independent recovery,
and machine settings. SYSTEM remains a separate removable cartridge. Ordinary
user files belong on DATA, not internal storage. No physical disk is written by
any build command below; Pi/NVMe boot and power-loss tests remain deferred.
Internal storage contains boot files, an independent recovery system and
persistent machine settings. The operating system itself lives on a removable
SYSTEM cartridge. This guide covers preparing the internal disk and updating
its settings from recovery.
## Build the complete disk image
@@ -42,17 +42,7 @@ For a 2 GiB recovery allocation or larger settings partition:
./image/build-internal --recovery-mib 2048 --internal-mib 512
```
Output directories supplied with `--output-directory` must already exist and be
empty. The builder accepts ordinary image files, never a host block-device
output. Final hardware provisioning and identity checks belong to the physical
acceptance procedure; do not confuse a partition payload with the complete disk.
## Install the internal disk when hardware is available
This is a **deferred physical procedure**. The image and virtual NVMe workflow
are software-tested; writing and booting the user's actual NVMe still require
the hardware. Installation erases the selected disk, including any existing
machine settings. Retain backups before replacing an existing installation.
## Install the internal disk
Use an NVMe enclosure or another Linux machine that can access the target drive
while the Pi is off. First verify a downloaded release using a separately trusted
@@ -132,12 +122,7 @@ alternative complete GPT images, each containing one `FDS_SYSTEM` partition.
Readback and backup-GPT relocation apply to this disk too. Check its partition
label, safely disconnect it, and insert exactly one SYSTEM cartridge in the Pi
before normal boot. Subsequent cartridge creation and updates can use FDS's
confirmed [media workflow](media-tools.md) after bay calibration.
On the first physical boot, check `fds info`, `fds machine status`, and
`fds bays`. The supplied bay map is empty until calibration. Follow
[physical acceptance](stress-testing.md) to measure ports, test the Dasung
display, and record actual boot/shutdown behavior before relying on the machine.
confirmed [media workflow](developer/media-tools.md) after bay calibration.
## Configure the machine before building
@@ -149,9 +134,9 @@ Copy `config/machine/` to your own directory. It contains three files:
- `hardware-catalog.toml`: optional USB identification names using the same schema
as the base catalog. Entries are data and cannot run commands.
The supplied bay map is deliberately empty because the physical wiring has not
been measured. Do not invent Pi USB paths. USB 2 and USB 3 companion ports need
explicit aliases for the same bay.
The supplied bay map is empty. Record actual controller/port identities for
each physical slot before installing settings. USB 2 and USB 3 companion ports
need explicit aliases for the same bay.
```sh
cp -a config/machine out/my-machine
@@ -253,21 +238,3 @@ diagnostic snapshot, including metadata already inspected during this boot.
Retrieve it with `fds machine fetch cartridges-first.json /tmp/saved-inventory.json`.
The daemon's live metadata cache remains volatile and is rebuilt from currently
attached devices; saved snapshots are never used to authorize media actions.
Together, explicit boot reports, inventory snapshots and hardware captures provide
the boot history, cached metadata and diagnostics assigned to FDS_INTERNAL in
master-plan section 12, without adding internal writes to startup or shutdown.
## Dependencies and validation
No new target package or Rust crate is required. The host image-tool prefix adds
`e2fsprogs` for ext4 creation, inspection and validation; it already supplies FAT
and EROFS tools. A private unprivileged user namespace gives created files root
ownership without requiring a root build session.
`make internal-test` exercises the actual packaged runtime in ARM VMs with
virtual NVMe. Acceptance evidence belongs in [M12 validation](m12-validation.md);
a passing VM does not verify the Pi EEPROM, PCIe path or physical flash durability.
The Linux [ext4 mount documentation](https://www.kernel.org/doc/html/latest/admin-guide/ext4.html)
explains why read-only loading also disables journal replay. Filesystem creation
options follow the upstream [mke2fs manual](https://man7.org/linux/man-pages/man8/mke2fs.8.html).