maquette 0.1.0

A simulated HDMI sink for tests: SCDC and EDID registers, a DDC bus, a PHY and a clock under deterministic time, with faults and conformance checks for hdmi-hal's traits
Documentation
# Testing Strategy

This page says how the tests are designed, and which file tests what; it grows as the
parts are built.

## Test structure

- **`src/clock.rs`** — `SimClock`: the start at zero, `advance`, delays with and without
  overshoot, the tick's rounding (`now` down, delays up), that a delay from any point within
  a tick waits at least its duration, saturation at the largest `Timestamp`, monotonic
  reads over mixed delays and advances, the reference implementations, `Send` and `Sync`,
  sharing between threads, and use in a `static`.
- **`src/check/report.rs`** — `Report`: points and failures counted, failures recorded in
  order up to the capacity and counted past it (a capacity of 0 included), the default
  capacity, the printed form, `Display` on a failing writer, and `assert_ok`'s panic.
- **`src/check/clock.rs`** — the clock check: `SimClock` passes with the defaults and with
  coarse ticks and overshoots; broken doubles fail with the points expected — a frozen
  clock, a delay that waits half, a clock that counts down on every read, a delay that moves
  the clock back; the settings; the async form, through `Delay` and through the `Send` twin
  (with `async`); against the host's clock (with `std`), a host clock passing, a clock 1000
  times fast and simulated time caught, the async form; the reference's failures printed.
- **`src/transcript.rs`** — the transcript's storage: order, overflow past the capacity
  (a capacity of 0 included), clearing, and completing a bus record's result; keeping the
  newest, the oldest dropped and counted, and a result reaching only a record still kept.
- **`tests/bus.rs`** — the bench's DDC bus over targets the test defines: routing to the
  first target that answers, a transaction no target takes, a target taking all of its
  transaction; `read_segmented` with and without the segment pointer and split into pieces;
  every refusal by argument and by capability, in hdmi-hal's order, reaching no target and
  taking no time; empty buffers; timing per byte and per transaction; a target's error with
  what it applied kept and the read filled with the pattern; notes and `Env`; `advance`
  updating every target; the transcript's overflow, and a session keeping the newest
  records; a target calling back into its bench panicking with the cause; the EDID store's lengths; SCDC through
  hdmi-hal's `ScdcOverDdc`; the time handle passing the clock check; `Send`, `Sync` and
  threads; calls from several threads following one another in time, a fault counting them
  in the transcript's order.
- **`src/scdc.rs`** — the SCDC register roles, and the transactions the bus never makes: an
  empty write, a second address.
- **`tests/scdc.rs`** — the built-in SCDC target: the default registers; source writes
  stored and recorded, bursts included; register events after their bus record, at its time;
  the offset persisting; SCDC through `ScdcOverDdc`; update flags cleared by writing them
  back; the sink's registers ignored or refused; the manufacturer's block past its
  identification stored; registers outside the modelled set; bursts
  past 0xFF wrapping or, for writes, refused, reads wrapping either way; presets; the `Sink_Version` setting; a sink without SCDC; a
  test's target at 0x54 replacing the built-in one; the settings and the `Sink` view.
- **`src/eddc.rs`** — the E-DDC transactions the bus never makes: several pointer bytes,
  empty writes, a second address; a missing DisplayID store.
- **`tests/hook.rs`** — the SCDC hook: a dropped byte ignored with the burst going on, a
  refused byte ending it, a changed value stored under the register's role, a sink that
  re-syncs when `TMDS_Config` is rewritten, a read hook changing only the wire (and noting
  through `Env`), presets bypassing it, the hook kept across a plug, the default changing
  nothing.
- **`tests/eddc.rs`** — the built-in EDID and DisplayID target: segment 0 and higher segments
  through the pointer, whole and split into pieces; the word offset persisting for
  current-address reads; the pointer reset between transactions and not readable; a sink
  without a pointer (E-DDC 8.1.2); missing segments refused or read past the store, and a
  segment present in one store only; reads past the store filled or wrapped; the
  128-byte boundary continued or wrapped; writes after the offset ignored and recorded; an
  empty EDID; the DisplayID's own store and offset, and its length check.
- **`tests/events.rs`** — bench events: the line starting off and its changes recorded once
  and seen by targets; a delay on the time handle as an event; HPD changes, the built-in
  targets answering or silent while HPD is low, a test's target deciding with HPD, pulses,
  and HPD refused on an unplugged sink; unplugging (nothing answers, the address byte
  charged); plugging a fresh sink, over a plugged one, and with a bad store; detaching (calls
  fail `Detached` after the argument checks, take no time) and reattaching; the operation
  budget counting what the handles do and not the test's own controls, panicking past it,
  and off.
