hdmi-hal-async
Part of Ashlar — a display connection stack in Rust, HDMI 2.1 first: from EDID parsing through mode negotiation to FRL link training.
display-types · piaf · concordance · cartouche · culvert · plumbob · hdmi-hal · hdmi-hal-async · hdmi-hal-i2c-dev
Async hardware abstraction traits for the HDMI stack.
hdmi-hal-async is the async companion to hdmi-hal,
following the same split as embedded-hal / embedded-hal-async. It mirrors each trait
in hdmi-hal with async fn methods and otherwise identical signatures — ScdcTransport
for raw SCDC register access and HdmiPhy for transmitter PHY control. Data types such as
EqParams are defined in hdmi-hal and re-exported here rather than duplicated.
Sync consumers continue to use hdmi-hal directly. Async platform backends (Embassy
drivers, async kernel drivers) implement the traits here. The two crates impose no
executor dependency on each other or their consumers.
Usage
Implement a trait against your async hardware backend:
use ScdcTransport;
A future may be dropped before it completes (a timeout, a select!); the trait
documentation says what a transport promises then. To stop early, check the deadline
before each call rather than dropping a call in flight.
Accept a trait bound in consumer code:
use ScdcTransport;
async
Multi-threaded executors
The plain traits promise nothing about their futures, so code generic over them cannot
spawn on a multi-threaded executor. For that, each trait has a Send twin,
phy::SendHdmiPhy and scdc::SendScdcTransport: the same methods, returning futures
that are Send, with errors that are Send. A transport twin is also Sync, because
read takes &self.
use SendScdcTransport;
A twin implementation is also an implementation of the plain trait, so it works with
code written against either. Import the trait your code is bounded by: with both in
scope, method calls on a twin implementation are ambiguous. Bound generic code by the twin
alone, as above: adding + ScdcTransport or + HdmiPhy, which the twins imply anyway,
makes the compiler use that bound instead of the blanket implementation, and the futures
are no longer known to be Send.
Stack position
hdmi-hal-async mirrors hdmi-hal's position in the stack, serving async platform
backends and async protocol logic. It depends on hdmi-hal for shared data types.
flowchart LR
dt["display-types"]
hal["hdmi-hal"]
async["hdmi-hal-async"]
ca["culvert-async"]
pa["plumbob-async"]
be["async platform backends"]
dt --> hal
dt --> async
hal --> async
async --> ca
async --> pa
async --> be
Out of scope
- Protocol logic — typed SCDC register wrappers and async link training belong in
the crates that consume
ScdcTransport. - Implementations — async platform backends live in the crates that use these traits.
- Sync/async adapters — wrappers that bridge sync implementations to async trait bounds belong in a compatibility shim crate, not here.
- Executor dependency — the traits impose no constraint on which async runtime is used.
Documentation
doc/architecture.md— trait surfaces, design principles, and async/sync splitdoc/roadmap.md— planned features and future work
Verifying releases
Releases are built on GitHub Actions and attested with
SLSA Build Level 2 provenance (from 0.2.0). To verify a release
.crate against its signed provenance, install the
GitHub CLI and run:
Releases from before the repository moved to the ashlar-display organization (0.2.0 and
0.2.1) were attested under its previous owner, and verify against it:
The attested .crate is attached to each
GitHub release.
Releases from 0.2.0 are uploaded through crates.io trusted publishing: the publish workflow obtains a short-lived token via OpenID Connect instead of using a stored API token. crates.io can also reject uploads made with an API token for this crate; the badge above shows whether that setting is on. Each version's publishing details, including the workflow run and commit, are available from the crates.io API:
# see .version.trustpub_data
0.0.1 (by hand) and 0.1.0 (from CI) were uploaded with an API token; they carry no provenance and have no GitHub release.
License
Licensed under the Mozilla Public License 2.0.