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_configuredtakes the caller’s. The USB3 device driver this crate ships, its provenance, and the staging that makes it loadable.--features bundledcompiles the target platform’s driver into the artifact; the bytes are in this source either way (Cargo packages it all), andtests/provenance.rshashes them.
Structs§
- Acquisition
- How to acquire.
lanesis the rhd_matrix acquisition-lane mask (ignored where there is no lane register).burstbounds 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. - Adio
Dout - The reply to
adio.dout. - AdioFb
- The reply to
adio.fb. - Adio
Mode - 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::hasandCaps::iterare how it is read. - Connect
Opts - 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). - Device
Info - A device’s IDENTITY, plus a hint about where it answered. What
findhands back and whatDevice::opentakes: 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
Filtermatches everythingfindcan reach, and eachSomenarrows 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. - IdBoards
Entry - One entry of the
id.boardsreply’sboardslist — declared[{addr: u8, serial: str}]. - Multi
Reader - 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. - Power
Status - 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.
- Release
Manifest - What a publication attaches beside a bitstream: enough for a program to decide, offline,
whether to flash it. Built by
tools/gateware_manifest.pyfrom the contract at the release tag’s own commit — the version is derived, never typed. - Reply
- A device’s answer.
#[must_use]becauserc != 0is returned, never raised: a droppedReplyis a device error nobody looked at. - SdkErr
usb3 - 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_framesis where a decode rejection ends up, and the whole reasonErrorhas no decode variant: a rejected frame is a fact about the link’s quality, not a reason to abandon a recording. - Stream
Reader - 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_namedcall, carrying the JSON type the UDP envelope needs.Intis a JSON number andTexta 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
AuxAdcis 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.modedeclares it twice and two identical types would be two things to keep in step. - Device
Err - THE closed device error set. A host switches on this;
rcis 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).StreamReaderresyncs and counts it; everyErrorhere is transport, host or device. - HostErr
- The closed HOST-side set. A conforming library reports these and mints no others — the
Python reference minted
overrunandtimeout, 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.
UnsupportedIS NOT A FAILURE:sys.claimisscope: session, and a build without it answersunknown_cmd— treat that as “no such facility” and proceed (contract.yaml:196-202). NoNotHeld:busyis 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.modedeclares 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.
- Transport
Kind - Which binding a device was found through.
usb3exists 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 positionalDevice::raw_cmdcall 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. Thescope: sessioncommands are listed too: they have no typed method, but they are still callable throughDevice::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
hosthalf of aSkew::Majorand the only version a caller may compare its own expectations against. The DEVICE’s isDevice::kdi(), read off the wire at bind. - READY_
TIMEOUT_ MS - How long a host must be willing to poll
contract_readybefore 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_dropregister 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
Devicebelow.
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.unlockgrant: the compact, key-sorted JSON the device rebuilds from the three positional args ({"dna":<dna>,"nonce":<nonce>,"tier":"<tier>"}), pinned byte for byte bykdi/vectors/unlock_vectors.json. Sign them with Ed25519 outside this crate — a station tool holds the key — and hand the 64-byte signature toDevice::unlock_with.