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