update docs

2026-09-22 13:23:34 +08:00
parent 99bc3d15c5
commit 8a4788fca8
126 changed files with 7198 additions and 2425 deletions
@@ -0,0 +1,78 @@
+# M7 writable DATA validation
+
+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.
+
+
+Software acceptance passed on 2026-09-21 using the x86_64 Arch build workstation,
+QEMU 11.1.1, the actual AArch64 Pi kernel and static FDS tools. Physical Pi,
+removable-media power loss and real shutdown/eject latency remain deferred.
+
+## DATA acceptance workload
+
+`make data-test` passed in `out/m7-vm.drg2a4ml/`:
+
+- Without DATA, the ordinary UID-1000 console can write its temporary home.
+  Inserting a valid ext4 DATA cartridge activates `/data`; user writes persist
+  through eject and reinsertion while the temporary home remains separate.
+- An unmanaged shell working directory and an extra bind mount each prevent
+  SAFE. The additional-mount check runs before stopping managed programs.
+- A managed writer and its child run as UID/GID 1000 with no effective
+  capabilities and `no_new_privs`. At least 128 MiB is written while repeatedly
+  overwriting a 64 MiB file. Both processes intentionally ignore TERM.
+- Eject escalates to kernel cgroup termination after its exit deadline, observes
+  that the complete group has exited, runs syncfs, closes its writeback handle,
+  unmounts normally and only then reports SAFE. The managed process count is zero.
+- SAFE persists across a daemon restart until removal/reinsertion. Reinsertion
+  reads the previously saved user file, followed by another successful eject.
+- Two DATA candidates in one discovery snapshot remain read-only. Explicit
+  selection activates the requested bay; another request cannot replace an
+  active session underneath its users.
+- Pulling DATA during dirty writes produces actual kernel storage errors. The
+  daemon stops the remaining managed descendants and clears the vanished mount.
+  Eject afterward fails; this path never claims SAFE or a clean filesystem.
+
+After the VM releases its disks, the test extracts each safely ejected ext4
+partition into an ordinary file. Host e2fsprogs 1.47.4 runs `e2fsck -fn` on both;
+both exit zero. `debugfs` extracts the 64 MiB stress payload, whose size and SHA-256
+match the complete expected byte pattern. No host filesystem mount is involved.
+See `primary-fsck.log`, `secondary-fsck.log`, `filesystem-tools.log`, and
+`surprise-removal-kernel.log` in the evidence directory.
+
+During development, removal exposed partially disappearing USB sysfs entries.
+Discovery now skips incomplete individual entries, retains a still-present
+mounted disk identity, and does not restart the daemon merely because another
+USB device is being removed. Fixture checks and the final hotplug workload passed.
+Kernel diagnostics sharing the test serial console are preserved in logs and
+excluded only from the CLI JSON parser; errors are not treated as successful I/O.
+
+## Final image and regressions
+
+| Artifact | SHA-256 |
+| --- | --- |
+| Rootfs TAR, `out/rootfs-build.wFuKoS/` | `cdd7c2c8809bf144234470839cc082014f9757276e1d2f769496511c056fe127` |
+| SYSTEM, `out/system-build.y7aiuhbi/` | `1675f9225ccca746045f7f999fed5b9b48d7bdd23869aa65a90f97a4219aafab` |
+| Production boot FAT, `out/boot-build.abgq4799/` | `fb54582a9bd3bb393299002a65a5b0035e806e6733e81a437369a0b152b297e2` |
+
+The rootfs has 112 packages, 1,170 AArch64 ELF files and a 408,309,760-byte TAR.
+M7 adds no external Rust dependency or target package. Its process tracking uses
+already-enabled Linux cgroup v2 and PID-limit support. cgroup setup belongs to
+the cartridge daemon and adds no console dependency. Test filesystem tools are
+the host e2fsprogs tools already used by the M2 workflow.
+
+The final sequential pipeline exited zero: fresh rootfs and initramfs, tooling
+checks, formatting/negative checks, rootfs checks, native-init VM, SYSTEM and boot
+volume, all nine stage0 cases, ordinary console tests, cartridge tests and DATA
+tests. Logs are `out/logs/m7-verified-*.log`. Native-init evidence is
+`out/m2-vm.1sPKEy/`; the cartridge regression is `out/m6-vm._cgfbexe/`.
+The temporary root test console and writer binary are confined to disposable
+fixtures and do not ship in the production rootfs.
+
+The ordinary-console trace in `out/m5-vm.6_55lhge/` measures 1,769.585 ms from the
+kernel clock, versus M6's 1,753.878 ms: +15.707 ms. The ARM regression comparison
+passes the 100 ms explanation threshold (`out/logs/m7-boot-regression.log`).
+These individual VM observations do not establish Pi performance targets.
+
+Attached-media writeback fault injection, broader stress and complete shutdown
+ordering remain part of M10/M11. Physical flash-controller cache and power-loss
+behavior require hardware. Read [DATA usage](data.md) for the implemented user
+workflow and [the ledger](implementation-status.md) for remaining milestones.