README.md

   1 # FriiDump — Project Frankenstein Branch
   2
   3 FriiDump is a command-line optical-disc dumping tool for Nintendo GameCube,
   4 Nintendo Wii, standard DVD-ROM, and selected Original Xbox/XGD workflows. This
   5 repository preserves the Project Frankenstein development branch based on
   6 FriiDump **0.5.3.5**.
   7
   8 The branch extends the original FriiDump code with:
   9
  10 - analyzer-derived HLDS `0xE7` drive profiles for GameCube/Wii dumping;
  11 - native GDR-8050L and GDR-3120L Xbox/XGD paths;
  12 - redump-style Original Xbox/XGD1 reconstruction and metadata;
  13 - optional game-partition XISO output;
  14 - media preflight, profile reporting, and STOP UNIT cleanup;
  15 - validated Windows/MSVC and Linux/CMake build paths.
  16
  17 The original detailed user documentation remains in [`README`](README).
  18 Xbox-specific behavior is documented in [`docs/XBOX.md`](docs/XBOX.md).
  19
  20 ## Repository status
  21
  22 This is the active canonical Project Frankenstein FriiDump repository. Authority
  23 was accepted at annotated tag `v0.5.3.5-pf1`. The imported baseline is
  24 intentionally conservative: source and
  25 maintained documentation were preserved, while disc images, live logs, compiled
  26 binaries, build directories, result archives, and unrelated reverse-engineering
  27 work were excluded.
  28
  29 The baseline source came from:
  30
  31 ```text
  32 D:\vscode-workspace\friidump
  33 ```
  34
  35 No firmware binaries or disc images belong in this Git repository.
  36
  37 Authority surfaces:
  38
  39 ```text
  40 repository: /srv/project-frankenstein/repos/friidump.git
  41 authority marker: /srv/project-frankenstein/catalog/authority/friidump.json
  42 canonical tag: v0.5.3.5-pf1
  43 ```
  44
  45 ## Build
  46
  47 ### Windows — validated MSVC 32-bit path
  48
  49 The maintained Windows helper invokes the Visual Studio 2019 Build Tools
  50 32-bit environment and compiles from `msvc32_friidump.rsp`:
  51
  52 ```powershell
  53 .\build_msvc32.cmd
  54 ```
  55
  56 Clean generated output with:
  57
  58 ```powershell
  59 .\build_msvc32.cmd clean
  60 ```
  61
  62 The VS Code build tasks are in `.vscode/tasks.json`. The helper currently
  63 expects:
  64
  65 ```text
  66 C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\
  67 ```
  68
  69 ### Linux / Unix — CMake
  70
  71 ```bash
  72 cmake -S . -B build -DBUILD_STATIC_BINARY=ON
  73 cmake --build build
  74 ./build/src/friidump --help
  75 ```
  76
  77 The canonical repository baseline was locally compiled with GCC using this path. The
  78 build completed successfully. One inherited warning remains in
  79 `libfriidump/rs.c` concerning a right-shift count; it is recorded as technical
  80 debt and was not silently changed during repository import.
  81
  82 ## Common commands
  83
  84 List command-line options:
  85
  86 ```text
  87 friidump --help
  88 ```
  89
  90 GameCube/Wii dump using automatic drive/profile detection:
  91
  92 ```text
  93 friidump -d <drive> -8 -s -i game.iso
  94 ```
  95
  96 Standard readable DVD:
  97
  98 ```text
  99 friidump -d <drive> -D -i dvd.iso
 100 ```
 101
 102 Original Xbox/XGD redump-style image:
 103
 104 ```text
 105 friidump -d <drive> -T 4 -i xbox.iso
 106 ```
 107
 108 Original Xbox/XGD game-partition XISO:
 109
 110 ```text
 111 friidump -d <drive> -T 4 -X xbox.xiso
 112 ```
 113
 114 Consult [`README`](README), [`docs/options`](docs/options), and
 115 [`docs/XBOX.md`](docs/XBOX.md) before hardware use.
 116
 117 ## Safety and evidence rules
 118
 119 FriiDump issues low-level SCSI/MMC and model-specific vendor commands.
 120
 121 - Use only drives and media you own or are authorized to examine.
 122 - Do not assume two firmware revisions share the same private-command layout.
 123 - Prefer exact analyzer-derived profiles over guessed addresses or legacy
 124   fallbacks.
 125 - Treat live hardware behavior as the final validation boundary.
 126 - Keep firmware, media images, memory dumps, and generated logs outside Git.
 127 - Preserve provenance for every firmware/profile conclusion.
 128
 129 ## Source layout
 130
 131 ```text
 132 src/                 command-line program
 133 libfriidump/         disc, drive, dumping, Xbox, and vendor-command logic
 134 libmultihash/        checksum implementations
 135 docs/                user, Xbox, validation, and historical documentation
 136 .vscode/             maintained Windows build helper and tasks
 137 build_msvc32.cmd     Windows build entry point
 138 CMakeLists.txt       portable build entry point
 139 ```
 140
 141 ## Project boundaries
 142
 143 - **PFES** — engineering specification, decisions, evidence status, and history.
 144 - **xbox-dvd-tools** — firmware acquisition, extraction, analysis, disc tools,
 145   and shared validation utilities.
 146 - **mn103s-emulator** — MN103S CPU/emulator and GDR-8050L emulation work.
 147 - **friidump** — this dumping application and its maintained drive profiles.
 148 - **Firmware archive** — managed server artifacts outside Git.
 149
 150 ## License
 151
 152 FriiDump is distributed under the GNU General Public License, version 2 or
 153 later. See [`COPYING`](COPYING). Existing source-file copyright notices and
 154 authors are preserved.