Skip to content

Latest commit

 

History

History
74 lines (59 loc) · 7.99 KB

testing.md

File metadata and controls

74 lines (59 loc) · 7.99 KB

Testing strategy

spiritlevel's core is a pure decision, TmdsLinkParams::choose: no I/O, no clock, no allocator. Its tests are unit tests that call it over the inputs that matter and check the whole result, including every reason it reports.

Test structure

Unit tests live in a #[cfg(test)] module at the end of each file:

File What the tests check
src/params.rs choose over every combination of the sink, source and policy facts, with the result checked for consistency; the 340 MHz threshold at, just above and below it, under both ScramblingThreshold settings (Above340, AtOrAbove340); that LTE_340Mcsc_scramble without scrambling support gives no low-rate scrambling; that each reason is set exactly when its fact blocks; the sink's TMDS_Config for each case (DVI sink, SCDC sink below the threshold, low-rate scrambling); an error exactly above 340 MHz on a sink that cannot scramble; choose usable in const contexts
src/types.rs The fact and policy types: constructors keep their fields in order and are const, NONE matches new(false, false, false), DEFAULT matches Default (low-rate scrambling on, Above340), the policy builders change one field each; with display-types, the conversion from the HF-SCDB (an absent block gives NONE)
src/error.rs ParamsError's Display names every missing fact, and reads well without one
src/config.rs The settings: the defaults are the documented ones, each setter changes its field alone, validate reports every problem at once, and SinkPresence is exhaustive
src/procedure/bring_up.rs Bring-up over the test double: the default order for a scrambled link, OutputDuringSinkWrite::Running running unscrambled output through the write, and a plain link clearing the sink with no deadline; whole-byte writes without reading, and no write where none is due; an FRL sink cleared and given the source version by default, each following its setting, and a sink without SCDC given nothing; a video that does not give the link's rate refused before any I/O; a failure in the work before both paths (the FRL clear and Source_Version) a warning, transient or not, with the work going on, a kind added later counted as transient, and those warnings kept when the write later stops; the wait counted from the write; a failed write carrying on or, under Stop, tearing down, with no writes to a gone sink in the cleanup; a read-modify-write that fails at the write saying so; a check that sees no scrambling, and a late start, as warnings; a PHY failure saying where and whether output may run; tear_down_on_error off leaving both ends; the cancel flag read before each step of that work and before a plain link's read-back, ending the procedure before any I/O when set at entry and tearing down at the next point otherwise; a zero interval spending the wait in one delay; no combination of settings recording more events than the bound
src/procedure/check.rs The scrambling check: a sink that reports at once is set after one read, one that reports late when it does, one that never does is not set after the window; failed reads do not end it, every read failing is Unreadable, and a detached bus or Unsupported ends it at once; a frozen clock ends it on its read count, a delay that runs late ends it, and no read starts after the window; a zero window reads once; the read cap follows window and interval; the cancel flag is read before every read
src/procedure/reconnect.rs The reconnect check: a sink that kept its configuration matches; a reset sink lost it, with the bits read kept; both bits are compared, and a plain link expects both clear; a failed read is reported, not acted on; changed facts or a sink without SCDC read nothing
src/procedure/restore.rs The quick restore: a scrambled link written, set and checked with the output running; a plain link written and not checked; no write where none is due; a failed write carrying on or stopping; a failed scrambler call an error, with the write; only the check reading the cancel flag
src/procedure/tear_down.rs Tear-down: by default only the output stops; clearing follows the order the settings give; nothing is written to a plain link, a sink without SCDC or a gone sink; a failed sink write is a warning, and a failed PHY step does not keep the output running; a low-rate scrambled link is cleared too; events are stamped from the I/O's clock; no combination of settings records more events than the bound
src/procedure/test_io.rs The test double the procedure tests run against: writes reach its registers and calls cost simulated time; it records each call and answers as set
src/scdc.rs TmdsScdc: a register-level implementation does what each method says, a borrowed implementation forwards every call, and UpdateError tells the read's failure from the write's
src/culvert.rs With culvert, the adapter for culvert's client: every method goes through culvert, errors carry the transport's kind and say which transfer failed, a protocol error is Unsupported, the transport reads blocks as a sink would, and CulvertError prints, compares and chains as culvert's error
src/link.rs TmdsLink: bring-up, tear-down, the reconnect check and the quick restore run over its parts, which are reachable between procedures; the plain form and the one with a cancel flag; its synchronous I/O passes every call through
src/outcome.rs The result types: errors print and chain, warnings keep their order and never overflow, a plain link's check read nothing, and the kinds keep the result and drop the value
src/event.rs Events are Copy and carry no error values

Against a simulated sink (tests/simulated_sink.rs)

With the culvert feature, the procedures run through culvert's client, over hdmi-hal's ScdcOverDdc on maquette's simulated DDC bus, with its simulated PHY and its time as clock and delay. The sink keeps its scrambling lock, its TMDS_Config and its HPD resets as the public receivers do; refusals, delays and faults are set per test.

Covered:

  • A bring-up at 594 Mcsc locks the sink, and a tear-down clears it; a plain 1/10 link writes TMDS_Config 0 and checks nothing; low-rate scrambling at 1/10 locks
  • A slow sink locks within the check window, and a slower one does not
  • The quick restore: a sink that withholds the status once locks on it; one that resyncs on the rewrite is waited out; a sink that drops Scrambling_Enable is found lost and restored
  • HPD: by default any pulse loses the configuration; a sink that resets only after 100 ms of HPD low keeps it over a short pulse and loses it over a long one
  • A strict sink locks when the scrambler follows the write, but not on a quick restore with scrambled output already running; a tear-down and a bring-up recover
  • Faults: a NACKed TMDS_Config write carries on with a warning; a detached one ends the bring-up with a tear-down; a failed start_output ends it with a PHY error

Doctests

The README's example runs as a doctest (ReadmeDoctests in src/lib.rs) and asserts the link it chooses, so it stays true to the API.

Builds

CI runs the tests with the default features and with no default features (without the display-types conversions), on stable and on the MSRV. It builds both for thumbv7em-none-eabi, which has no std, on stable, and the no-default build on the MSRV.

Coverage

Coverage is measured with cargo-llvm-cov and kept from falling by a ratchet: CI fails when line coverage drops more than 0.1 percentage points below .coverage-baseline, and opens a PR raising the baseline when a push improves it. See setup.md for the commands.

Philosophy

  • Every reason, not the first. A decision reports every condition that applies, so the tests check each reason against the fact that sets it, not only the outcome.
  • Exhaustive where the input space is small. The facts are a handful of booleans; testing every combination is cheaper than arguing which ones matter.