- **`tests/lock.rs`** — the scrambling lock: the status 1 ms after the later of the write
  and scrambled output, either order; the strict sink waiting for output to start again, and for 1 ms after a ratio change; the
  ratio match, the ratio fitting the rate on both sides of 340 000 kHz, scrambling at 1/10
  and unscrambled output; the lock lost when the output
  stops or `Scrambling_Enable` is cleared; a rewrite not restarting it; the count trigger;
  refusals of both kinds, the trigger counting from the accepted attempt, only a write that
  sets `Scrambling_Enable` counting as an attempt; the trigger
  counting from the write that makes the ratio match; the count trigger restarting when a
  condition fails; the enable timeout, with and without output in time, output late
  though the time passed on the bus, a ratio change restarting it, its 100 ms default and
  a sink that never gives up; a delay on
  the time handle as the event that sets it; a preset status holding until the lock
  changes; the defaults.
- **`tests/hpd.rs`** — the HPD resets: every group on any low by default; `Config` on
  every low and the rest after 100 ms; a reset taken at the first event after it is due,
  and when HPD rises; a group that never resets; a reset after zero; a reset as HPD rises,
  losing what was written during the low; one reset per low; a `TMDS_Config` reset losing
  the lock; a status reset re-arming it while a preset still holds; each change of the
  status recorded once; the groups and their defaults.
- **`tests/boundaries.rs`** — exact boundaries: a budget of *n* allowing *n* operations
  and panicking past it; only `start_output` taking the start latency; the PHY's maximum
  rate taken and not above; segment 0x7F not refused; a segment-0 read writing no pointer;
  a segment existing only where a store has bytes; a pointer of 0 taken without a store.
- **`tests/faults.rs`** — faults: before (nothing applied, the address byte charged), after
  (the write latched), partway through a write and a read (the buffer the pattern), a NACK
  partway through a read falling on its address byte, and past
  the last byte; `nth` with a count and until cleared; filters; refused, empty and detached
  calls not counting, unplugged ones counting; each piece of a split read an operation;
  the first scheduled fault striking while every fault counts; a full schedule; a fault
  that never strikes; the stretch timeout, slow operations, `Detached` and `Unsupported`
  effects; a fault for a time striking until its window passes, a zero window striking
  nothing; a preset as an event the lock answers; a corrupt read succeeding with one byte
  changed, counted across the read data only.
- **`tests/actions.rs`** — scheduled actions: before an operation (seen by it) and after
  one (following its record), after a PHY call of the simulated PHY and of a coupled one;
  every action doing what its control does; a detach before an operation failing it;
  operations while detached not counting; an action that cannot apply only recorded; the
  schedule shared with faults, and an action cleared before it comes; a fault and an
  action on one operation; a plug with broken stores refused when scheduled; an action at a
  time taken at an `advance` and before a bus operation, at the event's time, and at the
  next event once past; an update inside an operation taking none of its own actions; an
  unplug during an HPD pulse leaving HPD low.
- **`tests/phy.rs`** — the simulated PHY: a bring-up driving the line until the sink locks,
  and a procedure that never sets the scrambler failing at every rate; each scrambler
  setting after `configure`, and each within the capabilities; `configure` with the output running, failing or stopping it;
  power and the configure-since-power-on rule; the capabilities (rate, scrambler, low-rate
  scrambling), 340 000 kHz counting as a low rate; the mode rule between TMDS and FRL, and the FRL calls outside FRL; a test's
  line holding until the PHY's output changes; the records; PHY faults before and after
  effect, counting and sharing the schedule; the budget; two handles one PHY; generic code
  bounded on the traits; the settings.
- **`tests/coupled.rs`** — `Coupled<P>` over a double: a bring-up locking the sink; the line
  unscrambled after `configure` until `set_scrambling`, whatever the double's scrambler;
  errors returned unchanged and a failed call changing nothing, recorded as `Coupled`; the
  budget; FRL and power passing through by the contract, every call reaching the coupled
  PHY, and a power-on while powered keeping the mode; the last change to the line
  winning, with the simulated PHY and the test's own line; scheduled PHY faults left to the
  simulated PHY; reaching and taking back the PHY; a TMDS-only PHY.
- **`tests/asynch.rs`** (with `async`) — an async bring-up bounded on the `Send` twins alone,
  its future proved `Send` and run on another thread, locking the sink; the plain async
  traits through the blanket implementations; hdmi-hal-async's `SendScdcOverDdc` over the
  bench's bus; errors and records as the sync handles make them; nothing happening until a
  future is polled; a `SimClock` alone as an async delay, passing the clock check.
