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 theirSendtwins, 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.
- Bench
Builder - Builds a
Bench:Bench::builder, its setters, thenbuild. - 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
Copyhandle borrowed from the bench (Bench::ddc). - Env
- The bench as a target sees it, for the length of one call.
- Error
Rates - 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::schedulenames it. - Filter
- Which operations a fault counts: every field that is set must match.
- Lane
Limits - 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.
- Link
Lanes - Each lane’s
LaneLimits: what the link can carry in FRL link training. - Phy
- The bench’s simulated PHY, a
Copyhandle 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
nthcall matching its kind, fortimescalls, withPhyErrorKind::Fault. Scheduled withBench::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
attemptsattempts, an attempt being a write ofTMDS_ConfigwithScrambling_Enableset. One source, which reads two ways: the two kinds. - Scdc
Registers - A read-only view of the SCDC registers, as the sink holds them.
- Schedule
Full - The fault schedule is full: the bench’s
FAULTSfaults are scheduled. - SimClock
- A clock and a delay on simulated time.
- Sink
- The sink as the test sees it, a
Copyhandle borrowed from the bench (Bench::sink): its registers and HPD, read without a bus operation, so reading them changes nothing and takes no time. - Sink
Config - The sink’s settings.
- Time
- The bench’s clock as a
Clockand aDelay, aCopyhandle 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.
- Bench
Error - Why a bench cannot be built, or a sink plugged in.
- Block
Boundary - 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/linuxe9954f3fbddd,drivers/gpu/drm/display/drm_scdc_helper.c:440–478). - CedUpdate
- When the sink sets
CED_Update(Update_0bit 1), andRSED_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 embeddedsw97f2baf7f69e,XilinxProcessorIPLib/drivers/v_hdmirx1/src/xv_hdmirx1.c:2303–2345,2410–2436); no second source shows when, or whether, a receiver sets them. - Configure
While Running - What
configuredoes with the output running: the contract allows either. - During
HpdLow - 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.
- During
Read - 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
Recordrecords. - 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 clearFLT_update, and setsFRL_startonce the lanes lock (embeddedsw97f2baf7f69e,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 setsFRL_startwithout the lanes in sync (github.com/CoreELEC/common_drivers8ca9b6c3b715,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). - Hook
Write - What the sink does with a byte the source writes, as an
ScdcHookdecides. - 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.
- Missing
Segment - 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
Filternames it. - Operation
- One operation of a transaction.
- Owned
Write - 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. - Past
Store - 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.
- PhyCall
Kind - The kind of a PHY call, without its arguments.
- PhyError
Kind - Why a call of the simulated PHY failed.
- Point
- Where in an operation a fault strikes.
- Refusal
Kind - How a sink refuses an attempt to enable scrambling.
- Register
Group - A group of SCDC registers that an HPD low resets together.
- Scdc
Past End - What an SCDC read or write that runs past 0xFF in one burst does. hdmi-hal’s
ScdcTransportleaves it to the sink, and no public source says. - Scrambler
After Configure - 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. - Status
Update - Whether the sink sets
Status_Update(Update_0bit 0) when it changesClock_Detectedor a lane lock inStatus_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_drivers8ca9b6c3b715:drivers/media/vout/hdmitx20/hdmi_tx_scdc.c:88–112), others read them regardless (Linux, github.com/torvalds/linuxe9954f3fbddd: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
Actionhappens: once, then it leaves the schedule. Counts start when it is scheduled, from 1 (annthof 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§
- Scdc
Hook - 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 aplug. Presets do not pass through it: they are the test’s own. Like a target, it runs with the bench locked and sees it throughEnvonly. - Target
- A device on the sink’s DDC bus, as the bench routes transactions to it.