maquette
Part of Ashlar — a display connection stack in Rust, HDMI 2.1 first: from EDID parsing through mode negotiation to FRL link training. See all crates.
A simulated HDMI sink for tests.
maquette simulates what an HDMI source can observe of a sink: its SCDC registers, its EDID
and DisplayID behind the DDC bus, the source's PHY and the line between them, and a clock,
all under deterministic simulated time. Code written over
hdmi-hal's traits runs against it as against a
sink — with the sink's delays, its refusals and its faults — and a test asserts on one
ordered transcript of everything that happened. Where real sinks differ and no public source
settles how, the behaviour is a setting with a documented default. It also carries
conformance checks that an implementation of hdmi-hal's traits runs in its own tests.
Status
In development, before its first release. Built: SimClock, hdmi-hal's clock and delay on
simulated time; the bench, with its DDC bus routed to a test's own targets, the sink's SCDC
registers and its EDID and DisplayID behind the E-DDC segment pointer, register presets and
the transcript; the line, HPD, unplug and detach; the sink's scrambling lock, status flags,
character error counters (with torn reads) and FRL link training, and its HPD resets; the
link's character errors and lane limits; scheduled faults, scheduled sink changes and an operation budget; a hook for a
quirk on top of the sink's SCDC registers; a simulated PHY, or any PHY coupled to the bench,
driving the line; hdmi-hal-async's traits on the same handles (async feature); a
fuzz target checking the simulator's invariants; and conformance checks for implementations
of hdmi-hal's Clock and Delay, DdcBus, ScdcTransport, TmdsPhy, FrlPhy and
PhyPower. The design is in doc/architecture.md, and what comes
next is on the roadmap.
Usage
A bench is a sink, its bus, the source's PHY and a clock in one. A procedure gets the bench's handles as the hdmi-hal traits it takes, and a test asserts on the sink and on the transcript of everything that happened:
use Duration;
use ;
/// The procedure under test: scrambling at 594 Mcsc, the output, then the sink's status.
let bench = new.unwrap;
let up = bring_up;
assert_eq!;
assert_eq!;
assert!;
// A fault: the next write to TMDS_Config is not acknowledged.
let nack = NoAcknowledge;
bench
.schedule
.unwrap;
let error = bring_up.unwrap_err;
assert_eq!;
Settings make the sink stricter or slower (SinkConfig), faults fail or garble operations,
scheduled actions change the sink in the middle of a procedure, and the conformance checks in
check run an implementation of hdmi-hal's traits against what the bench knows.
A procedure that waits and reads the time runs on SimClock in no time at all, and a test
checks exactly how long it took. One clock serves as both clock and delay:
use Duration;
use ;
/// Polls `ready` every millisecond until it holds or `timeout` has passed.
// A delay that sleeps 100 µs long, as a real one may.
let clock = new.with_overshoot;
let mut polls = 0;
let found = poll;
assert!;
// Three delays of 1 ms, each 100 µs long.
assert_eq!;
SimClock is Sync and can be a static. With the std feature a host supplies its
critical section; on a bare target the application supplies one.
An implementation of hdmi-hal's clock and delay runs the conformance check in its own tests. It reports every point that failed, not just the first:
use ;
// Your platform's clock and delay; one `SimClock` serves as both here.
let clock = new;
let report = clock;
report.assert_ok; // panics listing every failed point
check::ClockCheck chooses the delays and reads the check runs, for a platform whose real
delays should be few or short; with the async feature, run_async checks an async delay.
The clock alone cannot show its rate: run_with_reference measures each delay on a clock
the test trusts too, such as check::HostClock on a host (with std).
Features
-
std— the critical-section implementation for hosts, and the checks that need threads. Without it, the application supplies its own critical section, as embedded code does. A host test enables it:[] = { = "…", = ["std"] } -
async— hdmi-hal-async's traits, and theirSendtwins, on the same handles.
no_std builds
maquette is #![no_std] without alloc in every build, and #![forbid(unsafe_code)]:
its capacities are const generics with defaults, so a bench also runs on a bare target.
Stack position
maquette implements and checks hdmi-hal's
traits, and hdmi-hal-async's with the
async feature. The crates above them use it in their tests.
Out of scope
Checks for traits defined by the crates that test against it, a sink's internals (video
decoding, its EDID policy, CEC), and real hardware. See
doc/architecture.md.
Documentation
doc/architecture.md— role, scope, the bench and its handles, time, the sink's behaviour and its sources, faults, the conformance checksdoc/roadmap.md— what is planned, in the order it is builtdoc/setup.md— build, test, MSRV and coverage commandsdoc/testing.md— how the tests are designedCONTRIBUTING.md— issues, pull requests and coding standards
Verifying releases
Releases will be built on GitHub Actions and attested with
SLSA Build Level 2 provenance. To verify a release .crate against its
signed provenance, install the GitHub CLI and run:
The attested .crate will be attached to each
GitHub release.
The first release will be uploaded by the publish workflow with a crates.io API token scoped to publishing this new crate, because trusted publishing can only be set up for a crate already on crates.io; the token is revoked afterwards. Later releases will be uploaded through crates.io trusted publishing: the publish workflow obtains a short-lived token via OpenID Connect instead of using a stored API token. Each version's publishing details, including the workflow run and commit, are available from the crates.io API:
# see .version.trustpub_data