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. See all crates.
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 — DdcBus for the
connector's DDC bus, ScdcTransport for raw SCDC register access, FrlPhy and TmdsPhy
for transmitter PHY control, PhyPower for its power, and Delay for waiting (with
hdmi-hal's Clock, which does not wait, re-exported). 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::SendFrlPhy, phy::SendTmdsPhy, phy::SendPhyPower, scdc::SendScdcTransport,
ddc::SendDdcBus and time::SendDelay: the same methods, returning futures that are
Send, with errors (where the trait has them) that are Send. The transport and bus twins
are also Sync, because their methods take &self.
use SendScdcTransport;
# ;
#
# ;
#
# // A stand-in with tokio::spawn's bound: the future must be `Send + 'static`.
#
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 + FrlPhy, 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.
no_std
hdmi-hal-async is #![no_std] and needs no allocator; the traits use async fn, so any
executor can drive them, including those for bare-metal targets.
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/setup.md— build, test,no_std, MSRV and coverage commandsdoc/testing.md— what the tests check and how CI runs themdoc/roadmap.md— planned features and future workCONTRIBUTING.md— how to contribute, and trait stability
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.