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,110 @@
+# M11 stress 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.
+
+
+[Stress-test usage and physical procedure](stress-testing.md) · [Implementation ledger](implementation-status.md)
+
+M11 software acceptance passed on 2026-09-21. The expanded twelve-device suite
+passed in `out/m11-vm.o1c_tqiv/`, including the explicit readiness gate and
+diagnostic collector. The public `make stress-test` passed all six initial media
+failure cases in `out/m11-faults.g5uw_jao/`. The strengthened final
+`make media-fault-test` passed in `out/m11-faults.hfyqoui3/`, verifying the actual
+virtual-device byte counter before each interruption. `make check` then passed. Physical Pi/hub/battery tests remain deferred.
+
+## Twelve-device evidence
+
+The complete runs used the packaged M10 CLI rootfs and actual Pi kernel in
+an isolated generic ARM VM. A protected virtual SYSTEM root and twelve USB disks
+were present: one DATA and eleven distinct PROGRAM cartridges. Every identity
+matched its bay through cold boot, three simultaneous hotplug/removal cycles,
+rotated placements and reverse device insertion order.
+
+Eleven direct readers each verified 32 MiB while DATA wrote and flushed 64 MiB.
+All twelve measured I/O intervals overlapped. QEMU block counters confirmed the
+corresponding reads/writes, so cached file reads alone could not satisfy the test.
+A subsequent managed writer and its TERM-ignoring descendant ran during native
+reboot. Independent host `e2fsck` passed; the entire 64 MiB payload matched its
+expected SHA-256. Another boot with a different device declaration order retained
+correct mapping and data, and completed native poweroff. Read-only cartridge
+image hashes were unchanged.
+
+Kernel logs from normal stress/reboot contained no detected unexpected USB reset,
+controller failure, I/O error or filesystem error. This only describes the virtual
+hardware used in the test. It says nothing about physical voltage, hub firmware,
+cables, RP1 or a storage controller's cache guarantees.
+
+## Startup observations
+
+Three paired samples used the same SYSTEM and virtual controller, with either
+zero or twelve USB disks. The first complete run observed:
+
+| USB population | Kernel-to-console samples | Median |
+| --- | --- | --- |
+| Empty | 1907.961445, 1761.020483, 1847.460910 ms | 1847.460910 ms |
+| Twelve | 1968.638224, 1998.194820, 1927.705171 ms | 1968.638224 ms |
+
+The median device-load difference was **+121.177314 ms**, above the 100 ms review
+threshold. Stage0 discovery remained approximately 23–27 ms in both scenarios;
+the increased work appears mainly between s6 start and console readiness.
+The unchanged getty graph has no cartridge-readiness dependency. Concurrent USB
+and cartridge processing competes with startup in this two-vCPU emulator. This
+is an explanation of the controlled device-load comparison, not a claim that a
+code change has been proven faster or that Pi timing targets passed.
+
+Earlier complete cold-boot pairs from interrupted test attempts observed
+122.544124 ms and +76.064782 ms; their raw reports remain in
+`out/m11-vm.jcvwpxel/` and `out/m11-vm.w4oyzwje/`. They are not full acceptance runs.
+The spread is retained rather than discarding slower observations. The expanded
+suite then passed with medians 1900.735990 ms (empty) and 1957.588750 ms (twelve):
+**+56.852760 ms**. All samples and the actual ARM comparison are stored in
+`out/m11-vm.o1c_tqiv/boot-comparison.json` and `boot-review.log`. The blocked-daemon
+case reached the real UID-1000 prompt with no cartridge control socket, then
+completed enumeration and native shutdown after an explicit event released the
+daemon. This verifies console independence under the same twelve-device load.
+
+## Test-harness findings
+
+The AArch64 Linux `O_DIRECT` flag differs from the x86_64 value. An initial
+fixture incorrectly requested directory-only opens and failed before I/O. The
+corrected ARM-only test helper performs aligned direct reads; byte checks and
+block counters then passed. No target runtime change was needed.
+
+A burst of asynchronous device-deletion events could arrive while a new QMP
+monitor connection was being greeted. The shared VM helper now accepts those
+events before the greeting, without treating them as command responses. Checked
+serial capture executes a command once and retries only a corrupted transfer.
+It preserves kernel diagnostics instead of suppressing error messages.
+
+## Media failure acceptance
+
+Actual-device tests passed for write EIO, flush EIO and readback EIO.
+Each leaves a failed operation across daemon restart, with no SAFE marker.
+Cancellation, worker death and daemon death during confirmed writing also passed
+in `out/m11-faults.g5uw_jao/`. The strengthened run in
+`out/m11-faults.hfyqoui3/` additionally requires at least 64 MiB in QEMU's actual
+write counter while the transfer remains incomplete, retaining that counter and
+job state in an interruption record. All three strengthened interruption cases
+passed: each had accepted 128 MiB into the guest write path and delivered 64 MiB
+to the virtual disk, with a 270532608-byte source still incomplete. Cancellation
+retained its diagnostic, worker death retained a failed-completion error, and
+daemon death retained a restart error. Each remained failed after another
+restart, with the daemon usable and no SAFE marker.
+
+Final logs are `out/logs/m11-final-stress-retry.log`,
+`out/logs/m11-final-faults.log` and `out/logs/m11-final-check.log`. The final failure
+run records input hashes and QEMU 11.1.1 identity beside its images. Runtime
+packages and boot artifacts remain the verified M10 builds; M11 adds tests and
+physical-test tooling rather than changing the target service behavior.
+
+## Physical acceptance
+
+The [physical procedure](stress-testing.md#prepare-the-physical-session) covers
+bay calibration, cold boot, rotated placement, concurrent I/O, orderly reboot and
+poweroff, power behavior and external timing. `tools/capture-hardware` collects
+read-only local diagnostics with per-command exit statuses and checksums. It
+reports collection success separately from hardware acceptance. All 17 capture
+commands returned success in the ARM VM, and the resulting private directory
+and checksums passed inspection. The blank physical session template remains
+explicitly `not_run`. None of those
+physical tests has been performed in this milestone.