Matthew Jackson
3db4106253
Disc::sweep, Disc::patch, Disc::copy, SweepOptions and PatchOptions have zero occurrences in src/ — recovery moved to freemkv-engine — but they were still documented in 30 places across README.md, TROUBLESHOOTING.md, six files under docs/, seven src/ doc comments and a Cargo.toml comment. README.md is the crate's GitHub front page and carried a full multi-pass code example that cannot compile. Two of the src/ references were intra-doc LINKS to deleted items ([`disc::Disc::copy`], [`disc::Disc::patch`] in scsi/mod.rs). They produced no warning on a normal `cargo doc` only because they sit on pub(crate) items; `--document-private-items` reports both, and they are gone now. The README example is deleted rather than rewritten against the engine's API: libfreemkv documenting a downstream crate's API on its own front page is the drift that produced this, and it cannot even depend on it. The src/ references become plain code spans naming freemkv_engine::recovery::* — deliberately not links, for the same reason. docs/rip-recovery.md was 202 lines about relocated code. It now documents only what this crate owns — Drive::read, SenseFamily, DiscStream's adaptive batch halving — plus the read-path design constraints, which belong with the code that enforces them, and points at freemkv-engine/src/recovery/ for the strategy. api-design.md's module tree is regenerated from the real src/disc/ and src/drive/ layouts instead of hand-patched; it had listed sweep.rs, patch.rs, mapfile.rs and read_error.rs, none of which exist. Three stale facts surfaced while rewriting and are corrected: the read timeouts are 10 s / 60 s, not the documented 1.5 s / 30 s; Drive::reset and SgIoTransport::reset no longer exist at all, so "no SCSI reset from any read path" is now stated as the stronger fact it has become; and verify_title, listed as a progress-emitting operation, was removed entirely. CHANGELOG.md keeps its references — those are the historical record of the releases that shipped the API.
1.8 KiB
1.8 KiB
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:
- Disc to Rip — the big picture
- Architecture — how modules fit together
- Drive Access — how we talk to hardware
- UDF → MPLS → CLPI — how disc content is structured
- AACS — how encryption works and how we break it
API Documentation
Generated API docs are on docs.rs/libfreemkv.