modem-device
The seam between the driver and a device: trait Device, trait Medium: Device
and the types they speak in. Was modem-backend with one trait Backend
until #117, which split the seam along the planes of
docs/design/device-planes.md and changed no behaviour.
This crate deliberately depends on nothing but async-trait, thiserror and
optional serde — and in particular no Zenoh and no tokio. CI holds the
first with a dependency-graph guard, because the moment this could parse a key
expression the second policy plane invariant I1 forbids would exist. The
absence of tokio is why DeviceEvent is a plain struct rather than a channel:
putting a watch::Receiver on the trait would drag a runtime into the crate
whose entire job is to be the seam.
An out-of-tree backend needs this and nothing else. It is published together
with modem-contract and modem-mgmt, one version for the three (#97); the
history is in CHANGELOG.md.
What an implementor does first
- Pick the plane. A device whose bytes you carry is a
Medium; a device whose bytes the kernel carries is aNetdev. Both are aDevice. - Implement the four required
Mediummethods (capabilities,send,recv,metrics) and say the truth inCapabilities:reliableonly if the hardware never loses (I2), and the SDU sizes the frame really holds.sendblocks to apply backpressure and never splits an SDU (I3, I4). - Run the conformance kit from your own tests:
conformance::device, andconformance::netdevfor a netdev, thenassert_clean. Passing it is what conforming means;udp-medium/tests/conformance.rsis a ten-line example. - Then the defaulted methods, as the device has them:
report,oper,identity,next_event,configuration,actions,close. A device that says nothing about itself is still a legitimate device.
Two things it must never do: retry on its own initiative (I1: there is no
reset, and recovery is a restart, of the device or of the daemon), and
publish a reading it does not have (an absent value, never a zero).
The traits
Device is what the management plane serves — every method defaulted, so a
device that says nothing about itself is a legitimate device. Medium: Device
is the SDU data plane: implementations own everything below the driver —
framing on the air, vendor APIs, contact scheduling, radio state — and nothing
above it. A device whose data plane is the kernel's is a Netdev: Device —
it names its interface, and the lanes never see it (#118, #130).
Device method |
||
|---|---|---|
report() |
defaulted | Sync on purpose — answer from a cache, never from I/O (#49) |
next_event() |
defaulted | Edge-triggered: one Raised, one Cleared, never a repeat (#51) |
close() |
defaulted | Called once, on the way down (#50) |
configuration() |
defaulted | The configuration plane (config::Configure: schema, read-back, apply), None for a device with nothing to configure; the Iridium terminal and the LoRa simulator declare one (#125) |
Medium method |
||
|---|---|---|
capabilities() |
required | Read once at startup to size lanes |
send(lane, sdu) |
required | Must block rather than queue. Backpressure by not returning is what invariant I3 asks for |
recv() |
required | Returns the lane it arrived on, so the driver routes without inspecting the payload |
metrics() |
required | |
configure_lanes(lanes) |
defaulted | What lanes exist, so recv need not guess (#52) |
Netdev method |
||
|---|---|---|
interface() |
required | The interface name, as the kernel spells it (#118) |
close() |
defaulted | Called after every lane stops. A simulator never needs telling; a radio does (#50) |
The defaults are why the conformance kit's decorator check exists: a decorator that forgets one no longer fails to compile, it silently answers for itself.
There is no reset, and that is a decision. A medium that reopened itself
would need a policy for when to retry and when to give up, and a policy inside
the driver is the second policy plane I1 forbids. Recovery is a restart, and
next_event is what tells a supervisor to perform one.
Implementors
fake-medium (three of them) and sbd-medium. sbd-medium is the first to
implement close and next_event for real.
Conformance
modem_device::conformance (#131) is the tests that kept this workspace's
implementors honest, with the medium taken out, so an implementor written
elsewhere runs them from its own suite. Every check returns the Failures it
found rather than panicking — the kit's own tests hand it one deliberately
broken implementor per check — and assert_clean is the one-line form:
let mut f = device.await;
f.extend;
assert_clean;
| Check | What it holds a device to |
|---|---|
device_decorator_forwards, medium_decorator_forwards, netdev_decorator_forwards |
every method of the trait reaches the wrapped device and its answer comes back unchanged |
core |
report, oper, identity agree across two calls; a report with a reading says its age |
events_are_edge_triggered |
the same words with the same edge twice in a row is a repeat, not an edge |
schema_is_valid, effective_within_schema |
names that can be spelled in a key, bounds that do not cross, a read-back inside the schema, no sensitive value in it |
contract_refused |
a contract group answers ConfigError::Contract, naming the restart |
read_back_and_undo |
after apply, effective shows the change; after the Undo, the previous values |
sensitive_never_read_back |
a value written to a sensitive parameter is in no read-back and no Debug |
netdev |
within one presence epoch no counter goes backwards |
Nothing here needs a runtime: the timed checks take a deadline or a tick
future from the caller. What the kit cannot check is that the sync methods do
no I/O; it checks what follows from the contract instead. The wire-level half
— against a running plane — is modem_mgmt::conformance.
Where the rules are
Descriptive; ../docs/architecture.md is normative — §4.8 for the seam, §2 for
the invariants the doc comments cite by number.