FriiDump 0.5.3.15: close XGD1 geometry and lead-in capture

[friidump.git] / docs / XBOX.md

# Xbox disc support

This version adds a native Xbox/XGD disc path to FriiDump. It uses the selected
optical drive directly through MMC/SCSI commands. The only extra Xbox metadata
written by FriiDump is optional dump metadata such as PFI/DMI binary captures
and the redump-style JSON descriptor.

## Supported Xbox drive profiles

- `HL-DT-ST DVD-ROM GDR8050L`
  - Detected as an Xbox-capable drive.
  - Keeps the visible DVD-video view during detection so `-i` can capture video L0/L1.
  - Runs the Xbox challenge-table handshake only when the dumper needs the
    unlocked game/XDVDFS view.
  - Enables sticky descrambling with Mode Select page `0x31` after the unlock.
- `HL-DT-ST DVD-ROM GDR3120L` / `GDR-3120L`
  - Detected as an Xbox-capable drive.
  - Uses the DiscImageCreator-style `FF 08 01` feature-list and lock-state
    command family.
  - For redump-style `-i`, FriiDump tries lock state `0` first to capture the
    visible/video view, then lock state `2` / wxripper state to read the game
    view.
  - The GDR-8050L challenge-table handshake is not applied to this model.

Samsung/Kreon-style candidates such as `TS-H352C`, `TS-H353A`, `SH-D162C`,
`SH-D162D`, `SH-D163A`, and `SH-D163B` are recognized as drive profiles, but
are not automatically redirected into Xbox mode. Force Xbox mode with `-T 4`
when testing those drives and firmware that supports the `FF 08 01` command
family.

Other drives continue to use FriiDump's original drive command/method logic for
ordinary GameCube, Wii, Wii DL, or DVD dumps. If Xbox mode is explicitly forced
with `-T 4` on a drive that is not wired into the Xbox unlock backend, FriiDump
now refuses the run instead of falling back to GC/Wii methods.

For ordinary DVD-ROM media, use `-D` / `--dvd` as a clear alias for `-T 3`:

```sh
friidump -d <drive> -D -i dvd.iso
```

That DVD mode is available to all drives and stays on FriiDump's original
DVD/raw/ISO dumping path. It does not run Xbox unlocks or write Xbox metadata.

## Recommended commands

### Redump-style Original Xbox/XGD1 ISO

```sh
friidump -d <drive> -T 4 -i xbox.iso
```

For Xbox/XGD media, `-i` reconstructs a redump-style 2048-byte-sector image. It
is not just a game-partition dump. For retail dual-layer media the layout is:

- video L0 at output LBA `0`, read from the visible DVD-video view;
- pregame padding up to output LBA `198144`;
- a 32-sector game lead-in at output LBA `198144`;
- unlocked game/XDVDFS data beginning at output LBA `198176`;
- postgame padding;
- video L1 tail at output LBA `3820720`, captured from the visible DVD-video view
  before the unlock.

When available, FriiDump also writes these files next to the ISO:

- `<name>.pfi.bin` - READ DVD STRUCTURE format `0x00` / Physical Format
  Information;
- `<name>.dmi.bin` - READ DVD STRUCTURE format `0x04` / Disc Manufacturing
  Information;
- `<name>.redump.json` - JSON metadata describing the layout, hashes, drive
  profile, PFI/DMI filenames, and lead-in capture status.

For the GDR-8050L redump path, the 32-sector game lead-in is captured from
unlocked source LBA `0..31` before copying XDVDFS data from source LBA `32`.
FriiDump 0.5.3.13 proved this placement with cache-aligned raw-sector IDs. The
native libfriidump path retains per-sector zero-fill only for a genuinely
unreadable lead-in sector and records the read/zero-fill counts; the reference
Xbox path treats failure to capture the proven lead-in as a dump failure.

FriiDump also records a `discimagecreator_reference` section in the JSON. The
redump-style constants are checked against DiscImageCreator's Original
Xbox/XGD1 model: `XBOX_SIZE = 3820880`, `XBOX_LAYER_BREAK = 1913776`, DVD start
PSN `0x30000`, and Xbox/game start PSN `0x60600`. That gives the FriiDump
virtual layout start at output LBA `0x30600` / `198144`, matching the
DiscImageCreator layout model for Original Xbox discs.

For the GDR-8050L redump-style path, FriiDump follows the original dumper's
state order: primary handshake, media-cycle, re-handshake, game metadata/auth
probe, media-cycle back to the visible DVD-video view, video L0/L1 capture, final
handshake, game lead-in/game data write, metadata write, and STOP UNIT cleanup.

For GDR-3120L/Kreon-style vendor-lock-state drives, FriiDump sends lock state
`0` before the video-view capture and lock state `2` before the game-view read.

### Game partition XISO

```sh
friidump -d <drive> -T 4 -X xbox.xiso
```

`-X / --xiso` writes only the game partition as an XISO-style image. The XISO
path unlocks first when needed, probes XDVDFS at LBA `306112`, then falls back
to LBA `32`. For dual-layer retail-style media it copies through LBA `1913920`
using `1913920 - startLba` source sectors. For single-layer/homebrew-style media
it uses `VolumeSize / 2048` from the XDVDFS header.

Like `-i`, XISO mode attempts to read the 32-sector game lead-in and falls back
to per-sector zero-fill only where reads fail.

`--xiso` is a separate output mode and cannot be combined with `-i`, `-r`, or
`-a` in one run.

## Read-only XGD1 logical-boundary probe

FriiDump 0.5.3.11 adds a Windows-only diagnostic that does not create or alter
an ISO:

```powershell
friidump -d f: --xgd1-layout-probe "docs\debug\xgd1-layout-probe.json"
```

The mode is currently restricted to the GDR-8050L challenge-handshake profile.
It performs the following evidence sequence:

1. Record the entry READ CAPACITY(10) state.
2. Cycle the tray and verify the exact 6,992-sector locked/video capacity.
3. Probe selected boundary LBAs with one-sector READ(10) and READ(12).
4. Apply the established full Xbox handshake and verify the unlocked/game
   capacity.
5. Probe the corresponding unlocked-source and capacity-edge LBAs.
6. Restore the locked/video entry state when the run began locked.
7. Atomically publish the JSON report and issue STOP UNIT.

Each command record includes the Win32 result, SCSI status, sense
key/ASC/ASCQ, all-zero/nonzero classification, SHA-1, and full 2048-byte sector
data when the read succeeds. Expected out-of-range failures are evidence and
do not by themselves invalidate the report.

This is a logical-read probe, not a physical-sector dumper. It does not assert
that inaccessible filler is zero, does not replace the current synthetic
ranges, and does not promote the reconstructed XGD1 image to Redump identity.

## GDR-8050L handshake sequence

The GDR-8050L path performs this sequence when switching from visible DVD-video view
to unlocked game view. This method is credited to scsi1.pas / "XBOX 1
DVD-Drive unlocker tool v0.1" by The Specialist and the xboxhacker.net
contributors credited in that source.

1. READ CAPACITY(10).
2. MODE SENSE(10), page `0x3E`.
3. READ DVD STRUCTURE, format `0xC0`, using CDB
   `AD 00 FF 02 FD FF FE 00 06 64 00 C0`.
4. If needed, fall back to the Hitachi-family vendor challenge-table command
   `0xFD`.
5. Decode the challenge table with SHA-1 and RC4.
6. MODE SELECT(10) first challenge.
7. MODE SENSE(10) verify.
8. MODE SELECT(10) second challenge.
9. MODE SENSE(10) verify.
10. MODE SELECT(10) partition-1 unlock.
11. MODE SELECT(6), page `0x31`, to enable sticky descrambling.
12. READ CAPACITY(10) again as an observation.  Like the original dumper, this
    verification is diagnostic; the later XDVDFS probe determines whether the
    game view is actually available.

## GDR-3120L / Kreon-style vendor unlock sequence

The GDR-3120L/Kreon-style path follows the DiscImageCreator `FF 08 01` command
family:

1. `FF 08 01 10` - get feature list; valid replies begin with `A55A 5AA5`.
2. `FF 08 01 11 00` - set lock state 0 / visible DVD-video view when redump-style `-i`
   needs the visible/video area.
3. `FF 08 01 11 02` - set lock state 2 / wxripper state when the game/XDVDFS
   view is needed.
4. `FF 08 01 15 00` - disable vendor error-skip before dumping.
5. READ CAPACITY(10), READ DVD STRUCTURE, and READ(10) are then used by the
   selected dump layout.

## GC/Wii and candidate drive list

Hitachi-LG GC/Wii support list reflected in this branch:

- `GDR-8082N`, `GDR-8083N`, `GDR-8084N`
- `GDR-8161B`, `GDR-8162B`, `GDR-8163B`, `GDR-8164B`
- `GCC-4160N`, `GCC-4240N`, `GCC-4243N`, `GCC-4244N`, `GCC-4247N`
- `GDR-8085N`, `GDR-8087N`, and `GCC-4246N` are probable but not confirmed here.
- `GCC-4241N` and `GCC-4242N` are capable but known to have many errors.

DiscImageCreator reference candidates noted but not fully cloned here:

- XBOX/XBOX 360 Kreon firmware candidates: `TS-H353A`, `TS-H352C`, `SH-D162C`,
  `SH-D162D`, `SH-D163A`, `SH-D163B`.
- XBOX/XBOX 360 swap candidate: `GSA-4163B`.
- HD-DVD and BD are DiscImageCreator-supported disc classes, but this FriiDump
  branch does not claim DiscImageCreator-equivalent HD-DVD/BD feature coverage.

Implementation map:

- MMC/SCSI helpers, the GDR-8050L unlock path, and the `FF 08 01` vendor
  helpers: `libfriidump/dvd_drive.c`
- Xbox disc detection/unlock timing: `libfriidump/disc.c`
- Redump-style ISO and XISO dumping: `libfriidump/dumper.c`

### GDR-8050L reference path

On Windows, GDR-8050L `-i` and `-X` are dispatched to a copied-in reference implementation from jtryba's original Xbox dumper (`main.c`, `utils.c`, `unlock.c`, and helpers). This preserves the original state-machine order instead of approximating it in FriiDump's generic read loop. It also preserves the reference timing sleeps: tray-cycle 3000 ms, readiness settle 1500 ms after success or 10000 ms fallback, RefreshVolume's 1000 ms wait, and the explicit post-refresh 2000 ms settle.

For GDR-8050L, bare `-i` derives `Title[MediaID].iso` from the XBE title and DMI media ID, and bare `-X` derives `Title[MediaID].xiso`. Supplying `-i <file>` or `-X <file>` is an explicit filename override. FriiDump prepares the game view for that title/media-ID discovery with state-aware READ CAPACITY classification: it reuses an already-unlocked view, otherwise it attempts one direct full handshake without a media transition. A tray-cycle-and-retry path exists only as recovery when direct verification fails.

FriiDump 0.5.3.8 returns the reference dumper's actual finalized ISO filename,
byte count, CRC32, MD5, SHA-1, and SHA-256 to the common Redump verifier after a
successful option-1/full-disc dump. This supports both explicit `-i <file>` and
bare `-i` with XBE/DMI-derived names without hashing the 7.29 GiB file twice.
Use `--redump-report <file>` to publish the same atomic schema-2 evidence record
used by GameCube/Wii paths.

The current XGD1 image map contains unresolved zero-filled pregame and postgame ranges.
Accordingly, `NO EXACT MATCH` is a valid evidence result even when all readable
sectors were acquired successfully. The verifier reports acquisition evidence
and archive identity as separate claims. `-X` remains outside DAT verification
because XISO is not a full Redump disc image.

GDR-3120L remains on the separate `FF 08 01` vendor lock/unlock path. Forced Xbox mode on non-supported Xbox unlock profiles is rejected rather than routed through FriiDump GC/Wii fallback methods.



## XGD1 cache-aligned raw-ID geometry correction (0.5.3.13)

The first 0.5.3.12 hardware report contained a mixture of valid physical IDs
and stale/block-start cache entries. The corrected probe now performs the same
zero-transfer READ(12) flush and 16-sector block alignment used by the proven
modified-GDR-8050L Method 8 path. It dumps only the raw 12-byte header and
four-byte EDC for the selected slot, decodes the layer bit, normalizes layer-1
PSNs by 24-bit complement, and compares each sample with its mapped full-output
LBA.

The live 0.5.3.13 run matched all 13 selected samples and set
`physical_geometry_resolved` true. The result proves the physical placement of
the visible video ranges, the full unlocked game range, and the omitted
pregame/postgame spans. It does not establish the byte content of the omitted
filler spans.

## Drive-captured XGD1 game lead-in (0.5.3.14)

