hdmi-hal-async 0.4.0

Async hardware abstraction traits for the HDMI stack
Documentation

hdmi-hal-async

CI crates.io docs.rs License: MPL-2.0 Rust 1.85+ SLSA Level 2 trusted publishing only

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

cargo add hdmi-hal-async

Implement a trait against your async hardware backend:

use hdmi_hal_async::scdc::ScdcTransport;

struct MyAsyncI2cBackend { /* ... */ }
# #[derive(Debug)]
# struct MyError;
# impl hdmi_hal_async::ddc::DdcError for MyError {
#     fn kind(&self) -> hdmi_hal_async::ddc::DdcErrorKind {
#         hdmi_hal_async::ddc::DdcErrorKind::Other
#     }
# }

impl ScdcTransport for MyAsyncI2cBackend {
    type Error = MyError;

    async fn read(&self, reg: u8) -> Result<u8, MyError> { todo!("read one register") }
    async fn write(&mut self, reg: u8, value: u8) -> Result<(), MyError> {
        todo!("write one register")
    }

    // One DDC transaction for the whole buffer (a length limit, if any, of at least
    // 16 bytes). A backend that cannot burst-read
    // implements this with `hdmi_hal_async::scdc::read_block_bytewise(self, reg, buf).await`
    // and says so: its reads are then one register at a time.
    async fn read_block(&self, reg: u8, buf: &mut [u8]) -> Result<(), MyError> {
        todo!("read buf.len() registers from reg")
    }
}

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 hdmi_hal_async::scdc::ScdcTransport;

async fn configure_frl<T: ScdcTransport>(transport: &mut T) -> Result<(), T::Error> {
    transport.write(0x31, 0x01).await?; // initiate FRL
    Ok(())
}

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 hdmi_hal_async::scdc::SendScdcTransport;
# struct MyThreadSafeBackend;
# #[derive(Debug)]
# struct MyError;
# impl hdmi_hal_async::ddc::DdcError for MyError {
#     fn kind(&self) -> hdmi_hal_async::ddc::DdcErrorKind {
#         hdmi_hal_async::ddc::DdcErrorKind::Other
#     }
# }
# // A stand-in with tokio::spawn's bound: the future must be `Send + 'static`.
# mod tokio {
#     pub fn spawn<F: core::future::Future + Send + 'static>(_future: F) {}
# }

impl SendScdcTransport for MyThreadSafeBackend {
    type Error = MyError;

    async fn read(&self, reg: u8) -> Result<u8, MyError> { todo!() }
    async fn write(&mut self, reg: u8, value: u8) -> Result<(), MyError> { todo!() }
    async fn read_block(&self, reg: u8, buf: &mut [u8]) -> Result<(), MyError> { todo!() }
}

fn spawn_frl_start<T: SendScdcTransport + 'static>(mut transport: T) {
    tokio::spawn(async move { transport.write(0x31, 0x01).await });
}

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

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:

gh attestation verify hdmi-hal-async-X.Y.Z.crate --repo ashlar-display/hdmi-hal-async

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:

gh attestation verify hdmi-hal-async-X.Y.Z.crate --owner DracoWhitefire \
  --signer-repo DracoWhitefire/hdmi-hal-async

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:

curl -A "your-tool (contact)" https://crates.io/api/v1/crates/hdmi-hal-async/X.Y.Z
# 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.