From: jtryba Date: Tue, 4 Aug 2026 21:56:56 +0000 (-0500) Subject: Document exact-release Linux hardware validation X-Git-Url: https://git.jtryba.com/browse/friidump.git/commitdiff_plain/refs/heads/main?ds=inline;hp=759ff43c97423ceb8ce4be11002237ff507284c6 Document exact-release Linux hardware validation --- diff --git a/README b/README index a983057..a9f2616 100644 --- a/README +++ b/README @@ -160,23 +160,27 @@ $ cmake .. $ make $ make install -Linux-specific note: You need root privileges to issue certain commands to the -DVD-ROM drive. Hence you have the following possibilities: -- Run FriiDump as root: discouraged. -- Run it through sudo: better but nevertheless discouraged. -- Set the setuid bit on the executable: this is the recommended way to run - FriiDump under Linux. This way, the code run with superuser privileges will - be reduced to a minimum, guaranteeing a certain level of security (note that - security-related bugs might exist anyway!!!). Also note that, even when the - setuid bit is set, the attempt to open the drive for reading will be done - after privileges have been dropped, so you will need explicit read access to - the DVD-ROM drive. Usually having the system administrator add you to the - "cdrom" group is enough. To set the setuid bit on the executable, run as - root: - - $ chown root:root /usr/local/bin/friidump - $ chmod u+s /usr/local/bin/friidump +Linux-specific note: Run FriiDump as a normal user. Do not run it with `sudo`, +and do not install it setuid-root. +Linux vendor-command paths need two separate permissions: + +- The normal user needs access to the selected `/dev/sr*` device and, when + applicable, its `/dev/sg*` device. On Ubuntu, membership in the `cdrom` group + normally provides this access. +- GameCube/Wii memory-dump methods and Xbox vendor-unlock paths need effective + `CAP_SYS_RAWIO` on the exact validated FriiDump executable. + +After you verify the executable, use the maintained helper: + + $ bash ./validation/friidump-linux-rawio-capability.sh install \ + ./build/src/friidump + $ getcap ./build/src/friidump + +Rebuilding, relinking, copying, replacing, or re-extracting the executable can +clear its file capability. Verify `cap_sys_rawio=ep` before each +vendor-command hardware run. See `docs/LINUX.md` for the complete Linux +permission and hardware procedure. =============================================================================== Usage diff --git a/README.md b/README.md index 0318a06..9816d34 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,29 @@ the executable clears that capability. See [`docs/LINUX.md`](docs/LINUX.md) before Linux hardware use. +## Exact-release Linux hardware validation + +The exact FriiDump 0.5.3.16-pf1 Linux executable was validated on two +GameCube paths after release publication: + +- an `HL-DT-ST CDRW/DVD GCC4244 B101` completed profile selection, all 20 seed + blocks, a controlled partial read, cancellation, native reporting, profile + reporting, and STOP UNIT; +- a physical GDR-8163B cross-flashed with modified GDR-8050L `0012` firmware + completed the modified `0xE7` path, all 20 seed blocks, a controlled partial + read, cancellation, native reporting, profile reporting, and FriiDump's + internal STOP UNIT. + +The validated cross-flashed unit had to start with a readable Video DVD before +it identified as `HL-DT-ST DVD-ROM GDR8050L 0012`. The drive stayed powered and +connected while the disc was changed to Sonic Mega Collection (US). Linux host +media probing was temporarily quarantined for that run because earlier +background reads had blocked the USB/SCSI path. + +See +[`docs/reports/FRIIDUMP_LINUX_EXACT_RELEASE_HARDWARE_VALIDATION_0.5.3.16-pf1.md`](docs/reports/FRIIDUMP_LINUX_EXACT_RELEASE_HARDWARE_VALIDATION_0.5.3.16-pf1.md) +for the exact evidence identities and validation limits. + ## Candidate11 Linux Xbox parity baseline Candidate11 begins the Linux parity campaign without replacing the validated Windows/MSVC GDR-8050L path. The Windows copied-reference implementation remains diff --git a/docs/CURRENT_STATUS.md b/docs/CURRENT_STATUS.md index da37392..d53f9fc 100644 --- a/docs/CURRENT_STATUS.md +++ b/docs/CURRENT_STATUS.md @@ -13,6 +13,14 @@ tree rather than inferring authority from a checkout directory or ZIP name. - Linux/CMake builds pass with explicit normal-user `CAP_SYS_RAWIO` handling. - A GCC-4244 B101 completed the Sonic Mega Collection (US) GameCube dump with an exact full-image hash match. +- The exact 0.5.3.16-pf1 Linux executable later completed a controlled + GCC-4244 B101 GameCube smoke with all 20 seed blocks, partial output, + cancellation, native reporting, profile reporting, and STOP UNIT. +- The exact 0.5.3.16-pf1 Linux executable completed the modified GDR-8050L + `0xE7` GameCube path on physical GDR-8163B hardware cross-flashed with + GDR-8050L `0012` firmware. The run completed all 20 seed blocks, partial + output, cancellation, native reporting, profile reporting, and internal + STOP UNIT. - The Linux GDR-8050L path established both Xbox game-view transitions, read XDVDFS metadata, captured DMI media ID `TQ00501A`, produced a controlled partial GAME-XDVDFS output with hashes and native reporting, and completed @@ -20,6 +28,24 @@ tree rather than inferring authority from a checkout directory or ZIP name. - Native `friidump-test-result.v1` reports cover complete, partial, failed, cancelled, no-media, seed-failure, and modified-firmware states. +## Linux exact-release hardware closure + +The two required Linux GameCube hardware targets are complete. + +The GCC-4244 B101 exact-release evidence archive has SHA-256 +`7c9573d7dddf6381d8847626d0a45e96e57f2b64d79967a041d8acf4affebef5`. +The cross-flashed GDR-8163B/GDR-8050L `0012` evidence archive has SHA-256 +`872b8144b8cc55601b268867ad8cc74cc7266a514cf015e24cd2fe3a450ee602`. + +The validated cross-flashed unit required a readable Video DVD at power-on +before it identified as GDR-8050L `0012`. The drive remained powered and +connected while the disc was changed to Sonic Mega Collection (US). A +temporary host-probe quarantine prevented background Linux media discovery +from blocking the USB/SCSI path. The host state was restored after the run. + +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). + ## Hardware-validation boundary The Linux GDR-8050L evidence validates the command path, game-view state, @@ -77,5 +103,7 @@ selection plus raw-I/O authorization, but failed immediately at Stage 2 because the Linux optical door remained locked while FriiDump held the device open. Candidate16 releases the Linux `CDROM_LOCKDOOR` state before each GDR-8050L software eject/load cycle, restores the lock after a successful load, and leaves -the door unlocked on failure for manual recovery. A physical Xbox-disc smoke is -required before the Linux Xbox gate can close. +the door unlocked on failure for manual recovery. The later Candidate21 +hardware run closed the Linux Xbox command-path gate with both game-view +transitions, DMI capture, controlled partial output, cancellation, native +reporting, and STOP UNIT. It did not claim a newly completed full Xbox image. diff --git a/docs/ChangeLog b/docs/ChangeLog index ba4bcc8..6ff205e 100644 --- a/docs/ChangeLog +++ b/docs/ChangeLog @@ -1,3 +1,20 @@ +2026-08-04 Project Frankenstein Linux exact-release hardware documentation + + * Record exact FriiDump 0.5.3.16-pf1 Linux hardware validation on + HL-DT-ST GCC-4244 B101. + * Record exact-release modified-0xE7 GameCube validation on physical + GDR-8163B hardware cross-flashed with GDR-8050L 0012 firmware. + * Document the validated Video-DVD boot and powered disc-swap sequence for + that cross-flashed unit. + * Document the temporary UDisks/udev host-probe quarantine boundary and + require complete host-state restoration. + * Warn against standalone sg_turs, sg_prevent, and STOP probes on the + validated GDR-8050L USB path because those probes blocked in kernel I/O. + * Replace inherited setuid-root Linux guidance with the maintained + normal-user CAP_SYS_RAWIO procedure. + * Preserve the immutable v0.5.3.16-pf1 release tag and record this as a + post-release documentation update only. + FriiDump 0.5.3.16-pf1 ---------------------- - Correct standard READ DVD STRUCTURE Format placement from CDB byte 11 diff --git a/docs/LINUX.md b/docs/LINUX.md index 4c877fb..ad4661c 100644 --- 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 diff --git a/docs/reports/FRIIDUMP_LINUX_EXACT_RELEASE_HARDWARE_VALIDATION_0.5.3.16-pf1.md b/docs/reports/FRIIDUMP_LINUX_EXACT_RELEASE_HARDWARE_VALIDATION_0.5.3.16-pf1.md new file mode 100644 index 0000000..8570bb8 --- /dev/null +++ b/docs/reports/FRIIDUMP_LINUX_EXACT_RELEASE_HARDWARE_VALIDATION_0.5.3.16-pf1.md @@ -0,0 +1,198 @@ +# FriiDump 0.5.3.16-pf1 Linux Exact-Release Hardware Validation + +## Purpose + +This report records the final Linux hardware validation of the exact published +FriiDump 0.5.3.16-pf1 executable. It covers the GCC-4244 B101 path and the +modified GDR-8050L `0xE7` path on cross-flashed GDR-8163B hardware. + +The evidence archives remain outside Git. This report records their exact +filenames, SHA-256 values, accepted results, and validation limits. + +## Release authority + +- Release: `0.5.3.16-pf1` +- Annotated tag: `v0.5.3.16-pf1` +- Tag object: `3faddd693c9198081778561c683f21c7904c7376` +- Release commit: `410adc894dbd68d10080151171b8c42a9197df46` +- Release tree: `2b7f19e733e742e6589d1afc40c63da7be4b99da` +- Linux executable SHA-256: + `ac58e427b59ba98018c8c1ed4f07fbf736cc887f3e74fefe0d04a43409d88561` +- Linux authorization: normal-user execution with `cap_sys_rawio=ep` + +## GCC-4244 B101 result + +Evidence archive: + +`friidump-v0.5.3.16-pf1-gcc4244-b101-linux-smoke-v4-20260803T223910Z.tar.gz` + +SHA-256: + +`7c9573d7dddf6381d8847626d0a45e96e57f2b64d79967a041d8acf4affebef5` + +Accepted classification: + +`ACCEPTED_PASS_WITH_WRAPPER_POSTPROCESSING_DEFECT` + +Validated hardware and runtime identity: + +- drive: `HL-DT-ST CDRW/DVD GCC4244 B101`; +- kernel block device during the run: `/dev/sr1`; +- SCSI-generic device during the run: `/dev/sg2`; +- USB bridge: JMicron `152d:2338`; +- serial: `4534CD5277D6`; +- command: `2`; +- method: `8`; +- profile: Type3, `legacy_detected`; +- cache base: `0x80000000`; +- memory windows: `5`. + +Validated behavior: + +- exact release identity and executable hash; +- effective `CAP_SYS_RAWIO`; +- all 20 seed blocks; +- Sonic Mega Collection (US) identification; +- controlled partial output; +- controlled cancellation; +- native JSON report; +- HLDS profile report; +- FriiDump STOP UNIT; +- clean kernel evidence for the accepted run. + +The run completed 5,441 sectors and 11,143,168 bytes before cancellation. The +partial ISO SHA-256 was +`44ea2620898cc0ddbff643b6141b1830699e0b58f8ba51bdc2e4a9f2a2044ca8`. + +The wrapper exited during post-processing because it used invalid shell +arithmetic for the cancellation duration. FriiDump had already completed the +validated hardware gates. The cleanup path also confirmed STOP. No additional +hardware run is required only to correct the wrapper. + +The earlier Candidate11 full dump remains the full-image authority. It matched +the established Sonic Mega Collection (US) reference: + +- sectors: `712880`; +- CRC32: `01b52739`; +- MD5: `85a525df1481d0ad67d8761f832dca12`; +- SHA-1: `06eb6d15b4d7f90ec0fed9ce9a77db41358d74ed`; +- SHA-256: + `30098da93f5de9ece8da44f8afdfb85cf9bcdc24d77131221e64e3038a529010`. + +## Cross-flashed GDR-8163B/GDR-8050L result + +Evidence archive: + +`friidump-v0.5.3.16-pf1-gdr8050l-0012-host-probe-quarantine-v2-20260804T031108Z.tar.gz` + +SHA-256: + +`872b8144b8cc55601b268867ad8cc74cc7266a514cf015e24cd2fe3a450ee602` + +Accepted classification: + +`ACCEPTED_PASS_WITH_OUTPUT_ASSERTION_DEFECT` + +Validated hardware and runtime identity: + +- physical hardware: GDR-8163B; +- operating identity: `HL-DT-ST DVD-ROM GDR8050L 0012`; +- modified firmware: GDR-8050L `0012` with `0xE7` memory-dump support; +- kernel block device during the run: `/dev/sr1`; +- SCSI-generic device during the run: `/dev/sg2`; +- USB bridge: JMicron `152d:2338`; +- serial: `4534D6D52972`; +- command: `2`; +- method: `8`; +- profile: `GDR-8050L modified 0xE7 speed-probe pending`; +- selected runtime profile: 3-window no-prefetch; +- cache base: `0x80000000`. + +The validated unit did not identify as GDR-8050L when it started with Sonic +Mega Collection in the tray. It required this sequence: + +1. Put a readable Video DVD in the tray. +2. Close the tray. +3. Power on and connect the external drive. +4. Wait for the `GDR8050L 0012` identity. +5. Keep drive power and USB connected. +6. Use the physical eject button. +7. Replace the Video DVD with Sonic Mega Collection (US). +8. Close the tray and wait for spin-up. +9. Start FriiDump. + +This sequence is evidence for the validated cross-flashed unit. It is not a +general claim for every GDR-8050L. + +Normal Linux media discovery caused background reads on this USB path. Earlier +reads blocked in kernel I/O and prevented FriiDump initialization. The accepted +run used a temporary, failure-safe quarantine: + +- the target was absent before quarantine; +- the current UDisks state was recorded; +- UDisks optical-volume probing was stopped; +- udev rule execution was paused; +- the drive was connected with the Video DVD; +- exact sysfs identity was confirmed; +- private block and SCSI-generic nodes were created from sysfs; +- the disc was changed while power and USB remained connected; +- FriiDump ran through the private nodes; +- the external target was disconnected before queued udev work was released; +- udev and UDisks were restored to their original active state. + +The accepted run sent no standalone SCSI readiness probe, no standalone STOP +command, and no PREVENT/ALLOW MEDIUM REMOVAL command. FriiDump completed its own +ready-media check and internal STOP UNIT. + +Validated behavior: + +- initialization in 1 second; +- all 20 seed blocks; +- seed elapsed time of 21.58 seconds; +- Sonic Mega Collection (US) identification; +- 2,161 sectors and 4,425,728 bytes of partial output; +- controlled cancellation in 1 second; +- native JSON report; +- HLDS profile report; +- primary log; +- FriiDump internal STOP UNIT; +- complete host-state restoration; +- no kernel I/O error during the accepted run. + +The partial ISO SHA-256 was +`6a68279eccac41b63ec6cc0074e4ef43559808d51d201a6db7fab4c1a0313057`. + +The wrapper's final assertion expected a colon in the successful ready-media +line. FriiDump printed: + +`Checking for ready media before disc seed retrieval... OK` + +The exact hardware evidence passed. No additional hardware run is required only +to correct the wrapper assertion. + +## Operational limits + +- Identify optical devices dynamically. Do not assume `/dev/sr0`. +- Keep the internal optical drive installed when an external validation drive + is attached. +- Run FriiDump as the normal user. +- Apply `cap_sys_rawio=ep` only to the exact validated executable. +- Do not run FriiDump with `sudo`. +- Do not install FriiDump setuid-root. +- Do not use standalone `sg_turs`, `sg_prevent`, or STOP probes on the validated + GDR-8050L USB path. +- If a process is in state `D`, power-cycle only the external drive and USB + bridge. The blocked kernel request must return before a pending signal can + complete. +- Do not disable UDisks or udev permanently. +- Preserve hardware evidence outside Git by exact filename and SHA-256. + +## Final disposition + +The GCC-4244 B101 and cross-flashed GDR-8163B/GDR-8050L `0012` Linux GameCube +hardware targets are complete for FriiDump 0.5.3.16-pf1. + +The GCC-4244 B101 full-image authority remains the earlier exact full dump. The +exact-release GCC run and the exact-release GDR-8050L run validate release +identity, authorization, profile selection, seed retrieval, partial output, +cancellation, reporting, and STOP behavior.