The successful 0.5.3.13 geometry report established these adjacent mappings:

- unlocked source LBA `0..31` -> output LBA `198144..198175`, raw PSN
  `0x060600..0x06061F`;
- unlocked source LBA `32` -> output LBA `198176`, raw PSN `0x060620`, where
  the `MICROSOFT*XBOX*MEDIA` XDVDFS descriptor begins.

FriiDump 0.5.3.14 therefore replaces the historical synthetic 32-sector
game-lead-in write with drive capture from source LBA `0..31`. This changes the
full XGD1 output bytes and requires a new live full-disc dump plus Redump DAT
comparison. The 191,312-sector pregame and postgame spans retain zero-filled
placeholder content: their physical geometry is proven, but their inaccessible
byte content is not.

## Logging

The original Xbox reference logger is now the shared FriiDump run logger. Every
run opens a log file before the banner is printed. When an output filename is
known, the log is retargeted to `<output>.log`. If no output filename is known
but a drive is known, it uses `friidump_<drive>.log`; otherwise it uses
`friidump.log`. Xbox reference diagnostics continue to be written to the same
log.

GCC-4243N/GCC-4244N Method 8 split-recovery note
--------------------------------------------------
For HLDS GCC-4243N and GCC-4244N GameCube/Wii dumping, the default Hitachi command-2 / Method-8 path now has three visible recovery layers: the existing Method-8 5-block/window read reconstruction retry loop, the dump-level retry envelope, and a Method-8 split-recovery path for a failed 16-sector block. The split-recovery path reconstructs the failed block by trying 8-sector, 4-sector, 2-sector, then 1-sector streaming chunks, validates the rebuilt 16-sector raw block with the normal unscrambler/EDC check, and only caches/writes it if validation succeeds. All retry and split-recovery messages are mirrored through the shared FriiDump log file, so a failure such as `Dump failed at sectors: N..N+15` should now include whether 8/4/2/1 chunk recovery was attempted and where it failed. Existing Xbox logging remains on the same shared log path; GDR-3120L Xbox support remains on the explicit vendor lock/unlock path.

HLDS 0xE7 DIC profile-layer update
------------------------------------
This branch now classifies HLDS/MN103 0xE7 GC/Wii dumping drives into DIC-style profiles before assigning the FriiDump Hitachi cache reader.  The selected profile is printed in the run log after Command/Method:

- Type1: GCC-4160N/GCC-4240N, cache base 0x00a13000, one 16-sector memory window.
- Type3: GCC-4243N/GCC-4244N/GCC-4246N/GCC-4247N and GDR8083N/GDR8084N, cache base 0x80000000, five 16-sector memory windows.
- Type4: GDR8082N/GDR8161B/GDR8162B/GDR8163B/GDR8164B and related DVD-ROM profiles, cache base 0x80000000, five 16-sector memory windows.
- Type4 GDR-8050L modified 0xE7 test: GDR8050L/GDR-8050L with cross-flashed or modified firmware that adds 0xE7 memdump, cache base 0x80000000, five 16-sector memory windows, Method 8 default for GC/Wii tests.
- Type2_1/Type2_2: GCC-4241N/GCC-4242N are identified as experimental DIC Type2 shapes, but this branch does not yet claim DIC parity for their moving-cache behavior.

The Type1 base address comes from the DIC source behavior for GCC-4160N/GCC-4240N.  Method 8 now honors the selected profile's memory-window count, so Type1 reads/cache-validates one 16-sector block per request instead of assuming the Type3/Type4 five-window cache layout.  GCC-4243N and GCC-4244N remain on Method 8 by default.  GDR-8050L is now split into a special modified-firmware GC/Wii test profile: stock GDR-8050L firmware is still expected to use the Xbox path only, while a cross-flashed/modified GDR-8050L with 0xE7 memdump added can be tested on the Method 8 GC/Wii cache reader.  GDR-3120L Xbox ripping support remains on the separate explicit vendor lock/unlock path.


GDR-8081N experimental 0xE7 probe layer
-----------------------------------------
GDR-8081N is now recognized as an experimental HLDS 0xE7 GC/Wii candidate.
Unlike GDR8082N/GDR816x, it was not in the confirmed DIC dump list, so FriiDump
does not hard-code it as a normal Type4 drive.  It starts as `GDR-8081N
experimental 0xE7 probe` and, during seed retrieval, tries small sector-0
validation reads across these cache profiles:

