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