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) |
oper() |
defaulted | RFC 2863's operational status, with a reason and whether it is recoverable (#121) |
identity() |
defaulted | RFC 8348's fields and the equipment identifier; never a subscriber's (#122, I5) |
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) |
actions() |
defaulted | Operator actions: explicit, costed, never scheduled (#129) |
security() |
defaulted | What the device guarantees about the bytes it carries, as SecurityProperties — never a boolean (I6, #164) |
counters() |
defaulted | Named counters beyond the fixed vocabulary; published only under subjects the registry declares (#157, #164) |
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) |
statistics() |
defaulted | The kernel's counters, RFC 8343's names where Linux keeps exactly that counter (#130) |
epoch() |
defaulted | The presence epoch: moves on a re-enumeration or a counter seen to decrease (#130) |
destinations() |
defaulted | The neighbours the radio reports it can reach, None for a device with no such notion (#137) |
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.
Layers
A layer (#157, docs/design/sdu-layers.md) is what sits between the
driver's scheduler and a Medium when a deployment wants encryption, a peer
address on a shared channel, or fragmentation below Zenoh's handshake: the
layer::Layer trait, a synchronous transform over opaque SDUs with no I/O of
its own. One SDU going down becomes zero or more frames (encode), one frame
coming up zero or more SDUs or a counted refusal (decode), time passing
whatever its timers owe (tick, with the next deadline). It declares what it
does to the capabilities below it, maps the lanes asked of it onto the lanes it
asks below, says what it guarantees in SecurityProperties terms given what is
below, and keeps counters under its own kind. The driver's Stack owns every
piece of I/O around a stack of them and is the only Medium the scheduler
sees; a layer never awaits, never owns a task or a socket, and is never a
Medium. Instant is std::time::Instant, handed in, so a test drives a layer
with a clock it advances by hand and this crate still links no tokio.
A layer is its own crate, [package.metadata.zenoh-modem] layer = true, behind
a cargo feature of the driver, off by default. conformance::layer holds it to
the rules below.
Implementors
In this workspace: fake-medium (the null cable, the simulator, the radio
cell, and a netdev stub), sbd-medium, sbd-gateway, udp-medium,
sx1262-medium, netdev-modem, dlep-modem and mm-modem. sbd-medium
was the first to implement close and next_event for real.
Which types are #[non_exhaustive], and the rule
Since 0.3 (#164) the seam follows one rule, so that a new fact a device can state is not a breaking change for every device that cannot:
- A struct an implementor constructs is
#[non_exhaustive], with a constructor taking the facts every implementor has andself-returning setters for the rest. The fields staypub, for reading and for assignment.Capabilities::new(..).arq(..).framing(..),Metrics::new().tx_sdus(..),NetdevStats::new().in_octets(..),Report::new().rssi(..),Counter::new(..),SecurityProperties::new(..).guarantee(..). - An enum a consumer must match exhaustively to stay correct is exhaustive
on purpose. A new
Duplexor a newArqchanges what every scheduler, simulator and reliability claim must do, and should break their builds (#97). - Freshness is the device's. A device withholds a reading it no longer
trusts (returns
None) rather than reporting it with an age;Report::age_msis the age of the whole snapshot, which the management plane applies as one rule (STALE_AFTER). There is no per-reading age, and there will not be one until a device needs it.
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 |
layer::layer, layer::pair |
a layer, or a pair of them (directional keys, addresses): a round trip is the identity; the declared overhead is the observed one at every size; a flipped bit and a truncation are refused where integrity is claimed, a repeat where anti-replay is, and every refusal moves a counter; a deadline announced is kept and nothing is owed unannounced; counters are scoped by kind; an SDU sent on a lane arrives on the matching lane. Synchronous, no runtime; with the reference layers Identity, Overhead, Split (#157) |
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.