- Probe A Type4-derived: base 0x80000000, 5 windows.
- Probe B single-window: base 0x80000000, 1 window.
- Probe C Type1-base: base 0x00a13000, 1 window.
- Probe D moving-cache candidate: base 0x7fff7f00, 1 window.

The first candidate that can read/validate sector 0 is selected for the rest of
the run and logged.  If all candidates fail, seed retrieval stops and the log
records each failed probe.  Unsupported/non-HLDS drives now keep zeroed HLDS
profile fields so stale cache-base/window values are not printed.
## FriiDump 0.5.3.9 live-summary closure

The embedded GDR-8050L reference path returns finalized hashes, output size and
sector count, title, media ID, and elapsed evidence to FriiDump.  The final HLDS
summary therefore describes the reconstructed output rather than the locked
6,992-sector view.  GC/Wii seed terminology is marked not applicable for this
Xbox authentication path.  DumpXboxGameDisc no longer spins the drive down
internally; FriiDump performs one final STOP UNIT after Redump verification.

## FriiDump 0.5.3.10 state-aware metadata-entry handshake

The copied GDR-8050L bridge no longer performs the unconditional sequence
`unlock -> tray cycle -> unlock` before title/XDVDFS probing.

Normal entry paths are now:

- already-unlocked entry: verify readiness, reuse the game view, and read title,
  XDVDFS, media ID, and physical metadata;
- locked/video entry: issue one full handshake directly, refresh/read capacity,
  and continue only after the game view is observed;
- recovery only: when direct verification fails, cycle the tray once, retry the
  full handshake once, and fail cleanly if the game view is still absent.

The dump itself still performs one intentional media transition to restore the
locked/video view before VIDEO-L0 and VIDEO-L1 capture, followed by one full
handshake for game/XDVDFS sectors. Therefore the expected normal cold-state
sequence is `unlock -> metadata -> tray cycle -> video -> unlock -> game`, and
an already-unlocked entry omits the first unlock.

XDVD sidecar authentication evidence now distinguishes two separate facts:

- `unlock_requires_media_transition: false`
- `locked_video_view_restore_requires_media_transition: true`

The compatibility field `requires_media_transition` is also `false`; it refers
to authentication/unlock acceptance, not to restoring the locked video view.

## XGD1 raw-sector ID geometry probe (0.5.3.12)

Live 0.5.3.11 evidence closed the ordinary logical-read branch: all 17
successful READ(10)/READ(12) pairs were identical, the locked view stopped at
6991, and the unlocked view stopped at 3431263. Output-space LBAs outside
those capacities returned ILLEGAL REQUEST / LBA OUT OF RANGE (05/21/00).
This means neither READ opcode exposes a hidden logical source for the
synthetic pregame or postgame ranges.

`--xgd1-raw-id-probe <file>` is the next read-only geometry probe. On the
modified GDR-8050L profile it fills the drive cache with a controlled 16-sector
READ(12), dumps the selected 2064-byte raw sector through `E7 48 49 54 01`, and
decodes bytes 1..3 of the raw DVD ID as the physical-sector number. Adjacent
locked and unlocked boundary samples can establish whether the active logical
views map linearly or jump across omitted physical regions.

Raw physical IDs do not reveal the contents of inaccessible filler sectors.
No zero-filled range may be promoted to exact merely because its geometry is
confirmed.


## 0.5.3.15 live closure

The required 0.5.3.14 hardware run completed on the modified GDR-8050L
revision `0012`.

The drive-captured source LBA `0..31` lead-in was independently verified at
output LBA `198144..198175`, and source LBA `32` remained the XDVDFS boundary at
output LBA `198176`.

Final output:

- sectors: `3,820,880`;
- bytes: `7,825,162,240`;
- SHA-256:
  `5995f823c6d67b9e3e3b3e1c2b54e1e036793188bec6b5be4220f559305f53b9`.

The Microsoft Xbox DAT scan returned `NO EXACT MATCH`. Pregame and postgame
geometry is proven, but their inaccessible content remains zero-filled and
unresolved.

Without `--redump-dat-dir`, DAT discovery checks the executable-relative
`redump_dat` directory before the current working directory. This prevents
runner working directories from hiding the packaged DAT set.