README.md

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