Skip to main content

Crate maquette

Crate maquette 

Source
Expand description

A simulated HDMI sink for tests.

maquette simulates what an HDMI source can observe of a sink: its SCDC registers, its EDID and DisplayID behind the DDC bus, the source’s PHY and the line between them, and a clock, all under deterministic simulated time. Code written over hdmi-hal’s traits runs against it as against a sink, with the sink’s delays, refusals and faults, and a test asserts on one ordered transcript of everything that happened. It also carries conformance checks that an implementation of hdmi-hal’s traits runs in its own tests.

The Bench holds the simulation. Its DDC bus (Ddc) routes each call to a test’s own Targets or the sink’s SCDC registers, EDID and DisplayID, and records it in the transcript. The line, HPD, unplug and detach are bench events; the sink keeps a scrambling lock and resets its registers around an HPD low; register presets and a view of the registers (Sink) serve the test; the simulated Phy, or any PHY Coupled to the bench, drives the line; scheduled Faults fail operations; an operation budget ends a test that loops forever; SimClock keeps the time. The check module holds the conformance checks for hdmi-hal’s traits. With the async feature the handles implement hdmi-hal-async’s traits too. The design is in doc/architecture.md.

§Features

  • std — the critical-section implementation for hosts, and the checks that need threads. Without it, the application supplies its own critical section, as embedded code does.
  • async — hdmi-hal-async’s traits, and their Send twins, on the same handles.

Re-exports§

pub use hdmi_hal::ddc::DdcBus;
pub use hdmi_hal::ddc::DdcCapabilities;
pub use hdmi_hal::ddc::DdcError;
pub use hdmi_hal::ddc::DdcErrorKind;
pub use hdmi_hal::ddc::DdcHandle;
pub use hdmi_hal::ddc::EddcTarget;
pub use hdmi_hal::ddc::NoAcknowledgeSource;
pub use hdmi_hal::phy::EqParams;
pub use hdmi_hal::phy::FrlOutput;
pub use hdmi_hal::phy::FrlPhy;
pub use hdmi_hal::phy::LaneEqParams;
pub use hdmi_hal::phy::LanePatterns;
pub use hdmi_hal::phy::LtpPattern;
pub use hdmi_hal::phy::PhyPower;
pub use hdmi_hal::phy::TmdsClockRatio;
pub use hdmi_hal::phy::TmdsPhy;
pub use hdmi_hal::phy::TmdsPhyCapabilities;
pub use hdmi_hal::phy::TmdsPhyConfig;
pub use hdmi_hal::phy::TmdsVideo;
pub use hdmi_hal::phy::TxFfeLevel;
pub use hdmi_hal::phy::TxFfeRestrictions;
pub use hdmi_hal::ColorBitDepth;
pub use hdmi_hal::ColorFormat;
pub use hdmi_hal::HdmiForumFrl;
pub use hdmi_hal::time::Clock;
pub use hdmi_hal::time::Delay;
pub use hdmi_hal::time::Timestamp;
pub use hdmi_hal;
pub use hdmi_hal_async;async

Modules§

check
Conformance checks for implementations of hdmi-hal’s traits.

Structs§

