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.
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.
cargo add spiritlevelState 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.
display-types(default) —Fromconversions from display-types'HdmiForumSinkCapinto the sink facts. Without it the crate has no dependencies.
spiritlevel is #![no_std] without alloc in every build, and #![forbid(unsafe_code)].
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.
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.
doc/architecture.md— role, scope, the rules for choosing the link and their sources, the types, design principles and decisionsdoc/roadmap.md— what is planned and under considerationdoc/setup.md— build, test, MSRV and coverage commandsdoc/testing.md— what the tests check and how CI runs themCONTRIBUTING.md— issues, pull requests and coding standards
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/spiritlevelThe 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