- **`tests/ddc_check.rs`** — the `DdcBus` check: the bench's bus passing with a described
  device, as a narrow SMBus-style bus, without a segment pointer, without a description,
  from several threads (past 16, and none refused) and async; and buses broken one way each
  caught — doing more than they claim, accepting an empty write, writing the pointer for
  segment 0, corrupting what they read, answering where nothing does, panicking, ignoring
  the offset, dropping the write of a `write_read`, a `write` that sends nothing; unreachable addresses and no
  segmented reads refused; failures from several threads counted; every failure printed.
- **`tests/scdc_check.rs`** — the `ScdcTransport` check: hdmi-hal's `ScdcOverDdc` over the
  bench passing, block and bytewise, behind a 16-byte bus, without faults and async; and
  transports broken one way each caught with exact counts — block reads from the wrong
  register, no 16-byte reads, hidden errors, stuck after an error, failing an empty buffer,
  a `write` that does nothing, a `write` split in two — a write read back and the image
  restored; and a sink without SCDC failing every read; a full fault schedule failing the setup, not
  the transport; a failure no transfer took withdrawn; the failures printed.
- **`tests/phy_check.rs`** — the PHY check: the bench's PHY passing every run under both
  `configure`-while-running settings and both rates, a PHY coupled to the bench passing,
  capabilities refusing or skipping `set_scrambling(true)`, a probe that cannot tell
  skipping its points, a probe reading the PHY it is handed, a scrambler for high rates
  only at 340 000 kHz and just above, the async forms; and PHYs broken one way each caught
  at their point — starting unconfigured (through `run_tmds` and its async form too),
  `configure` keeping the output running, `stop_output` failing while off, `configure` not
  leaving FRL, `power_on` remembering the configuration, `set_scrambling(true)` refused at
  high rates, `set_scrambling` doing nothing, `configure` ignoring the rate and ratio.
- **`README.md` and the rustdoc examples** — run as doctests.

## How the tests are designed

- **Deterministic.** Every test runs on simulated time. Nothing reads the host's clock or
  sleeps, so a test gives the same result on every run and every machine.
- **maquette's implementations pass its own checks.** `SimClock`, the bus and the simulated
  PHY are each run through the conformance check for their trait.
- **The checks' negative cases run against broken doubles:** a clock that goes backwards, a
  delay that returns early, a bus that ignores its capabilities, a PHY that starts without
  being configured. Each must be reported by the check, as the point that failed.
- **Sink behaviour against its sources.** Each row of the sink-behaviour table in
  [`architecture.md`]architecture.md has a test of its fixed behaviour or of each setting,
  default included.
- **Ordering through the transcript.** Tests assert on the transcript's records and their
  times, not on internal state.
- **Records at capacity.** Each record (the transcript, the fault schedule, the reports) is
  tested full, counting its overflow without a panic, at the default and small capacities.

Tests of other crates' procedures against the bench (TMDS bring-up through culvert's client,
the EDID read) live with those crates, which use maquette as a dev-dependency.

## Fuzzing

`fuzz/fuzz_targets/bench.rs` drives a bench with arbitrary sequences of bus calls, PHY calls,
line changes, HPD, plug and adapter changes, presets, faults, scheduled actions (all but a
plug, which would change the sink's settings unseen) and clock advances, on a sink whose
settings and bus capabilities the input chooses; it decodes the input bytes itself. Its bench
holds 4096 records, and it asserts none overflowed, so the invariants see every record.
After every action it checks the invariants a simulator must keep:

- the same input gives the same transcript (each input runs twice);
- nothing panics and no arithmetic overflows (the budget is off; an input runs at most 256
  actions);
- `Scrambling_Status` is set only while `Scrambling_Enable` is set and the line is
  scrambled TMDS at the matching ratio, and that ratio fits the rate (no action presets
  the status; the input's lines include ratios that do not fit);
- once the lock's conditions have held for a time trigger, the status is set (for sinks
  neither strict nor refusing, after an advance or a delay, with HPD high; the input picks
  each register group's HPD reset);
- no `Register` event changes a register the sink owns by `Actor::Source`;
- the segment pointer never outlives its command sequence: the EDID's segment 0 holds
  0x00–0x7F and segment 1 0x80–0xBF, so every EDID read at 0x50 that succeeds must hold no
  byte of segment 1;
- the transcript's times never go backwards.

CI runs the target for 60 seconds on every push and pull request, and for an hour weekly
and on demand; the weekly run minimises the corpus and opens a `ci/fuzz-corpus` pull
request with it. A crash is uploaded as an artifact.

## Coverage

CI measures line coverage without features, with `std` and with `async`, merged into one
report, against `.coverage-baseline` (see [`setup.md`](setup.md)).