Bench
A simulated sink, its clock and its line, and the handles a procedure runs over.
BenchBuilder
Builds a Bench: Bench::builder, its setters, then build.
BusError
A failed call of the bench’s DDC bus.
BusRecord
A bus operation as the transcript records it: read, not built (see Record).
BusTiming
How long the bench’s bus operations take on its clock.
Coupled
Any PHY driving the bench’s line: a third party’s, a forwarding stub, a firmware PHY under hardware-in-the-loop.
Ddc
The bench’s DDC bus, a Copy handle borrowed from the bench (Bench::ddc).
Env
The bench as a target sees it, for the length of one call.
ErrorRates
Character errors on the link, per lane, in errors a second: what the sink’s character error counters count while the lane is locked. Lane 3 carries data in 4-lane FRL only; the Reed-Solomon corrections are FRL’s.
Fault
A fault: it strikes bus operations that match its filter, at a point of the operation, with an effect. Scheduled with Bench::schedule.
FaultId
A scheduled fault, as Bench::schedule names it.
Filter
Which operations a fault counts: every field that is set must match.
LaneLimits
What one lane of the link can carry in FRL link training: the highest rate it trains at, and the least TxFFE level the source must apply on it. A lane outside its limits does not carry the training patterns the sink asks for, so training does not pass.
LinkLanes
Each lane’s LaneLimits: what the link can carry in FRL link training.
Phy
The bench’s simulated PHY, a Copy handle borrowed from the bench (Bench::phy); two handles are one PHY.
PhyError
A failed call of the simulated PHY.
PhyFault
A fault of the simulated PHY: it fails the nth call matching its kind, for times calls, with PhyErrorKind::Fault. Scheduled with Bench::schedule_phy, in the same schedule as the bus’s faults.
PhySettings
How the simulated PHY behaves where hdmi-hal’s contract allows several behaviours. Each defaults to the least forgiving one: a procedure must be correct under any behaviour the contract allows.
Record
One entry of the transcript: what happened, and when.
Refusal
“Some displays refuse to set the scrambling bit right away”: a sink that does, for its first attempts attempts, an attempt being a write of TMDS_Config with Scrambling_Enable set. One source, which reads two ways: the two kinds.
ScdcRegisters
A read-only view of the SCDC registers, as the sink holds them.
ScheduleFull
The fault schedule is full: the bench’s FAULTS faults are scheduled.
SimClock
A clock and a delay on simulated time.
Sink
The sink as the test sees it, a Copy handle borrowed from the bench (Bench::sink): its registers and HPD, read without a bus operation, so reading them changes nothing and takes no time.
SinkConfig
The sink’s settings.
Time
The bench’s clock as a Clock and a Delay, a Copy handle borrowed from the bench (Bench::time): one value passed as both.

Enums§

