docs/LINUX.md

   1 # FriiDump on Linux
   2
   3 ## Exact-release hardware status
   4
   5 The exact FriiDump 0.5.3.16-pf1 Linux executable has completed controlled
   6 hardware validation on both required GameCube paths:
   7
   8 - `HL-DT-ST CDRW/DVD GCC4244 B101`;
   9 - physical GDR-8163B hardware that identifies as
  10   `HL-DT-ST DVD-ROM GDR8050L 0012` after a cross-flash with modified
  11   GDR-8050L firmware.
  12
  13 Both runs used the exact executable with SHA-256
  14 `ac58e427b59ba98018c8c1ed4f07fbf736cc887f3e74fefe0d04a43409d88561`
  15 and effective `cap_sys_rawio=ep`. Both runs completed profile selection, all
  16 20 seed blocks, a controlled partial read, cancellation, native reporting,
  17 profile reporting, and STOP UNIT.
  18
  19 The GCC-4244 B101 exact-release run supplements the earlier Candidate11 full
  20 dump, which remains the full-image hash authority. The GDR-8050L exact-release
  21 run validates the modified `0xE7` GameCube path; it does not claim a new full
  22 GameCube image.
  23
  24 See
  25 [`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).
  26
  27 ## Candidate21 status
  28
  29 FriiDump builds natively with GCC/CMake and uses Linux optical-drive packet
  30 commands through the existing `dvd_drive` transport. Candidate21 makes the
  31 Linux privilege boundary explicit and reproducible.
  32
  33 Candidate21 also corrects the Linux GDR-8050L software tray cycle. Linux may
  34 lock an optical door while the device is open (`CDO_LOCK`). Before each required
  35 Xbox media cycle, FriiDump now releases that lock with `CDROM_LOCKDOOR`, sends
  36 the software eject/load sequence, waits for readiness, and restores the door
  37 lock after a successful load. On a cycle failure it deliberately leaves the
  38 door unlocked so the disc can be recovered without power-cycling the external
  39 drive.
  40
  41 The Linux workflow uses two separate permissions:
  42
  43 1. **Device-node access** — the normal user must be able to open `/dev/sr*` and,
  44    where applicable, the corresponding `/dev/sg*`. On Ubuntu this normally
  45    comes from membership in the `cdrom` group.
  46 2. **Vendor-command authorization** — GameCube/Wii memory-dump methods and Xbox
  47    vendor-unlock paths issue commands outside Linux's ordinary unprivileged
  48    SCSI allowlist. Those operations require effective `CAP_SYS_RAWIO`.
  49
  50 Membership in `cdrom` is necessary but does not replace `CAP_SYS_RAWIO`.
  51
  52 ## Candidate21 DMI and media-ID boundary
  53
  54 Candidate20 proved the Linux SG_IO handshake and XDVDFS data path but left the
  55 media ID empty because its standard READ DVD STRUCTURE helper wrote Format to
  56 CDB byte 11. Candidate21 uses byte 7, matching the copied Windows
  57 `GetMediaID()` request. Live runs log `[XBOX-DVD-STRUCTURE]` PFI and DMI capture
  58 results. The expected Red Faction II media ID is `TQ00501A`.
  59
  60 The step-9 sticky-descrambling transport result remains visible. Final READ
  61 CAPACITY and readable XDVDFS data are authoritative for game-view success.
  62
  63
  64 ## Build
  65
  66 ```bash
  67 cmake -S . -B build \
  68   -DBUILD_STATIC_BINARY=ON \
  69   -DBUILD_NATIVE_REPORT_TESTS=ON \
  70   -DFRIIDUMP_BUILD_COMMIT="$(git rev-parse HEAD)"
  71 cmake --build build --parallel
  72 ./build/src/friidump-xbox-portable-metadata-test
  73 ./build/src/friidump-linux-rawio-test
  74 ./build/src/friidump --help
  75 ```
  76
  77 Linux configuration and the Candidate21 build validator print a warning that a
  78 normal build does **not** install file capabilities. This is intentional: a
  79 compiler invocation must not silently elevate its output or invoke `sudo`.
  80
  81 ## Install the minimum raw-I/O authority
  82
  83 Do not run FriiDump itself with `sudo`, and do not install it setuid-root. Grant
  84 only `CAP_SYS_RAWIO` to the exact validated executable:
  85
  86 ```bash
  87 BIN="$(readlink -f ./build/src/friidump)"
  88 sudo setcap cap_sys_rawio=ep "$BIN"
  89 getcap "$BIN"
  90 ```
  91
  92 Expected output:
  93
  94 ```text
  95 /path/to/friidump cap_sys_rawio=ep
  96 ```
  97
  98 The maintained helper performs identity checks, applies the capability, verifies
  99 that the executable bytes did not change, and confirms the resulting xattr:
 100
 101 ```bash
 102 bash ./validation/friidump-linux-rawio-capability.sh install \
 103   ./build/src/friidump
 104 ```
 105
 106 Status and removal operations are also available:
 107
 108 ```bash
 109 bash ./validation/friidump-linux-rawio-capability.sh status \
 110   ./build/src/friidump
 111
 112 bash ./validation/friidump-linux-rawio-capability.sh remove \
 113   ./build/src/friidump
 114 ```
 115
 116 The maintained release helper applies the capability only to the exact
 117 validated executable:
 118
 119 ```bash
 120 bash ./validation/friidump-linux-rawio-capability.sh \
 121   install ./build/src/friidump
 122 ```
 123
 124 ### Capability lifetime
 125
 126 Linux file capabilities are extended attributes. They are not reliably
 127 preserved by ZIP extraction, ordinary copying, source packaging, or rebuilding.
 128 Replacing or relinking the executable clears the capability. Reapply and verify
 129 `cap_sys_rawio=ep` after every build that will be used for vendor-command
 130 hardware work.
 131
 132 Never assume that a newer candidate inherited the capability from an older
 133 binary. Candidate11 worked because its exact executable carried
 134 `cap_sys_rawio=ep`; Candidate12 and Candidate13 initially did not.
 135
 136 ## Runtime preflight
 137
 138 Before a vendor-command path begins seed retrieval or Xbox unlock, Candidate21
 139 checks the process's effective capability mask from `/proc/self/status`.
 140
 141 With the least-privilege configuration it prints:
 142
 143 ```text
 144 Linux raw-I/O preflight: PASS (CAP_SYS_RAWIO effective; ...).
 145 ```
 146
 147 When the capability is absent, FriiDump refuses the vendor operation before
 148 seed retrieval, prints exact `setcap` and `getcap` commands for the running
 149 executable, writes the failure into the native report, and issues STOP UNIT.
 150 This replaces the previous generic transport-level `EPERM` failure.
 151
 152 Candidate21 also refuses vendor-command work when the entire process is running
 153 as root. Run it as the normal user with the file capability instead.
 154
 155 Standard readable-DVD operations that do not use vendor memory-dump or unlock
 156 commands do not require `CAP_SYS_RAWIO`.
 157
 158 ## Device access
 159
 160 Identify the actual optical device dynamically. Do not assume the external
 161 validation drive is `/dev/sr0`:
 162
 163 ```bash
 164 for dev in /sys/class/block/sr*; do
 165   printf '%s: ' "/dev/${dev##*/}"
 166   xargs < "$dev/device/vendor"
 167   xargs < "$dev/device/model"
 168   xargs < "$dev/device/rev"
 169 done
 170 ```
 171
 172 Inspect permissions for the selected block and SCSI-generic device:
 173
 174 ```bash
 175 id
 176 ls -l /dev/sr1 /dev/sg2
 177 getcap "$(readlink -f ./build/src/friidump)"
 178 ```
 179
 180 Close media players and file managers, and unmount any filesystem from the
 181 selected drive. Linux currently provides no FriiDump-exclusive optical-volume
 182 lock equivalent for this path.
 183
 184 For the validated cross-flashed GDR-8050L USB path, do not use standalone
 185 `sg_turs`, `sg_prevent`, or `friidump -p` commands as readiness or cleanup
 186 probes. During validation, separate probe commands blocked in kernel I/O and
 187 required a power cycle of the external drive and USB bridge. The accepted run
 188 used FriiDump's internal ready-media check and internal STOP UNIT only.
 189
 190 ## Cross-flashed GDR-8050L GameCube/Wii procedure
 191
 192 The validated physical unit required this sequence before a GameCube/Wii run:
 193
 194 1. Put a readable Video DVD in the tray.
 195 2. Close the tray.
 196 3. Power on and connect the external drive.
 197 4. Wait until Linux identifies it as `HL-DT-ST DVD-ROM GDR8050L 0012`.
 198 5. Keep drive power and USB connected.
 199 6. Use the physical eject button.
 200 7. Replace the Video DVD with the target GameCube or Wii disc.
 201 8. Close the tray and wait for spin-up.
 202 9. Start FriiDump as the normal user with `cap_sys_rawio=ep` on the exact
 203    validated executable.
 204
 205 This boot-disc requirement is evidence for the validated cross-flashed unit. It
 206 is not a general claim for every GDR-8050L.
 207
 208 On the validated JMicron `152d:2338` USB bridge, normal host media discovery
 209 started background reads that could block the USB/SCSI path before FriiDump
 210 opened the drive. The accepted run temporarily stopped UDisks and paused udev
 211 rule execution, created private device nodes from sysfs, ran FriiDump, required
 212 the external target to be disconnected, and then restored the host state.
 213
 214 Do not disable UDisks or udev permanently. Use a reviewed, failure-safe
 215 quarantine workflow only when background host probing is proven to interfere.
 216 Record the original service state, restore it on every exit path, and disconnect
 217 the external target before queued udev work is released.
 218
 219 If an optical command remains in process state `D`, signals cannot complete
 220 until the blocked kernel request returns. Power-cycle only the external drive
 221 and USB bridge. Leave unrelated optical drives installed.
 222
 223 ## Xbox XISO
 224
 225 ```bash
 226 ./build/src/friidump \
 227   -d /dev/sr1 \
 228   -T 4 \
 229   -X "Red Faction II [TQ00501A].xiso" \
 230   --firmware-modified \
 231     "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
 232 ```
 233
 234 Omitting the XISO filename on a GDR-8050L derives `Title[MediaID].xiso` from the
 235 unlocked XBE/DMI view on Linux.
 236
 237 ## Xbox redump-style ISO
 238
 239 ```bash
 240 ./build/src/friidump \
 241   -d /dev/sr1 \
 242   -T 4 \
 243   -i "Red Faction II [TQ00501A].iso" \
 244   --firmware-modified \
 245     "GDR-8163B cross-flashed with modified GDR-8050L firmware; patched to allow 0xE7 memory dumps"
 246 ```
 247
 248 ## Exact-release evidence identities
 249
 250 The accepted external evidence archives are not stored in Git:
 251
 252 - `friidump-v0.5.3.16-pf1-gcc4244-b101-linux-smoke-v4-20260803T223910Z.tar.gz`
 253   - SHA-256:
 254     `7c9573d7dddf6381d8847626d0a45e96e57f2b64d79967a041d8acf4affebef5`
 255   - classification:
 256     `ACCEPTED_PASS_WITH_WRAPPER_POSTPROCESSING_DEFECT`
 257 - `friidump-v0.5.3.16-pf1-gdr8050l-0012-host-probe-quarantine-v2-20260804T031108Z.tar.gz`
 258   - SHA-256:
 259     `872b8144b8cc55601b268867ad8cc74cc7266a514cf015e24cd2fe3a450ee602`
 260   - classification:
 261     `ACCEPTED_PASS_WITH_OUTPUT_ASSERTION_DEFECT`
 262
 263 The wrapper defects occurred after or outside the validated hardware gates. No
 264 additional hardware run is required only to correct those wrapper defects.
 265
 266 ## Validation boundary
 267
 268 A Linux build is not considered ready for vendor-command hardware validation
 269 until all of these are recorded:
 270
 271 - exact executable SHA-256;
 272 - `getcap` output proving `cap_sys_rawio=ep` on that executable;
 273 - normal-user process identity;
 274 - device-node access through the intended group or ACL;
 275 - runtime raw-I/O preflight PASS;
 276 - hardware result, native report, and STOP UNIT result.
 277
 278 The `--xgd1-layout-probe` and `--xgd1-raw-id-probe` development probes remain
 279 Windows-only in this candidate. Their Linux transport port is tracked
 280 separately from ordinary ISO/XISO user-path parity.
 281
 282 ## Candidate21 GDR-8050L Windows-sequence parity
 283
 284 The portable Linux path follows the proven Windows state-aware order: readiness, entry capacity, direct `UnlockDrive()`, `RefreshVolume()`, a 2000 ms settle, readiness and capacity verification, with exactly one tray-cycle retry only if the direct handshake remains in the video view. It then sets maximum speed and proceeds to metadata. The same helper is used after video capture.
 285
 286 `RecoveryKick`, repeated synthetic LBA-zero reads, and generic automatic media-auth kicks are not part of this path. They belong only to a separate experimental modified-firmware campaign and are currently out of scope.
 287
 288
 289 ## GDR-8050L Xbox handshake transport
 290
 291 Candidate21 keeps the proven Windows `UnlockDrive()` command sequence but sends
 292 its Linux form with `SG_IO`, the direct Linux SCSI pass-through interface. This
 293 preserves each 6-, 10-, and 12-byte CDB length, the Windows 120-second command
 294 timeouts, the 10-second sticky-descrambling timeout, transfer direction, sense
 295 data, host status, and driver status. Every handshake command emits an
 296 `[XBOX-SGIO]` record to both the live console and persistent FriiDump log.
 297
 298 This is transport parity only. It does not add `RecoveryKick`, a generic media
 299 authentication kick, synthetic LBA-zero reads, or any modified-firmware-only
 300 recovery behavior.