Skip to content

About

TMDS link bring-up for HDMI sources: clock ratio, scrambling and sink configuration

Topics

Resources

Code of conduct

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

58 Commits

Folders and files

Repository files navigation

spiritlevel

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.

TMDS link bring-up for HDMI sources.

spiritlevel decides a TMDS link's bit clock ratio (1/10 or 1/40) and scrambling from the TMDS character rate, what the sink and the source can do, and the caller's policy, and states what the sink's TMDS_Config must hold. Where implementations of HDMI sources differ, the behaviour is a setting with a documented default, and every reason the link is or is not scrambled is reported.

Status

spiritlevel currently provides the link parameters alone: a pure, I/O-free, const function with no hardware dependency. The procedures — bring-up, tear-down and the reconnect check over the PHY and SCDC — are planned, together with the async companion spiritlevel-async; see the roadmap.

Usage

cargo add spiritlevel

State what the sink and the source can do, and choose the link for the TMDS character rate (in kHz, rounded up):

use spiritlevel::{
    ClockRatio, ParamsError, ScramblingDecision, SinkTmdsFacts, SourceTmdsFacts,
    TmdsLinkParams, TmdsPolicy,
};

fn main() -> Result<(), ParamsError> {
    // From the sink's HF-SCDB (feature `display-types`): `SinkTmdsFacts::from(hf_scdb)`,
    // where `None` is a sink without one. Or state the facts directly:
    let sink = SinkTmdsFacts::new(
        true,  // SCDC present
        true,  // scrambling supported (non-zero Max_TMDS_Character_Rate)
        false, // LTE_340Mcsc_scramble
    );
    let source = SourceTmdsFacts::new(true); // the PHY can scramble at low rates

    let link = TmdsLinkParams::choose(297_000, sink, source, TmdsPolicy::DEFAULT)?;

    assert_eq!(link.clock_ratio(), ClockRatio::Div10);
    // Not scrambled, and every reason is reported: here only the sink's.
    assert!(matches!(
        link.scrambling_decision(),
        ScramblingDecision::Off(off)
            if off.sink_does_not_declare && !off.source_cannot && !off.policy_off
    ));
    // What the sink's TMDS_Config must hold; `None` for a sink without SCDC.
    let config = link.sink_config().expect("this sink has SCDC");
    assert!(!config.scrambling_enable && !config.high_tmds_clock_ratio);
    Ok(())
}

Where HDMI sources differ, TmdsPolicy holds the setting: whether to scramble at or below 340 Mcsc when both ends can (default on), and whether exactly 340 000 kHz counts as above the threshold (default not). A rate above 340 000 kHz on a sink that cannot take scrambling is refused with ParamsError::ScramblingUnsupported, naming every missing fact.

Features

  • display-types (default) — From conversions from display-types' HdmiForumSinkCap into the sink facts. Without it the crate has no dependencies.

no_std builds

spiritlevel is #![no_std] without alloc in every build, and #![forbid(unsafe_code)].

Stack position

spiritlevel is the TMDS counterpart of plumbob, which trains FRL links: beside it in the stack, not on top of it. A link orchestrator chooses between them.

Below it, display-types supplies the sink's HDMI Forum capabilities (the display-types feature). The planned procedures will also use hdmi-hal for the PHY and, behind a feature, culvert for SCDC.

Out of scope

EDID reading and parsing, mode negotiation, FRL, InfoFrames and other data island packets, HDCP, hotplug detection, PHY electrical settings, and retry schedules. See doc/architecture.md.

Documentation

  • doc/architecture.md — role, scope, the rules for choosing the link and their sources, the types, design principles and decisions
  • doc/roadmap.md — what is planned and under consideration
  • doc/setup.md — build, test, MSRV and coverage commands
  • doc/testing.md — what the tests check and how CI runs them
  • CONTRIBUTING.md — issues, pull requests and coding standards

Verifying releases

Releases are 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:

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

The attested .crate is attached to each GitHub release.

0.1.0 was 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 was revoked afterwards. Later releases 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 rejects uploads made with an API token for this crate; the badge above shows that this 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/spiritlevel/X.Y.Z
# see .version.trustpub_data

License

MPL-2.0

About

TMDS link bring-up for HDMI sources: clock ratio, scrambling and sink configuration

Topics

Resources

Code of conduct

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages