Document exact-release Linux hardware validation

[friidump.git] / docs / LINUX.md

diff --git a/docs/LINUX.md b/docs/LINUX.md
index 4c877fbcb123b4f6db11cd639a70a76b3d043f18..ad4661c40f2ff0c556cce82b4fcb9c3d1484943b 100644 (file)
--- a/docs/LINUX.md
+++ b/docs/LINUX.md
@@ -1,5 +1,29 @@
 # FriiDump on Linux
 
+## Exact-release hardware status
+
+The exact FriiDump 0.5.3.16-pf1 Linux executable has completed controlled
+hardware validation on both required GameCube paths:
+
+- `HL-DT-ST CDRW/DVD GCC4244 B101`;
+- physical GDR-8163B hardware that identifies as
+  `HL-DT-ST DVD-ROM GDR8050L 0012` after a cross-flash with modified
+  GDR-8050L firmware.
+
+Both runs used the exact executable with SHA-256
+`ac58e427b59ba98018c8c1ed4f07fbf736cc887f3e74fefe0d04a43409d88561`
+and effective `cap_sys_rawio=ep`. Both runs completed profile selection, all
+20 seed blocks, a controlled partial read, cancellation, native reporting,
+profile reporting, and STOP UNIT.
+
+The GCC-4244 B101 exact-release run supplements the earlier Candidate11 full
+dump, which remains the full-image hash authority. The GDR-8050L exact-release
+run validates the modified `0xE7` GameCube path; it does not claim a new full
+GameCube image.
+
+See
+[`reports/FRIIDUMP_LINUX_EXACT_RELEASE_HARDWARE_VALIDATION_0.5.3.16-pf1.md`](reports/FRIIDUMP_LINUX_EXACT_RELEASE_HARDWARE_VALIDATION_0.5.3.16-pf1.md).
+
 ## Candidate21 status
 
 FriiDump builds natively with GCC/CMake and uses Linux optical-drive packet
@@ -153,9 +177,48 @@ ls -l /dev/sr1 /dev/sg2
 getcap "$(readlink -f ./build/src/friidump)"
 ```
 
-Close media players and file managers, unmount any mounted filesystem from the
-drive, and disable automatic media polling where practical. Linux currently
-provides no FriiDump-exclusive optical-volume lock equivalent for this path.
+Close media players and file managers, and unmount any filesystem from the
+selected drive. Linux currently provides no FriiDump-exclusive optical-volume
+lock equivalent for this path.
+
+For the validated cross-flashed GDR-8050L USB path, do not use standalone
+`sg_turs`, `sg_prevent`, or `friidump -p` commands as readiness or cleanup
+probes. During validation, separate probe commands blocked in kernel I/O and
+required a power cycle of the external drive and USB bridge. The accepted run
+used FriiDump's internal ready-media check and internal STOP UNIT only.
+
+## Cross-flashed GDR-8050L GameCube/Wii procedure
+
+The validated physical unit required this sequence before a GameCube/Wii run:
+
+1. Put a readable Video DVD in the tray.
+2. Close the tray.
+3. Power on and connect the external drive.
+4. Wait until Linux identifies it as `HL-DT-ST DVD-ROM GDR8050L 0012`.
+5. Keep drive power and USB connected.
+6. Use the physical eject button.
+7. Replace the Video DVD with the target GameCube or Wii disc.
+8. Close the tray and wait for spin-up.
+9. Start FriiDump as the normal user with `cap_sys_rawio=ep` on the exact
+   validated executable.
+
+This boot-disc requirement is evidence for the validated cross-flashed unit. It
+is not a general claim for every GDR-8050L.
+
+On the validated JMicron `152d:2338` USB bridge, normal host media discovery
+started background reads that could block the USB/SCSI path before FriiDump
+opened the drive. The accepted run temporarily stopped UDisks and paused udev
+rule execution, created private device nodes from sysfs, ran FriiDump, required
+the external target to be disconnected, and then restored the host state.
+
+Do not disable UDisks or udev permanently. Use a reviewed, failure-safe
+quarantine workflow only when background host probing is proven to interfere.
+Record the original service state, restore it on every exit path, and disconnect
+the external target before queued udev work is released.
+
+If an optical command remains in process state `D`, signals cannot complete
+until the blocked kernel request returns. Power-cycle only the external drive
+and USB bridge. Leave unrelated optical drives installed.
 
 ## Xbox XISO
 
@@ -182,6 +245,24 @@ unlocked XBE/DMI view on Linux.
     "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
 ```
 
+## Exact-release evidence identities
+
+The accepted external evidence archives are not stored in Git:
+
+- `friidump-v0.5.3.16-pf1-gcc4244-b101-linux-smoke-v4-20260803T223910Z.tar.gz`
+  - SHA-256:
+    `7c9573d7dddf6381d8847626d0a45e96e57f2b64d79967a041d8acf4affebef5`
+  - classification:
+    `ACCEPTED_PASS_WITH_WRAPPER_POSTPROCESSING_DEFECT`
+- `friidump-v0.5.3.16-pf1-gdr8050l-0012-host-probe-quarantine-v2-20260804T031108Z.tar.gz`
+  - SHA-256:
+    `872b8144b8cc55601b268867ad8cc74cc7266a514cf015e24cd2fe3a450ee602`
+  - classification:
+    `ACCEPTED_PASS_WITH_OUTPUT_ASSERTION_DEFECT`
+
+The wrapper defects occurred after or outside the validated hardware gates. No
+additional hardware run is required only to correct those wrapper defects.
+
 ## Validation boundary
 
 A Linux build is not considered ready for vendor-command hardware validation