spiritlevel
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. Its procedures then carry that out over the
PHY and the sink's SCDC: bring-up, tear-down, the reconnect check after a hotplug, and the
quick restore. Where implementations of HDMI sources differ, the behaviour is a setting
with a documented default, every reason the link is or is not scrambled is reported, and
every step of a procedure is recorded as a structured event.
Status
The link parameters are a pure, I/O-free, const function. The procedures are written
once as an I/O-free core (spiritlevel::procedure) and driven synchronously by TmdsLink,
over hdmi-hal's TMDS PHY, clock and delay
traits and the crate's own TmdsScdc. Each makes one attempt per call; retries are the
caller's. The async companion spiritlevel-async is planned; see the
roadmap.
Usage
State what the sink and the source can do, and choose the link for the TMDS character rate (in kHz, rounded up):
use ;
Where HDMI sources differ, TmdsPolicy holds the setting: whether to scramble at or
below 340 Mcsc when both ends can (default on), whether exactly 340 000 kHz counts as
above the threshold (default not), and which sinks with SCDC get the TMDS_Config write
on a plain link (default all). A rate above 340 000 kHz on a sink that cannot take
scrambling, or from a source without a scrambler, is refused with
ParamsError::ScramblingUnsupported, naming every missing fact; a rate above the source's
own maximum with ParamsError::AboveSourceMaximum.
Then bring the link up over the parts: the sink's SCDC (TmdsScdc, implemented for
culvert's client by the culvert feature), a TmdsPhy, a Clock and a Delay:
// spiritlevel re-exports the hdmi-hal types its API uses, so it is the only dependency.
use ;
/// Brings up 4K60 RGB over TMDS, then stops it again.
Each procedure has a _with_events form that calls a closure with every step, timestamped
from the caller's clock; MAX_BRING_UP_EVENTS and its siblings bound how many, so a caller
without alloc sizes its buffer.
Features
display-types(default) —Fromconversions from display-types'HdmiForumSinkCapinto the sink facts. Without it the caller fills the sink facts itself.culvert—TmdsScdcfor culvert's SCDC client (culvert::Scdc), with culvert's errors wrapped inCulvertError.
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, hdmi-hal supplies the TMDS PHY,
clock and delay traits the procedures run over,
display-types the sink's HDMI Forum
capabilities (the display-types feature), and, behind a feature,
culvert the SCDC client.
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 and design principlesdoc/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
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:
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:
# see .version.trustpub_data