Skip to main content

Crate kdi

Crate kdi 

Source
Expand description

KDI host library — identity-first discovery, the bind handshake, acquisition as decoded records, the typed command channel. Everything physical is quarantined in a PRIVATE Link enum: no public trait Transport, and no endpoint number outside a binding module.

Modules§

bundled
The USB3 device driver this crate ships, and where it came from. The provenance table compiles in with or without --features bundled: Cargo packages the whole source, so the bytes travel either way. No gateware image here — Device::open_usb3_configured takes the caller’s. The USB3 device driver this crate ships, its provenance, and the staging that makes it loadable. --features bundled compiles the target platform’s driver into the artifact; the bytes are in this source either way (Cargo packages it all), and tests/provenance.rs hashes them.

Structs§

Acquisition
How to acquire. lanes is the rhd_matrix acquisition-lane mask (ignored where there is no lane register). burst bounds the capture — the only mode where loss cannot happen INSIDE the data: free-running, a host that cannot drain gets an unlocatable hole (contract.yaml:152-157).
AdioAdc
The reply to adio.adc.
AdioDout
The reply to adio.dout.
AdioFb
The reply to adio.fb.
AdioMode
The reply to adio.mode.
Block
One typed section of a record.
Caps
The device’s capability bitmap, read once at bind. The raw word is public so it can be logged or compared verbatim; Caps::has and Caps::iter are how it is read.
ConnectOpts
How to bind. The default is “no capability requirement, the device’s own published ready window”, which is what a caller who has nothing to say should pass.
Device
A bound device: the link, the identity it was opened as, the capability word read at bind, the session’s lease token, and a shadow of every WireIn word this host has written — the shadow is why an unmasked field write cannot silently disarm a neighbouring stream (write_field).
DeviceInfo
A device’s IDENTITY, plus a hint about where it answered. What find hands back and what Device::open takes: a caller names a board by what it is, never by an address.
Filter
What to look for. EVERY FIELD UNSET MEANS ANY — a default Filter matches everything find can reach, and each Some narrows it.
Health
A stream’s backpressure reading. From StreamReader::health, and only meaningful when read after the data it describes.
IdBoards
The reply to id.boards.
IdBoardsEntry
One entry of the id.boards reply’s boards list — declared [{addr: u8, serial: str}].
MultiReader
Several live streams sharing one device borrow, from Device::start_multi. Reading is round-robin and fair: each call advances every stream’s decoder before refilling any, so a fast stream cannot starve a slow one of attention.
PowerStatus
The reply to power.status.
PowerUp
The reply to power.up.
Record
One frame, decoded. No CRC, no magic, no reject token, no descriptor stride.
ReleaseManifest
What a publication attaches beside a bitstream: enough for a program to decide, offline, whether to flash it. Built by tools/gateware_manifest.py from the contract at the release tag’s own commit — the version is derived, never typed.
Reply
A device’s answer. #[must_use] because rc != 0 is returned, never raised: a dropped Reply is a device error nobody looked at.
SdkErrusb3
Which driver call failed, or which symbol was not there. A symbol miss carries the C name it looked for, because that is the only string that identifies it; every other message here names the operation, not the vendor’s entry point.
Stats
What the reader had to recover from, cumulative over the life of the stream. bad_frames is where a decode rejection ends up, and the whole reason Error has no decode variant: a rejected frame is a fact about the link’s quality, not a reason to abandon a recording.
StreamReader
A live stream. OWNS the byte buffer, the partial-frame carry and the decode cursor — which is the whole reason the caller no longer can get them wrong.
SysHello
The reply to sys.hello.

Enums§

