spiritlevel 0.1.0

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

What each release contains is in the [changelog](../CHANGELOG.md); this page is about
what comes next. Today `spiritlevel` is the decision a TMDS bring-up starts from
(`TmdsLinkParams::choose`); next come the procedures that carry it out.

## Planned

### The procedures

The next step adds the I/O: the procedures that take a `TmdsLinkParams` to a running link, each
making one attempt and its check per call, with retries left to the caller.

- **Bring-up.** Above 340 Mcsc: write the sink's `TMDS_Config`, start scrambled TMDS output
  within the sink's deadline, and check `Scrambling_Status`. At or below 340 Mcsc: the plain
  link, or the scrambled one when the decision allows it. The sink's FRL settings are
  cleared first when the link may have been in FRL, and `Source_Version` is written on an
  SCDC sink when the policy says so.
- **Tear-down.** Clearing the clock ratio and scrambling on the sink and in the source, and
  stopping TMDS output, in the order that keeps the two in step.
- **The reconnect check.** After a hotplug, reading `TMDS_Config` back against the link the
  source runs (a sink may lose it, for example after a long HPD low), and a quick restore
  (a rewrite and a status check) when the caller chooses it over a full bring-up.
- **Diagnostics.** Each step reported as a structured event with its timestamp, so a caller
  can see what happened and when, without logging.

The order of the steps, their timing and where each comes from will be cited from public
implementations of HDMI sources, as the rules for choosing the link are.

### The interfaces the procedures need

`spiritlevel` defines what it needs rather than depending on particular implementations,
so a driver, a firmware image or a vendor SDK can supply its own:

- **From [hdmi-hal]https://github.com/ashlar-display/hdmi-hal's next breaking release:**
  a TMDS PHY trait (configure the character rate and clock ratio, start and stop TMDS
  output, the source's scrambler, a capabilities report from which `SourceTmdsFacts` is
  built), a PHY power trait, and clock and delay traits. These traits are being shaped with
  `spiritlevel` as their main caller, so the procedures follow that hdmi-hal release.
- **A small SCDC trait of the crate's own:** write and read `TMDS_Config`, read
  `Scrambling_Status`. A `culvert` feature adds its implementation over
  [culvert]https://github.com/ashlar-display/culvert's `Scdc`, kept in this crate so a
  change to the trait never forces a culvert release; it uses the `TMDS_Config` read on
  culvert's roadmap.

### `spiritlevel-async`

An async companion crate, as plumbob has plumbob-async: the procedures as an I/O-free core
shared by a sync driver here and an async driver there, over hdmi-hal-async's traits, with
futures that can be `Send`.

### Testing the procedures

The procedures will be tested against a register-level simulated HDMI sink with a simulated
clock, including sinks that refuse, delay or lose their configuration, and the crate will
offer conformance checks that implementors of the new hdmi-hal traits can run.

### Changes to today's types

The current types may change where the procedures need it, for example `SourceTmdsFacts`
built from the PHY's capabilities report. Such a change is a breaking release, and the
changelog will list it.

### The link orchestrator

A link orchestrator planned for the stack will choose between FRL (plumbob) and TMDS
(`spiritlevel`) and call the procedures: bring-up and tear-down, and the reconnect check
after a hotplug, deciding retries itself. It will drive `spiritlevel` through an interface
of its own; nothing in `spiritlevel` changes for it.

## Under consideration

### `serde` derives

Optional `Serialize` and `Deserialize` on the public types behind a feature, as
display-types and concordance have, so a diagnostic tool can record decisions. Waits until
`serde` without `std` is settled for the stack.

### Checking the rate against the TMDS maximum

`choose` does not refuse a character rate above the TMDS maximum; the negotiation layer
checks the sink's, source's and cable's ceilings before a link is chosen. A check here
would become a rule once the maximum is cited from public implementations.

### Writing `TMDS_Config` to a sink without SCDC

One source, Amlogic, writes `TMDS_Config` even to a sink that declares no SCDC; every other
source examined gates the write on SCDC, and `spiritlevel` follows them. A setting for the
other behaviour would be added only if a real sink needs it.