hdmi-hal 0.7.0

Hardware abstraction traits for the HDMI stack
Documentation

hdmi-hal

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.

Hardware abstraction traits for the HDMI stack.

hdmi-hal defines the behavioral contracts between protocol logic and hardware. It holds traits, and the glue between its own traits: no hardware, platform or clock implementations, no policy. Every trait expresses an I/O boundary that multiple crates in the stack need to cross in a compatible way — the DDC bus (any target on it, and E-DDC reads of EDID and DisplayID), raw SCDC register access, transmitter PHY control by link mode (what FRL link training needs: rate, training patterns, output mode and TxFFE levels; what TMDS bring-up needs: character rate, clock ratio, the scrambler, output on and off), PHY power, and a clock and delay. Further PHY configuration is on the roadmap.

Usage

cargo add hdmi-hal

Implement a trait against your hardware backend:

use hdmi_hal::ddc::{DdcError, DdcErrorKind};
use hdmi_hal::scdc::ScdcTransport;

struct MyI2cBackend { /* ... */ }
# #[derive(Debug)]
# struct MyError;

// Every transport error says what kind of failure it was, so generic code can tell a sink
// that does not answer from a bus that timed out or is gone.
impl DdcError for MyError {
    fn kind(&self) -> DdcErrorKind { todo!("classify the error") }
}

impl ScdcTransport for MyI2cBackend {
    type Error = MyError;

    fn read(&self, reg: u8) -> Result<u8, MyError> { todo!("read one register") }
    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::scdc::read_block_bytewise(self, reg, buf)` and
    // says so: its reads are then one register at a time.
    fn read_block(&self, reg: u8, buf: &mut [u8]) -> Result<(), MyError> {
        todo!("read buf.len() registers from reg")
    }
}

Accept a trait bound in consumer code:

use hdmi_hal::scdc::ScdcTransport;

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

For a complete worked example of ScdcTransport and FrlPhy with a simulated backend, see examples/simulate.

no_std

hdmi-hal is #![no_std] and needs no allocator, so the traits can be implemented on bare-metal targets as well as in a Linux userspace backend.

Stack position

hdmi-hal sits between the platform backends and the protocol logic crates. It has no dependency on the rest of the stack; protocol crates depend on it, not the reverse.

flowchart LR
    dt["display-types"]
    hal["hdmi-hal"]
    culvert["culvert"]
    plumbob["plumbob"]
    be["platform backends (e.g. hdmi-hal-i2c-dev)"]

    dt --> hal
    hal --> culvert
    hal --> plumbob
    hal --> be

Async variants of each trait live in the companion crate hdmi-hal-async, following the same split as embedded-hal / embedded-hal-async.

Out of scope

  • Protocol logic — SCDC register semantics, typed register wrappers, and the FRL link training state machine belong in the crates that consume ScdcTransport.
  • Implementations — concrete platform backends (kernel I²C drivers, simulator harnesses, test doubles) live in the crates that use these traits.
  • PHY vendor backends — hardware-specific register sequences belong in platform crates that implement FrlPhy and TmdsPhy.
  • CEC or eARC protocol logic — only the wire-access primitive will belong here; protocol state machines are in their own crates.

Documentation

Verifying releases

Releases are built on GitHub Actions and attested with SLSA Build Level 2 provenance (from 0.4.0). To verify a release .crate against its signed provenance, install the GitHub CLI and run:

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

Releases from before the repository moved to the ashlar-display organization (0.4.0 to 0.5.1) were attested under its previous owner, and verify against it:

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

The attested .crate is attached to each GitHub release.

Releases after 0.4.1 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/X.Y.Z
# see .version.trustpub_data

Versions up to 0.3.0 were uploaded with an API token (0.1.0 by hand, 0.2.0 and 0.3.0 from CI) and carry no provenance; 0.4.0 and 0.4.1 carry provenance but were also uploaded with an API token.

License

Licensed under the Mozilla Public License 2.0.