libfreemkv/docs/scsi-mod.md

# src/scsi/mod.rs — relocated internal notes

Overflow detail for internal (non-public) comments in `src/scsi/mod.rs`,
moved here to keep the guard's internal-comment cap. Each section is
pointed to by a short `// See docs/scsi-mod.md — ...` comment at its
original site.

## READ_TIMEOUT_MS calibration

10 s is calibrated from live empirical data on an LG BU40N + Initio 1618L
bridge ripping a UHD with marginal sectors:

- Sustained sequential reads: 3–7 ms
- Cold-start seek + read: up to ~1500 ms
- Successful ECC recovery: 1.6–2.6 sec
- Confirmed unreadable sector: 3.6–8.8 sec (kernel timeout)

10 s catches every legitimate slow read with comfortable margin and
short-circuits truly bad sectors at ~10 s rather than letting the kernel
mid-layer escalate for 30 s+.

Pre-0.13.21 this was 1.5 s, which forced the kernel mid-layer to time out
*normal* reads (cold-start often takes ~1.5 s) and run its full ABORT
TASK / LUN RESET / BUS RESET escalation while userspace kept submitting
fresh reads. The Initio bridge couldn't drain the resulting command queue
and entered a wedge state that only physical replug recovered — proven by
the v0.13.18 + v0.13.20 live tests.

Consumed only by the ripping read path (`drive::read`); gated so a
transport-only build doesn't warn on an unused const.

## READ_RECOVERY_TIMEOUT_MS history

Matches `sg_dd`'s 60 s ceiling: long enough that any sector the drive can
recover at all gets the time to do so, short enough that an unresponsive
bus is detected before the per-range watchdog fires.

In practice failed reads return in 1–4 s (the drive itself gives up on
uncorrectable ECC before the timeout); the 60 s value is a safety
ceiling, not a steady-state cost.

Historical note (2026-05-08): briefly lowered to 2 s with a 5x inline
retry loop in `freemkv_engine::recovery::patch` to mimic the kernel
`sr_mod` driver's auto-retry pattern. The synthetic logic worked but on
the live drive each "2 s" read paid ~1.5 s of kernel SCSI mid-layer
error escalation on top, so 5x retries took ~17 s per LBA and triggered
MAX_RANGE_SECS after 4 sectors — pushing recovery to 0/22 ranges (worse
than the 0/22 baseline of v0.17.3 single-shot at 60 s, since that at
least visited every range). Reverted; the kernel-auto-retry approach is
being pursued via a `/dev/sr0` pread fallback instead.

## checked_cdb_len rationale

Under SPC-4 the opcode's group code (bits 7-5 of byte 0) fixes the CDB
length, so dropping the tail bytes does not produce a shorter form of the
same command — it produces a DIFFERENT command with a different meaning
for the bytes that remain. The drive will usually execute it and return
GOOD status with data for a request the caller never made: a silently
wrong result, on the transport layer everything else in the crate sits
on.

Lives here, shared by all three platform backends, so the guard cannot
drift per platform (it previously truncated on Linux and Windows while
erroring on macOS — the "works on my platform, not theirs" class).

An EMPTY CDB is rejected here too. `ScsiTransport` is a public trait, so
an out-of-crate caller can pass one; every backend then either indexes
`cdb[0]` (a panic out of a public API) or hands the driver a zero-length
command descriptor, which under SPC-4 is not a command at all. That
guard used to exist ONLY in the Linux backend — macOS and Windows had
nothing — which is the same per-platform drift this helper exists to
prevent.

## parse_sense format details

Handles both response-code formats SPC-4 mandates:

- **Descriptor format** (response code `0x72` / `0x73`):
  - sense key = `sense[1] & 0x0F`
  - asc = `sense[2]`
  - ascq = `sense[3]`
- **Fixed format** (response code `0x70` / `0x71` and any unknown code
  per SPC-4 §4.5.3):
  - sense key = `sense[2] & 0x0F`
  - asc = `sense[12]`
  - ascq = `sense[13]`

`sb_len_wr` is the number of bytes the transport actually wrote into
`sense`. When the buffer is too short for the relevant fields we return
[`ScsiSense::NONE`] for the missing pieces rather than reading
uninitialised memory. The minimum useful sense reply is 4 bytes
(descriptor, to reach ASCQ at offset 3) or 14 bytes (fixed, to reach
ASC/ASCQ at offsets 12/13).

Pure function — same parse on every platform backend (Linux SG_IO, macOS
IOKit, Windows SPTI) so a regression here would silently mis-route SCSI
errors on all three OSes simultaneously.

## is_marginal detail

- `MEDIUM ERROR` (3) — canonical bad-sector signal
- `NOT READY` (2) — on many drives (notably BU40N), this is the dominant
  response for unreadable sectors (ASC 04/3E, 04/01, etc.)
- `ABORTED COMMAND` (B) — transient; retry usually works
- `RECOVERED ERROR` (1) / `NO SENSE` (0) — drive is healthy and either
  recovered the data or has no specific fault to report

## max_transfer_bytes Windows rationale

The Windows backend overrides the 1 MiB default with the adapter's real
`MaximumTransferLength` (queried via `IOCTL_STORAGE_QUERY_PROPERTY`): a
16 MiB READ that exceeds the adapter limit makes `DeviceIoControl` fail
outright, which freemkv then mis-reads as a transport failure and falls
back to slow, log-spamming tiny reads. Chunking to this limit fixes
that. Linux/macOS keep the 1 MiB default (well within any real
`max_sectors_kb`).

## drive_has_disc no-recovery rationale

A single TUR is issued; nothing else. No SCSI bus reset, no USB device
reset, no retry is attempted in-library (the USB-reset escalation was
removed in 0.13.4 after it was shown to deepen rather than clear the
wedge). No SCSI primitive is exposed to outside crates — autorip /
freemkv CLI / bdemu use this single function for the entire "is there a
disc?" decision.

## scsi module reset history

A top-level `scsi::reset()` wrapping platform reset in a
thread+recv_timeout used to live here; removed in 0.13.6 along with the
SG_SCSI_RESET / STOP+START UNIT escalation it existed to guard.

USB-layer recovery (`scsi::usb_reset()`) was rolled back in 0.13.4: on
the LG BU40N the USB reset itself succeeds but firmware below the bridge
stays locked until unplug-replug. See git tag `v0.13.3`.

The only hardware-touching APIs autorip + freemkv CLI use outside the
rip path: a one-shot `list_drives()` enumeration and a single-TUR
`drive_has_disc(path)`. `Drive::open`/`init()`/`Disc::scan` stay heavy.

## align_up mask semantics

`mask` is a *mask*, not a power-of-two alignment value: `0` means "no
alignment requirement" (any address is fine), `1` means 2-byte, `3` means
DWORD (4-byte), `7` means 8-byte, etc. — always one less than the
required alignment. An address is acceptable iff `(addr & mask) == 0`.

Returns the smallest `addr >= p` with `(addr & mask) == 0`. The standard
branch-free idiom `(p + mask) & !mask` works for any valid (`2^n - 1`)
mask, including `mask == 0` (where it is the identity).

Lives here, compiled on every platform, so the Windows SPTI bounce
buffer in `windows.rs` can share it and so the arithmetic gets unit
coverage on macOS/Linux CI even though the SPTI path only builds on
Windows.