Addr
Where the device answers. A HINT resolved from its identity, never part of its name (the Python reference host).
Arg
One argument of a Device::raw_cmd_named call, carrying the JSON type the UDP envelope needs. Int is a JSON number and Text a JSON string; the vUART line renders both as the bare token, so the choice is invisible there and load-bearing here.
Aux
Which auxiliary result of an RHD timestep. Their rows are not adjacent and AuxAdc is a timestep behind the other two; naming them is what keeps a caller out of that arithmetic.
Cap
A capability bit. Branch on these, NEVER on a version comparison.
ChMode
A mode token, 1:1 with the contract’s of: list. One enum for every argument that takes this value set — adio.mode declares it twice and two identical types would be two things to keep in step.
DeviceErr
THE closed device error set. A host switches on this; rc is a platform errno and is informative only — the same “unknown command” is -38 on Linux and -88 on the target.
Error
THERE IS NO DECODE VARIANT, deliberately: a rejected frame is a fact about link quality, not something a caller can act on mid-recording (the Python walk() killed the run over one flipped bit). StreamReader resyncs and counts it; every Error here is transport, host or device.
HostErr
The closed HOST-side set. A conforming library reports these and mints no others — the Python reference minted overrun and timeout, which are in neither published set.
Kind
What one block of a record IS. Append-only and FROZEN: a redefined kind is the one mis-parse nothing on the wire can catch. 0x80-0xff are reserved for private use.
Lease
What this host’s LEASE request did at bind. Unsupported IS NOT A FAILURE: sys.claim is scope: session, and a build without it answers unknown_cmd — treat that as “no such facility” and proceed (contract.yaml:196-202). No NotHeld: busy is refused at bind.
SegBoards
A mode token, 1:1 with the contract’s of: list. One enum for every argument that takes this value set — adio.mode declares it twice and two identical types would be two things to keep in step.
Skew
The device is not one this host may talk to. Refused at BIND, never later: every one of these is a reason the traffic that would follow cannot be trusted.
Stream
A named bulk stream. Independently enabled: one run bit, one burst bound, one pipe and one sticky overrun each.
TransportKind
Which binding a device was found through. usb3 exists only in a build with --features usb3.

Constants§

ARG_CHARSET
Every request token must match this, or a host MUST refuse it WITHOUT sending a byte: the vUART is shared with an ungated human shell, so a CR is command injection and a raw 0x1e forges a reply.
COMMANDS
Every published command with its declared argument order. THE ORDER IS THE WIRE (request.arg_order: declared, kdi/contract.yaml:874), so a host serialising a positional Device::raw_cmd call reads it from here instead of keeping a second copy of the registry — the copy that goes stale is the one that transposes two arguments. The scope: session commands are listed too: they have no typed method, but they are still callable through Device::raw_cmd.
CONTRACT_REV
Every frame carries the contract’s MINOR in contract_rev.
KDI_MAJOR
The contract MAJOR. A device announcing a different one must be refused at bind: majors are not compatible, and the traffic that would follow cannot be trusted.
KDI_MINOR
The contract MINOR. ADDITIVE by definition — a device on a HIGHER minor binds normally, and a host must never do version arithmetic beyond the major equality test.
KDI_VERSION
The contract THIS HOST implements — the host half of a Skew::Major and the only version a caller may compare its own expectations against. The DEVICE’s is Device::kdi(), read off the wire at bind.
READY_TIMEOUT_MS
How long a host must be willing to poll contract_ready before giving up, in milliseconds. A DEVICE property, published so that a slower-booting board does not turn into a fleet of hosts that each need a patch.
REQ_TAG
What every request line on the usb3 message channel starts with, so the shared console can tell a KDI request from something a human typed.
RESP_LEN_DIGITS
Lowercase ASCII hex digits of body length following the sentinel. EXACTLY this many: a short count is not padded, so a reader that scans for a delimiter instead reads garbage.
RESP_MAX_BODY
The device’s reply buffer, in bytes. A reply that does not fit is NOT SENT — pair a missing reply with the sticky console_tx_drop register rather than reading it as a device that answered short.
RESP_SENTINEL
The byte that opens a reply frame on the usb3 message channel. The wire it shares with the human console carries anything, so this — not a newline — is what a reply is found by.
USB3_READ_ALIGNMENT
A pipe read on the usb3 binding must be a multiple of this many bytes. A BINDING property, not a codec constant — an ethernet binding has a different one or none.
WORST_MS
Each command’s declared worst-case latency, in milliseconds. A host derives its reply deadline from this: the contract published the field and no host read it, so every command shared one flat wait and anything slower than it was simply unreachable.

Traits§

Commands
Every published command, typed. Implemented for Device below.

Functions§

find
Discover devices by IDENTITY across every binding this build has, and report what failed: a broken enumerator (an SDK that loads but does not answer, an unreadable discovery dir) is NOT an empty bench. NOT errors: a probe that fails (it IS gone), or a transport this build lacks.
grant_bytes
THE SIGNING BYTES of a sys.unlock grant: the compact, key-sorted JSON the device rebuilds from the three positional args ({"dna":<dna>,"nonce":<nonce>,"tier":"<tier>"}), pinned byte for byte by kdi/vectors/unlock_vectors.json. Sign them with Ed25519 outside this crate — a station tool holds the key — and hand the 64-byte signature to Device::unlock_with.