Files
libfreemkv/docs
Matthew Jackson 8949b81dfc macos(drive): discover empty-tray drives via IOKit registry-id selectors
Empty-tray optical drives couldn't be opened because the macOS backend
resolved drives by media-child `BSD Name`, which doesn't exist without a
disc loaded. Result: `list_drives()` returned nothing for a drive with no
media, and any attempt to `open("disc://")` on that state failed.

Fix: enumerate `IOBDServices` directly. With media present, the returned
selector is the familiar `/dev/diskN` path (unchanged). With no media,
the selector is an opaque `ioreg:<registry-id>` string that resolves to
the same IOBDServices entry — Disk Arbitration and unmount are skipped
because there's no media node.

- `src/drive/macos.rs`, `src/drive/mod.rs`, `src/scsi/mod.rs`: threads
  the selector through the transport so empty-tray drives are openable
  without punning it as a filesystem path.
- `src/scsi/macos.rs`, `src/scsi/macos_shim.c`: the C shim now accepts
  both `/dev/diskN` and `ioreg:<id>` in `shim_open_exclusive`, and
  `shim_list_drives` reports the correct selector for each drive.
- `tests/macos_drive_tests.rs` (new): covers empty-tray discovery.
- `docs/drive-access.md`, `docs/scsi-macos.md`: document the two-path
  selector model.

[skip-media]
2026-09-25 12:03:02 -07:00
..

libfreemkv Documentation

Technical documentation for libfreemkv, the open source optical drive library.

Start Here

Disc to Rip: End-to-End Flow — How the library goes from a disc in the drive to decrypted content. Read this first.

Reference

Document What it covers
Architecture Module map, design principles, error codes, platform support
Drive Access Drive, SCSI transport, profiles, unlock, why raw mode is needed
Rip Recovery What this crate owns of the recovery model: single-shot Drive::read, SenseFamily, DiscStream batch halving (the strategy itself moved to freemkv-engine in 1.6.0)
AACS Encryption Key resolution (4 paths), content decryption, bus encryption, SCSI handshake
UDF Filesystem UDF 2.50 with metadata partitions, pointer chain, how files are read from disc
MPLS Playlists Playlist format, play items, STN stream table, coding types
CLPI Clip Info EP map (coarse + fine entries), timestamp-to-sector mapping, extent calculation
API Design Stream API design, PES pipeline, input/output resolution

Reading Order

If you want to understand the whole library:

  1. Disc to Rip — the big picture
  2. Architecture — how modules fit together
  3. Drive Access — how we talk to hardware
  4. UDF → MPLS → CLPI — how disc content is structured
  5. AACS — how encryption works and how we break it

API Documentation

Generated API docs are on docs.rs/libfreemkv.