README.md

   1 # FriiDump — Project Frankenstein Branch
   2
   3 ## FriiDump 0.5.3.16-pf1 Linux Xbox DMI boundary correction
   4
   5 Candidate20 proved the complete Linux GDR-8050L Xbox command and data path:
   6 direct SG_IO challenge delivery, both game-view transitions, XDVDFS metadata,
   7 drive-captured game lead-in, partial GAME-XDVDFS output, controlled
   8 cancellation, hashes, native reporting, and STOP UNIT.
   9
  10 FriiDump 0.5.3.16-pf1 preserves that exact Windows-sequence control flow and
  11 SG_IO handshake. It corrects one remaining MMC boundary: standard READ DVD
  12 STRUCTURE uses CDB byte 7 for the Format field. Candidate20 incorrectly wrote
  13 the format to byte 11 (Control), so DMI format `0x04` was not captured and the
  14 media ID remained empty.
  15
  16 The release also adds persistent PFI/DMI capture diagnostics and a source
  17 contract that compares the portable request against the proven copied Windows
  18 `GetMediaID()` request.
  19
  20 The generic Xbox path still contains no RecoveryKick, generic media-auth kick,
  21 or synthetic LBA-zero recovery sequence.
  22
  23 Linux vendor-command work continues to require a normal-user process with
  24 `cap_sys_rawio=ep` on the exact validated executable. Rebuilding or replacing
  25 the executable clears that capability.
  26
  27 See [`docs/LINUX.md`](docs/LINUX.md) before Linux hardware use.
  28
  29 ## Exact-release Linux hardware validation
  30
  31 The exact FriiDump 0.5.3.16-pf1 Linux executable was validated on two
  32 GameCube paths after release publication:
  33
  34 - an `HL-DT-ST CDRW/DVD GCC4244 B101` completed profile selection, all 20 seed
  35   blocks, a controlled partial read, cancellation, native reporting, profile
  36   reporting, and STOP UNIT;
  37 - a physical GDR-8163B cross-flashed with modified GDR-8050L `0012` firmware
  38   completed the modified `0xE7` path, all 20 seed blocks, a controlled partial
  39   read, cancellation, native reporting, profile reporting, and FriiDump's
  40   internal STOP UNIT.
  41
  42 The validated cross-flashed unit had to start with a readable Video DVD before
  43 it identified as `HL-DT-ST DVD-ROM GDR8050L 0012`. The drive stayed powered and
  44 connected while the disc was changed to Sonic Mega Collection (US). Linux host
  45 media probing was temporarily quarantined for that run because earlier
  46 background reads had blocked the USB/SCSI path.
  47
  48 See
  49 [`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)
  50 for the exact evidence identities and validation limits.
  51
  52 ## Candidate11 Linux Xbox parity baseline
  53 Candidate11 begins the Linux parity campaign without replacing the validated
  54 Windows/MSVC GDR-8050L path. The Windows copied-reference implementation remains
  55 unchanged for challenge drives. Linux now uses the existing portable MMC/Xbox
  56 dump path with a shared XDFS/XBE metadata reader, XBE-derived default filenames,
  57 exact native-report result handoff, partial/full hashes, and consistent Xbox
  58 title, media ID, and region reporting.
  59
  60 Candidate11 subsequently completed real Linux GameCube validation on a
  61 GCC-4244 B101, including an exact full-dump hash match. Candidate12 retains that
  62 transport and dump behavior while correcting resource discovery and evidence
  63 wording. The development-only XGD1 layout and raw-ID probes remain separate from
  64 ordinary Linux ISO/XISO user paths.
  65
  66 FriiDump is a command-line optical-disc dumping tool for Nintendo GameCube,
  67 Nintendo Wii, standard DVD-ROM, and selected Original Xbox/XGD workflows. This
  68 repository preserves the Project Frankenstein release line through
  69 FriiDump **0.5.3.16-pf1**.
  70
  71 The branch extends the original FriiDump code with:
  72
  73 - analyzer-derived HLDS `0xE7` drive profiles for GameCube/Wii dumping;
  74 - native GDR-8050L and GDR-3120L Xbox/XGD paths;
  75 - redump-style Original Xbox/XGD1 reconstruction and metadata;
  76 - optional game-partition XISO output;
  77 - media preflight, profile reporting, and STOP UNIT cleanup;
  78 - optional atomic `friidump-test-result.v1` compatibility evidence reports;
  79 - validated Windows/MSVC and Linux/CMake build paths.
  80
  81 The original detailed user documentation remains in [`README`](README).
  82 Xbox-specific behavior is documented in [`docs/XBOX.md`](docs/XBOX.md).
  83
  84 ## Repository status
  85
  86 This is the active canonical Project Frankenstein FriiDump repository.
  87 FriiDump 0.5.3.16-pf1 incorporates the accepted native-reporting campaign,
  88 Linux raw-I/O authorization boundary, GameCube/Linux parity work, and the
  89 GDR-8050L Linux Xbox DMI correction.
  90
  91 Release authority is the annotated tag `v0.5.3.16-pf1`. Verify its live tag
  92 object, peeled commit, and tree before treating a checkout or archive as
  93 canonical.
  94
  95 Disc images, live logs, compiled binaries, build directories, result archives,
  96 and unrelated reverse-engineering work remain outside this repository.
  97
  98 Authority surfaces:
  99
 100 ```text
 101 repository: /srv/project-frankenstein/repos/friidump.git
 102 authority marker: /srv/project-frankenstein/catalog/authority/friidump.json
 103 canonical tag: v0.5.3.16-pf1
 104 ```
 105
 106 ## Build
 107 ### Windows — validated MSVC 32-bit path
 108
 109 The maintained Windows helper invokes the Visual Studio 2019 Build Tools
 110 32-bit environment and compiles from `msvc32_friidump.rsp`:
 111
 112 ```powershell
 113 .\build_msvc32.cmd
 114 ```
 115
 116 Clean generated output with:
 117
 118 ```powershell
 119 .\build_msvc32.cmd clean
 120 ```
 121
 122 The VS Code build tasks are in `.vscode/tasks.json`. The helper currently
 123 expects:
 124
 125 ```text
 126 C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\
 127 ```
 128
 129 ### Linux / Unix — CMake
 130
 131 ```bash
 132 cmake -S . -B build -DBUILD_STATIC_BINARY=ON
 133 cmake --build build
 134 ./build/src/friidump --help
 135 ```
 136
 137 The build prints a warning that Linux vendor-command hardware paths require a
 138 separate, explicit `CAP_SYS_RAWIO` installation step. After validating the
 139 binary:
 140
 141 ```bash
 142 bash ./validation/friidump-linux-rawio-capability.sh install   ./build/src/friidump
 143 ```
 144
 145 Run FriiDump as the normal user, not with `sudo`. One inherited warning remains
 146 in `libfriidump/rs.c` concerning a right-shift count; it is recorded as technical
 147 debt and was not silently changed during repository import.
 148
 149 ## Common commands
 150
 151 List command-line options:
 152
 153 ```text
 154 friidump --help
 155 ```
 156
 157 GameCube/Wii dump using automatic drive/profile detection:
 158
 159 ```text
 160 friidump -d <drive> -8 -s -i game.iso
 161 ```
 162
 163 Standard readable DVD:
 164
 165 ```text
 166 friidump -d <drive> -D -i dvd.iso
 167 ```
 168
 169 Original Xbox/XGD redump-style image:
 170
 171 ```text
 172 friidump -d <drive> -T 4 -i xbox.iso
 173 ```
 174
 175 Original Xbox/XGD game-partition XISO:
 176
 177 ```text
 178 friidump -d <drive> -T 4 -X xbox.xiso
 179 ```
 180
 181 Native compatibility reports are created automatically in the working
 182 directory using the log filename. To override the destination directory:
 183
 184 ```text
 185 friidump -d <drive> -8 -s -i game.iso --report-dir reports
 186 ```
 187
 188 Consult [`README`](README), [`docs/options`](docs/options),
 189 [`docs/XBOX.md`](docs/XBOX.md), and
 190 [`docs/NATIVE_REPORTS.md`](docs/NATIVE_REPORTS.md) before hardware use.
 191
 192 ## Safety and evidence rules
 193
 194 FriiDump issues low-level SCSI/MMC and model-specific vendor commands.
 195
 196 - Use only drives and media you own or are authorized to examine.
 197 - Do not assume two firmware revisions share the same private-command layout.
 198 - Prefer exact analyzer-derived profiles over guessed addresses or legacy
 199   fallbacks.
 200 - Treat live hardware behavior as the final validation boundary.
 201 - Keep firmware, media images, memory dumps, and generated logs outside Git.
 202 - Preserve provenance for every firmware/profile conclusion.
 203
 204 ## Source layout
 205
 206 ```text
 207 src/                 command-line program
 208 libfriidump/         disc, drive, dumping, Xbox, and vendor-command logic
 209 libmultihash/        checksum implementations
 210 docs/                user, Xbox, validation, and historical documentation
 211 .vscode/             maintained Windows build helper and tasks
 212 build_msvc32.cmd     Windows build entry point
 213 CMakeLists.txt       portable build entry point
 214 ```
 215
 216 ## Project boundaries
 217
 218 - **PFES** — engineering specification, decisions, evidence status, and history.
 219 - **xbox-dvd-tools** — firmware acquisition, extraction, analysis, disc tools,
 220   and shared validation utilities.
 221 - **mn103s-emulator** — MN103S CPU/emulator and GDR-8050L emulation work.
 222 - **friidump** — this dumping application and its maintained drive profiles.
 223 - **Firmware archive** — managed server artifacts outside Git.
 224
 225 ## License
 226
 227 FriiDump is distributed under the GNU General Public License, version 2 or
 228 later. See [`COPYING`](COPYING). Existing source-file copyright notices and
 229 authors are preserved.
 230
 231 ## FriiDump 0.5.3.16-pf1 Xbox Linux scope
 232
 233 Candidate21 preserves Candidate20's successful SG_IO Xbox handshake and
 234 Windows state-machine order. The only functional correction is the standard
 235 READ DVD STRUCTURE Format byte used for PFI/DMI capture. The mode-select-6
 236 sticky-descrambling command remains evidence-bearing and non-authoritative:
 237 final READ CAPACITY plus XDVDFS readability determine whether game view was
 238 established.