Action
Something the bench does by itself during a procedure, as the test scheduled it with Bench::schedule_action: what a test could do between two calls, done between two steps of the code under test.
Actor
Who changed a register.
BenchError
Why a bench cannot be built, or a sink plugged in.
BlockBoundary
What a read across a 128-byte block boundary at 0x50 or 0x52 does: “some implementations may support” continuing (VESA E-DDC 1.3, 2.2.6).
BusOp
The kind of a bus operation.
CedRead
Whether reading a character error counter clears it. Unresolved in public sources: one source’s comments say reading clears the counts at the sink (Xilinx embeddedsw 97f2baf7f69e, XilinxProcessorIPLib/drivers/v_hdmitx1/src/xv_hdmitx1.c:2979), while the same vendor’s receiver keeps them, and Linux reads the whole map for debugging with no word of losing them (github.com/torvalds/linux e9954f3fbddd, drivers/gpu/drm/display/drm_scdc_helper.c:440–478).
CedUpdate
When the sink sets CED_Update (Update_0 bit 1), and RSED_Update (bit 6) for the Reed-Solomon corrections, which it keeps until the source clears them. One public receiver sets both from a check once a second: when a valid count has risen by at least 4 since the last check, or has just reached 0x7FFF (Xilinx embeddedsw 97f2baf7f69e, XilinxProcessorIPLib/drivers/v_hdmirx1/src/xv_hdmirx1.c:2303–2345, 2410–2436); no second source shows when, or whether, a receiver sets them.
ConfigureWhileRunning
What configure does with the output running: the contract allows either.
DuringHpdLow
Whether a built-in target answers while HPD is low. For the EDID VESA E-DDC 1.3 §4.2.2 settles it; for SCDC no public source says.
DuringRead
Whether the registers that change by themselves (the character error counters) hold still while a read is under way. No public source says whether a sink holds them; the counters’ checksum is the source’s protection against a torn read, whatever the transport does. On a link without errors nothing moves, so the default tears only where a test sets ErrorRates.
Effect
What a fault does to the operation it strikes.
Event
What a Record records.
FrlPass
What an FRL sink checks before it passes link training and sets FRL_start. The two public receivers differ: Xilinx’s checks the patterns on every lane, waits for the source to clear FLT_update, and sets FRL_start once the lanes lock (embeddedsw 97f2baf7f69e, XilinxProcessorIPLib/drivers/v_hdmirx1/src/xv_hdmirx1_frl.c:398–412, 588–596, 616–640); Amlogic’s posts the pass whatever the lanes carry (its BIST error counts are only logged), gives up waiting for the clear after 100 ms, and sets FRL_start without the lanes in sync (github.com/CoreELEC/common_drivers 8ca9b6c3b715, drivers/media/vin/tvin/hdmirx/hdmi_rx_hw_t3x.c:4454–4576, 4770–4800, hdmi_rx_hw.c:864–879, hdmi_rx_wrapper.c:6711–6719).
HookWrite
What the sink does with a byte the source writes, as an ScdcHook decides.
HpdReset
When a group of registers resets to 0 around an HPD low.
Ignored
Why a built-in target ignored a write.
Line
What the source transmits, as the sink sees it.
MissingSegment
What the sink does with a segment pointer value for a segment it does not have. VESA E-DDC 1.3 requires an acknowledge of the pointer for segments 1 and higher that exist (6.4, 6.5), not what follows for others. A segment exists when the EDID or the DisplayID store has bytes in it.
OpKind
The kind of a bus operation, as a Filter names it.
Operation
One operation of a transaction.
OwnedWrite
What a write to an SCDC register the sink owns (Sink_Version, Scrambling_Status, Source_Test_Configuration, the status flags, the error counters, the manufacturer’s identification at 0xD0–0xDD) does. No public source says.
PastStore
What a read past the end of the EDID or DisplayID store does, in a segment the sink has. VESA E-DDC 1.3 covers only the data a display has. A read goes on with data: the host acknowledges each byte it reads, so the display cannot refuse one (DDC/CI 1.1 §1.6: the acknowledge bit goes the other way to the data).
PhyCall
A call of the simulated or a coupled PHY, with its arguments.
PhyCallKind
The kind of a PHY call, without its arguments.
PhyErrorKind
Why a call of the simulated PHY failed.
Point
Where in an operation a fault strikes.
RefusalKind
How a sink refuses an attempt to enable scrambling.
RegisterGroup
A group of SCDC registers that an HPD low resets together.
ScdcPastEnd
What an SCDC read or write that runs past 0xFF in one burst does. hdmi-hal’s ScdcTransport leaves it to the sink, and no public source says.
ScramblerAfterConfigure
The scrambler after configure: the contract leaves it unspecified. Each rule stays within the PHY’s capabilities: the scrambler is never on without one, nor on at or below 340 000 kHz where it cannot scramble there.
StatusUpdate
Whether the sink sets Status_Update (Update_0 bit 0) when it changes Clock_Detected or a lane lock in Status_Flags_0. The public receivers set it in their SCDC hardware, and none shows when; one source family reads the flags only when it is set and clears it by writing it back (Amlogic, github.com/CoreELEC/common_drivers 8ca9b6c3b715: drivers/media/vout/hdmitx20/hdmi_tx_scdc.c:88–112), others read them regardless (Linux, github.com/torvalds/linux e9954f3fbddd: drivers/gpu/drm/display/drm_scdc_helper.c:440–478).
Times
How many operations a fault strikes.
Trigger
When a sink’s behaviour happens once its conditions hold: after a time, or on a count of operations.
When
When a scheduled Action happens: once, then it leaves the schedule. Counts start when it is scheduled, from 1 (an nth of 0 is taken as 1), and count what a fault would.

Constants§

DEFAULT_BUDGET
The default operation budget (chosen): far more than a bring-up, a training run or a long session of polling takes, and spent within seconds by a loop that never ends.
DEFAULT_PHY_CAPABILITIES
The simulated PHY’s capabilities by default: 600 000 kHz, with a scrambler that also scrambles at or below 340 Mcsc.

Traits§

ScdcHook
A test’s change to how the built-in SCDC sink takes a byte the source writes, or answers a read: a vendor quirk on top of the standard sink, which keeps its offset, bursts, lock, HPD resets and records. Set with BenchBuilder::scdc_hook; one per bench, kept across a plug. Presets do not pass through it: they are the test’s own. Like a target, it runs with the bench locked and sees it through Env only.
Target
A device on the sink’s DDC bus, as the bench routes transactions to it.