spiritlevel 0.2.0

TMDS link bring-up for HDMI sources: clock ratio, scrambling and sink configuration
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
# Architecture

This document describes `spiritlevel` as released: what it decides and does, the rules it
follows and where they come from, its types, and why it works the way it does. Claims about HDMI behaviour cite
at least two independent public implementations of HDMI sources (see "Sources").

## Role

`spiritlevel` brings up and tears down the TMDS link of an HDMI source. First it decides,
without any I/O, what the link will be: from the TMDS character rate, what the sink and the
source can do, and the caller's policy, the link's bit clock ratio (1/10 or 1/40), whether
it is scrambled and why, and what the sink's `TMDS_Config` register must hold. Then its
procedures carry that out over the PHY and the sink's SCDC: bring-up, which configures the
sink, starts TMDS output in the right order and checks that the sink follows; tear-down;
and, after a hotplug while the link is up, the reconnect check and the quick restore.

The decision is a pure `const fn`, usable on its own by a caller that drives its hardware
itself. The procedures define the interfaces they need instead of depending on particular
implementations: a small SCDC trait of the crate's own (`TmdsScdc`) and
[hdmi-hal](https://github.com/ashlar-display/hdmi-hal)'s TMDS PHY, clock and delay traits.
A driver, a firmware image or a vendor SDK supplies those and uses the crate without a link
orchestrator or a negotiation layer above it.

TMDS and FRL are separate link modes with separate procedures. FRL link training is
[plumbob](https://github.com/ashlar-display/plumbob)'s; `spiritlevel` is its counterpart for
TMDS, beside it in the stack rather than on top of it.

It implements the procedure, not policy: where implementations of HDMI sources differ, the
behaviour is a setting with a documented default, and how often to retry is the caller's.

---

## Scope

`spiritlevel` covers:

- **Choosing the link parameters:** the clock ratio, scrambling and the sink's
  `TMDS_Config` contents, from the character rate, the sink's and source's facts, and the
  policy.
- **Explaining the choice:** every reason a link is not scrambled, and every missing fact
  when a rate is refused.
- **Bring-up:** clearing the sink's FRL settings when the link may have been in FRL,
  `Source_Version` on an SCDC sink when the settings say, writing `TMDS_Config`, starting
  TMDS output in an order that never sends scrambled TMDS before the sink is told, and
  checking `Scrambling_Status`.
- **Tear-down:** stopping TMDS output and, when the caller asks, clearing the ratio and
  scrambling on the sink and in the source.
- **After a hotplug while the link is up:** the reconnect check, which reads `TMDS_Config`
  back against the running link, and the quick restore, which writes it again without a
  new bring-up.
- **One attempt per call:** each call makes one attempt and its check, and reports the
  outcome and every step as an event.

It does not cover:

- **Computing the character rate:** it depends on the negotiated colour format, depth and
  pixel repetition, which is the negotiation layer's knowledge. The caller passes it in.
- **Checking the rate against the TMDS maximum** or the sink's, source's and cable's
  ceilings: the negotiation layer checks those before a link is chosen.
- **EDID reading and parsing:** the sink facts come from the parsed HDMI Forum capabilities.
- **The hardware:** the PHY's registers and electrical settings (swing, pre-emphasis, lane
  mapping) and the SCDC transfers are the implementations of the traits.
- **FRL:** plumbob.
- **InfoFrames and other data island packets, AVMUTE, HDCP.**
- **Hotplug detection and when to bring the link up or down:** the caller decides; the
  reconnect check is a tool it calls.
- **Retry and polling schedules:** the caller's, with `spiritlevel` making one attempt per
  call.

---

## Dependencies and features

The features and the dependencies, with their versions in `Cargo.toml`:

```toml
[features]
default = ["display-types"]
culvert = ["dep:culvert"]

[dependencies]
display-types = { default-features = false, optional = true }
hdmi-hal = { default-features = false }
culvert = { default-features = false, optional = true }
```

Dependencies point only down the stack: nothing below `spiritlevel` depends on it.

- **hdmi-hal** (always): the TMDS PHY trait (`TmdsPhy`, with its capabilities report and
  `TmdsClockRatio`, which `spiritlevel` re-exports as `ClockRatio`), the clock and delay
  traits, and the cancel flag. It is a public dependency, and `spiritlevel` re-exports the
  types its API uses (the PHY and time traits, `TmdsVideo` and its colour types, the DDC
  error classification, `Cancel`), so a caller or an implementation needs no other
  dependency and names the same versions; with `culvert`, culvert's client and errors too. hdmi-hal itself depends on display-types, so
  display-types is always in the graph.
- **`display-types`** (default): `From<&HdmiForumSinkCap>` and
  `From<Option<&HdmiForumSinkCap>>` for `SinkTmdsFacts`. Without it the caller states the
  sink facts itself. display-types is then a public dependency (its type appears in those
  impls), so a breaking display-types release means a breaking `spiritlevel` release.
- **`culvert`**: `TmdsScdc` for [culvert](https://github.com/ashlar-display/culvert)'s
  SCDC client (`culvert::Scdc`, over any `ScdcTransport`), with culvert's errors wrapped in
  `CulvertError`. The adapter lives here, so a change to `TmdsScdc` never forces a culvert
  release.

---

## Choosing the link

`TmdsLinkParams::choose(rate_khz, sink, source, policy)` returns the link or a
`ParamsError`.

### Inputs

| Input               | Type                                                                         | Where the caller gets it                                                                                                                                                                                                                                                                         |
|---------------------|------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| TMDS character rate | `u32`, kHz                                                                   | the negotiated configuration (pixel clock × deep-colour factor, halved for YCbCr 4:2:0, with any pixel repetition); **rounded up**, never truncated (12 bpc on a 1 kHz clock gives half kHz, and truncating 340 000.5 would pick 1/10)                                                           |
| Sink facts          | `SinkTmdsFacts { scdc_present, scrambling_supported, lte_340mcsc_scramble, frl_capable }` | the sink's HDMI Forum capabilities (`From<&HdmiForumSinkCap>`; no HF-SCDB means `SinkTmdsFacts::NONE`); `scrambling_supported` is SCDC present and a non-zero `Max_TMDS_Character_Rate`, as Linux derives `scrambling.supported` [11]; `frl_capable` a non-zero `Max_FRL_Rate`, used by bring-up's FRL clear, not by the rules here; the caller may clear a fact for a sink known to misbehave |
| Source facts        | `SourceTmdsFacts { scrambling, low_rate_scrambling, max_character_rate_khz }` | the PHY's capabilities report (`From<&TmdsPhyCapabilities>`): whether it has a scrambler, whether it can scramble at or below 340 Mcsc, and its highest TMDS character rate                                                                                                                       |
| Policy              | `TmdsPolicy { low_rate_scrambling, threshold, tmds_config_gate }`            | the caller; `TmdsPolicy::DEFAULT` follows the majority of the sources where there is one (rules 3 and 4), and a chosen default where there is none (rule 6)                                                                                                                                       |

### Rules

0. **A rate above the source's own maximum** (`max_character_rate_khz`) is refused first,
   with `ParamsError::AboveSourceMaximum`, so a sink never gets 1/40 for a link the PHY
   cannot then drive. A capability of this source, not a behaviour to cite.
1. **Above the threshold**, the clock ratio is 1/40 and the link is scrambled; the sink's
   `TMDS_Config` gets both `TMDS_Bit_Clock_Ratio` and `Scrambling_Enable`. Every source
   examined does this: the Linux DRM helper and vc4 (one lineage), i915, dw-hdmi, amdgpu,
   nouveau, Tegra, MediaTek v2, Xilinx and Amlogic [1], [3]–[10]. It needs a sink that can
   take it and a source with a scrambler (rule 5).
2. **At or below the threshold**, the clock ratio is 1/10, and a sink with SCDC has the
   ratio cleared in `TMDS_Config` [1], [3]–[10].
3. **Scrambling at or below the threshold** is on when all three allow it: the source can
   (`scrambling` and `low_rate_scrambling`), the sink supports scrambling (`scdc_present` and
   `scrambling_supported`) and declares `LTE_340Mcsc_scramble`, and the policy permits
   it. The sources that scramble at low rates, i915, amdgpu, nouveau and dw-hdmi, enable
   it whenever the sink declares it [3][4][5][6], and all four take the declaration from
   Linux's `scrambling.low_rates`, which the EDID parser sets only for a sink with SCDC and
   a non-zero `Max_TMDS_Character_Rate` [11]; i915, nouveau and dw-hdmi also check
   `scrambling.supported` themselves [3][4][6]. Xilinx leaves it to the application, off by
   default [9]. The helper lineage, Tegra, MediaTek v2 and Amlogic do not scramble at low
   rates [1][7][8][10] (in the helper lineage it is a TODO [2]). Hence a setting,
   **default on**.
4. **The threshold** is "above 340 Mcsc" by default; "at or above 340 Mcsc" is the
   alternative, and the two differ only at exactly 340 000 kHz. Above: the helper lineage,
   i915, dw-hdmi, nouveau, Xilinx and Amlogic [1][3][4][6][9][10]; at or above: Tegra and
   MediaTek v2 [7][8]. amdgpu is split and counted on neither side: its sink write uses
   "above" (`link_ddc.c:575`), its own scrambler "at or above"
   (`dce_stream_encoder.c:621`), so at exactly 340 000 kHz it scrambles without configuring
   the sink [5]. nouveau, Tegra and MediaTek v2 compare the mode's pixel clock, not the
   character rate [6][7][8]. Hence a setting, with the majority as default.
5. **A sink that cannot take scrambling** lacks `scdc_present` or `scrambling_supported`.
   Without SCDC the sink cannot be configured at all: no `TMDS_Config` value, ratio 1/10,
   no scrambling.
   - **Above 340 000 kHz**, `choose` refuses with `ParamsError::ScramblingUnsupported`,
     naming every missing fact. The sources gate the sink write and carry on unscrambled;
     `spiritlevel` refuses instead, because negotiation never picks such a rate, so
     reaching `choose` with it means the inputs disagree, and an unscrambled link would
     hide that.
   - **At exactly 340 000 kHz with `AtOrAbove340`**, such a sink gets the plain 1/10 link,
     which is a valid link at that rate under the default threshold, and `ScramblingOff`
     names the missing fact, so the departure from the requested threshold is visible.
     Tegra enables its scrambler and the sink's ratio only with SCDC [7]; MediaTek v2 sets
     its own scrambler regardless and skips only the sink write [8].

   - **A source without a scrambler** (`scrambling` not set) is treated the same way,
     since its sink would otherwise be told to expect scrambling the source cannot send:
     refused above 340 000 kHz, with `ScramblingUnsupported::source_cannot_scramble` set
     together with any sink flags that also apply; the plain 1/10 link at exactly
     340 000 kHz with `AtOrAbove340` (`ScramblingOff::source_cannot`); and no low-rate
     scrambling (rule 3). `SourceTmdsFacts::new` takes the source to have one.

   A source scrambling with an unconfigured sink is never an outcome of `choose`. One
   source, Amlogic, writes `TMDS_Config` even to a sink that declares no SCDC [10]; every
   other source gates the write on SCDC, and so does `spiritlevel`.
6. **Which SCDC sinks get a `TMDS_Config` write on a plain link** is a setting,
   `TmdsPolicy::tmds_config_gate`, with **any sink with SCDC** (`AnyScdcSink`) as chosen
   default. amdgpu, MediaTek v2 and Xilinx write to any SCDC sink; i915, dw-hdmi and
   nouveau only to one that supports scrambling; Amlogic to every sink [25]: no majority.
   The choice matters because most sources write `TMDS_Config` at every bring-up, a plain
   one included [20], while the helper lineage and Tegra clear it only at their own
   tear-down [24], so a sink left at 1/40 by something else would stay there. The groups
   differ only for a sink with SCDC that declares no TMDS rate above 340 Mcsc. Under
   `ScramblingSink`, such a sink's plain link has no `sink_config()`. The gate is a policy
   setting, not an edit of the sink facts: the facts say what the sink declares, the
   policy what the source does about it, so `Source_Version` and the FRL clear still
   happen on a sink the gate leaves unwritten. Amlogic's "every sink" is not offered
   (rule 5): a caller whose sink has SCDC despite its EDID sets `scdc_present`.

### Output

`TmdsLinkParams`: the rate, the clock ratio, whether the link is scrambled and why
(`ScramblingDecision`), the sink's `TMDS_Config` contents (`SinkTmdsConfig`, `None` exactly
when no write is due: a sink without SCDC, or a plain link rule 6 leaves unwritten), and the
sink facts it was chosen from (`sink()`, which bring-up's FRL clear uses). It also keeps the
source facts and policy, so `fits(sink)` can tell whether choosing again for other sink
facts gives the same link, as the reconnect check asks. The procedures program the PHY with the ratio and the scrambling flag and write the
sink's value through `TmdsScdc`; a caller without them does the same itself. `spiritlevel` states *what* the
register holds, not its bit layout: the encoding belongs to the SCDC implementation
([culvert](https://github.com/ashlar-display/culvert)'s `TmdsConfig`, for one).

---

## The procedures

Each procedure takes the running link's `TmdsLinkParams`, makes one attempt (and, for
bring-up and the quick restore, one check) and returns what happened; whether and when to
try again is the caller's. The procedures are written once as an I/O-free core
(`spiritlevel::procedure`, over the `TmdsIo` trait) and driven synchronously by `TmdsLink`,
over a `TmdsScdc`, a `TmdsPhy`, a `Clock`, a `Delay` and an optional `Cancel` flag. Every step
is also recorded as a `TmdsEvent` ("Diagnostics").

### Before both paths: the FRL clear and `Source_Version`

On a sink with SCDC, bring-up first does two things, in this order; a sink without SCDC
gets neither.

1. **The FRL clear.** A source that may have used FRL clears the sink's FRL settings
   before TMDS: `Config_1` (the FRL rate), then `FLT_update` [36]. amdgpu does it on every
   TMDS bring-up, Amlogic only on a sink that declares FRL [22][23]. Two sources, no
   majority, so a setting, `ClearFrl`: **`IfSinkDeclaresFrl`** (chosen default; `Config_1`
   holds FRL settings only on such a sink, `SinkTmdsFacts::frl_capable`) or `EveryScdcSink` (amdgpu's,
   for a driver whose EDID may not describe the sink behind it). `SinkTmdsFacts::new` sets
   `frl_capable` for a sink with SCDC, so a caller that never states it still gets the
   clear, which on a sink without FRL writes a register that sink does not use.
2. **`Source_Version` = 1.** No two sources agree on when to write it [39]: amdgpu on every
   bring-up when `Sink_Version` is 1, the helper lineage and dw-hdmi only on a scrambled link
   (the helper only to a sink reporting a version, dw-hdmi its version, 0 included), Xilinx
   unconditionally when it detects the sink, Amlogic only on its FRL path. So a setting,
   `SourceVersionWrite`: **`EveryBringUp`** (chosen default, closest to Xilinx's
   unconditional write), `IfSinkVersion1` (amdgpu's), `WhenScrambling` (the helper lineage's:
   on a scrambled link, to a sink reporting a version) or `Never` (for a sink that
   misbehaves).

Both come before the `TMDS_Config` write, as in every source that does them [22]; the order
between them is amdgpu's, the one source that does both. A failed step here is a warning
and the bring-up carries on, whatever the error's kind: neither source can see the result of
its FRL clear [27], and no source treats `Source_Version` as fatal. A bus that is gone
(`Detached`) fails the `TMDS_Config` write that follows, which stops the bring-up there; a
request the SCDC implementation cannot do (`Unsupported`) does not block the link.

### Bring-up

`bring_up(link, video, config)` brings up the link `choose` decided, carrying `video` (the
pixel clock, colour depth and format, which the PHY needs). The PHY takes the rate and the
video together, so they must agree: a link whose rate is not the one the video gives
(`TmdsVideo::character_rate_khz`, hdmi-hal's) is refused before any I/O, with
`BringUpError::VideoMismatch`. A caller gets the rate for `choose` from the video. The steps
for a scrambled link above 340 Mcsc, with `BringUpConfig::DEFAULT`:

1. **Output off.** TMDS output is stopped before anything is written, and stays stopped
   until step 5. i915, amdgpu, the dw-hdmi family, MediaTek v2, Xilinx and Amlogic write the
   sink with their output off [12]–[17]; vc4 and Tegra write it with unscrambled output
   running and turn their scrambler on afterwards [18]. A majority with dissent, so a
   setting, `OutputDuringSinkWrite`: **`Stopped`** (default) or `Running` (below).
2. **The sink's `TMDS_Config`, both bits in one write**, from `sink_config()`. amdgpu,
   nouveau and Amlogic write both bits in one transaction [14][6][17]; the other six
   lineages (i915, the helper lineage, the dw-hdmi family, Tegra, MediaTek v2, Xilinx) write
   them one at a time, in either order [37]. None depends on an order, and the register ends
   the same, so this is a platform difference rather than a dissent: `spiritlevel` writes
   both at once, which leaves no moment in which the sink holds one bit without the other. How it is written is a setting,
   `TmdsConfigWrite`: **`ReadModifyWrite`** (default; the bits set, every other bit kept as
   read), as seven lineages do (the five that write through Linux's SCDC helper, nouveau and
   Xilinx) [37]; or `WholeByte`, as amdgpu and Amlogic do [14][17] (one transaction, no
   read).
3. **The PHY:** the character rate, the clock ratio and the source's scrambler, with the
   output still off, as Xilinx and MediaTek v2 set their scrambler before output starts
   [16][15].
4. **The wait after the ratio write**, `ratio_wait`, **default 1 ms**: the five lineages
   that write the ratio through Linux's SCDC helper sleep 1–2 ms after every ratio write
   (i915, the helper lineage, the dw-hdmi family, Tegra, MediaTek v2) [37], the dw-hdmi
   family 100 ms more in its own code [12]; amdgpu, nouveau, Xilinx and Amlogic start output
   at once [14][6][16][17]. It is measured from the write, so the PHY's own time counts
   towards it, and spent in slices of at most `check_interval` (for cancellation).
5. **Output on.** If more than `scrambling_deadline` (**default 100 ms**) has passed since
   the write, the outcome carries a `DeadlineMissed` warning saying by how much. The 100 ms is
   stated in the comments of three lineages: i915's (the sink may disable scrambling if it
   sees no scrambled clock within 100 ms of the write) [19], and Linux's SCDC helper's and
   dw-hdmi's (1 to 100 ms from the ratio write until transmission resumes) [37][12]. dw-hdmi's
   own code waits longer than that [12], so it warns rather than stops: the check shows
   whether the sink followed.
6. **The check** of `Scrambling_Status` ("The scrambling check").

**No scrambled TMDS ever reaches the sink before its write**, in every source and in both
orders. With `Running`, the PHY is configured with its scrambler off and the output started
first (steps 3 and 5), then `TMDS_Config` is written and the wait spent, and only then the
source's scrambler turned on; the deadline runs from the write to the scrambler, and the
check from the scrambler. This is vc4's order: the PHY runs at the link's clock ratio from
the start, so on a 1/40 link the sink sees the 1/40 clock before its write [18]. Tegra,
which also writes with its output running, switches its clock mode only together with its
scrambler, after the write [18]; `TmdsPhy` sets the ratio only with the output stopped, so
that order cannot be expressed over it.

**At or below 340 Mcsc** the same steps run, with these differences:

- **`TMDS_Config` is written at every bring-up** where a write is due (rule 6), with the
  ratio cleared and `Scrambling_Enable` set only for a scrambled low-rate link, as i915,
  amdgpu, the dw-hdmi family, nouveau, MediaTek v2, Xilinx and Amlogic do [20], so a sink
  left at 1/40 by something else (another source, a firmware that ran first) is corrected.
  The wait follows every `TMDS_Config` write, one that clears the ratio included [37].
- **A plain link has no deadline and no check**: `Scrambling_Status` stays 0 there, so
  there is nothing to wait for (`CheckResult::NotApplicable`). A scrambled low-rate link
  has both, as i915 polls a low-rate scrambled link as it does a high-rate one [21].
- **A failed write on a plain link is followed by one `TMDS_Config` read**, whose result
  (the two bits and the byte, or the read's error) is part of the write's warning: with no
  check, a sink that kept 1/40 after a failed clear would otherwise go unnoticed.

**A failed `TMDS_Config` write** is a setting, `OnTmdsConfigFailure`: **`CarryOn`**
(default) keeps a warning and continues to the PHY and output, and the check shows whether
the sink followed. Most sources carry on (i915 logs it and enables the port, the others do
not look at the result) [26]; the DRM helper clears both sink bits and leaves its scrambler
off, and nouveau returns when its read fails [38]. `Stop` ends the bring-up with an error.
With read-modify-write, the warning (an `UpdateError`) says which half failed, and an error
or event names it by its step, `ReadTmdsConfig` or `WriteTmdsConfig`: a failed read means
nothing was written. Carrying on is also what a DRM driver needs, since its enable hooks cannot fail.

### The scrambling check

`Scrambling_Status` is read every `check_interval` (**default 1 ms**) until the sink reports
scrambling or `check_window` (**default 200 ms**) ends, counted from output start (from the
scrambler with `Running`): i915's values [19]. The helper lineage and Tegra re-check only
after 1 s and 5 s [1][7]; that is the caller's repeat, not this check.

- **Failed reads do not end it.** Polling goes on until the status is set or the window
  ends, so the result tells a sink that missed one read and then reported scrambling from
  one that never answered. It stops early only on an error that will not pass: the bus is
  gone (`DdcErrorKind::Detached`) or the read cannot be done (`Unsupported`). Any other kind,
  including one added to `DdcErrorKind` later, counts as transient: polling on costs a window
  at most, stopping early would misreport a link that came up.
- **Bounded by count as well as by time:** at most `ceil(window / interval) + 1` reads, so a
  clock that does not advance (a timer not started) ends the check instead of hanging the
  bring-up; reaching the count is recorded (`read_cap_reached`). The count bounds reads, not
  time: on such a clock the check takes as long as its reads take. No read starts after the
  window: the check ends when another interval would reach the window's end, and again when
  a delay ran past it; a slow read that started inside the window may end after it. The
  interval is spent by the `Delay`, not measured by the clock.
- **At least one read**, whatever the window: a window of 0 reads once, and an interval of
  0 reads again at once. `BringUpConfig::validate()` reports the settings that defeat their
  purpose: a deadline not longer than the wait (every bring-up would miss it), an interval
  not shorter than the window (one read) and an interval of 0 (reads back to back); the
  procedures run with any values.

The check ends `Set` (with the time it took), `NotSet` (the window ended) or `Unreadable`
(every read failed, or one failed with a non-transient error), with the number of reads and
failed reads and the first error. The link is left running in every case: no source treats
an unset `Scrambling_Status` as fatal, so the result is part of the outcome, not a condition
of it, and repeating the bring-up later is the caller's. `NotSet` and `Unreadable` are also a
warning, `ScramblingNotConfirmed`, since a link the sink does not follow shows nothing: a
caller that only looks at the warnings still sees it.

### What a bring-up returns

- **`BringUpOutcome::Up(LinkUp)`** when steps 1–5 completed: the link, when the sink was
  written and the output started, the check, and the **warnings**, each kind at most once:
  a failed FRL clear (`Config_1` or `FLT_update`), `Sink_Version` read or `Source_Version`
  write, a failed `TMDS_Config` write under `CarryOn`, a missed deadline, and a check that did
  not see scrambling.
- **`BringUpError`** when a step failed in a way that stops the bring-up: a PHY call (output
  off, configure, scrambler, output on), or the sink's `TMDS_Config` write with a
  non-transient error or under `Stop`. It names the step, the error, whether the output may be
  running, and the warnings gathered. Or, before any I/O, `VideoMismatch`: the video does
  not give the link's rate.
- **After an error, a tear-down**, with the caller's `TearDownConfig`, and its result in the
  error (`Cleanup`); with the sink taken to be gone after `Detached`. `tear_down_on_error:
  false` leaves both ends as the error left them, for a tool that wants to read the state.
- **`BringUpOutcome::Cancelled`** when the caller's cancel flag stopped it ("Cancellation").

### Cancellation

A caller stops a running procedure through its `Cancel` flag (hdmi-hal's, re-exported;
`AtomicBool` and any reference to a flag implement it),
never by dropping the future: a dropped call leaves the PHY and the sink in an unknown state.
Bring-up reads the flag at entry, before each SCDC step, before each slice of the ratio wait
and before each read of the check, so a cancel is seen within one `check_interval` whatever
the configured wait (with an interval of 0 the wait is one slice, read before it). Once it is set, the bring-up ends `BringUpOutcome::Cancelled`, never an
error, with where it was seen (`CancelPoint`):

- at entry, before any I/O, with nothing torn down (`Cleanup::Skipped`);
- anywhere else, after a tear-down with the caller's `TearDownConfig`, whatever
  `tear_down_on_error` says. The flag does not say why it was set, so the tear-down takes
  the sink to be present: with `clear_sink` on, a sink already unplugged gets one write,
  which fails fast and is a warning (`SinkClear::Failed`), as the sources that write
  regardless of the connection do [30].

Tear-down is the recovery and is not cancelled; the reconnect check is one read; the quick
restore reads the flag in its check alone. No procedure clears the flag: the caller resets it
before its next call, or that call ends `Cancelled` at entry.

### Tear-down

`tear_down(link, config, presence)` stops the link the bring-up started; `presence` says
whether the sink is still there, which only the caller knows. Powering the PHY down is not
part of it.

**Whether the sink is cleared** is a setting, `TearDownConfig::clear_sink`, **default off**:
the dw-hdmi family, nouveau, MediaTek v2, Xilinx and Amlogic leave `TMDS_Config` at tear-down
and rely on the next bring-up writing it [28]; i915, amdgpu, the helper lineage and Tegra
clear both bits [29]. Off is safe when the next link is a TMDS bring-up by this crate, which
writes `TMDS_Config` every time. **Before FRL it is not**: FRL training leaves `TMDS_Config`
alone, so a 1/40 scrambled link followed by FRL would leave both bits set for the whole FRL
session; amdgpu, the one source with separate TMDS and FRL paths, clears on every disable
[29]. A caller taking the link from TMDS to FRL, or handing the sink to something that may not
write it, sets `clear_sink`. Amlogic clears on suspend for sinks on a quirk list [31], which
this setting also covers.

With clearing on, the steps are:

1. **The sink's `TMDS_Config` to 0, in one write.** When is a setting, `SinkClearTiming`:
   **`BeforeOutputStops`** (default), as i915, amdgpu, the helper lineage and Tegra do [29],
   or `AfterOutputStops`, Amlogic's quirk path [31]. Only what the bring-up set is cleared: a
   plain link needs no write, as the helper lineage and Tegra write nothing when they did not
   scramble [29].
2. **The source's scrambler off.** Its order against the sink is a setting, `ScramblerOff`,
   a majority with dissent: **`AfterSink`** (default; i915, amdgpu, the DRM helper and Tegra
   stop their source side after the sink's clear) or `BeforeSink` (vc4, which splits the
   helper lineage) [29].
3. **Output off.**

With clearing off, only the output stops; the next bring-up sets the scrambler again.

- **Whether the sink is there** is the caller's argument, `SinkPresence`, on every call:
  `Present` writes, as i915, vc4 and Tegra do regardless of the connection; `Gone` writes
  nothing, as the helper and amdgpu do for a sink that is not connected [30].
- **Failures never keep the output running.** A failed sink write is a warning, as in every
  source that clears [29]. A failed PHY call is an error, but every later step is still
  attempted, so a failed scrambler call does not leave the output on; the result records
  each step's first error (`TearDownError`).
- **No waits:** the sources' waits during tear-down belong to AVMUTE and video, not to the
  sink's bits.

### The reconnect check

A sink may lose its `TMDS_Config` while the source keeps the link up: the helper lineage
says the sink's SCDC status "is reset and must be explicitly restored" on a reconnect with the
display active [32]. So after a hotplug while the link is up, the helper lineage checks on
every hotplug with the connector connected, dw-hdmi brings the link up again when the sink is
back, and Xilinx rewrites on a short HPD pulse [32][33][34]. Hotplug is the caller's;
`check_reconnect(link, current_sink)` is the check it calls, also usable at start-up on a link
found running (Amlogic writes `TMDS_Config` again then [35]).

- **The same sink first.** `current_sink` is the sink's facts from the EDID read after the
  hotplug, with any quirk the caller applied before applied again. When the link no longer
  fits them (`TmdsLinkParams::fits`: choosing again, with the source facts and policy the
  link was chosen with, would refuse the rate or give another ratio, scrambling or
  `TMDS_Config`), the result is `SinkChanged`, with nothing read. A fact the link does not
  depend on may change: a TV that toggles FRL in its EDID keeps its TMDS link. Facts that
  fit do not prove the same sink; telling sinks apart by their EDID is the caller's, before
  it calls the check.
- **One read, both bits compared** with `sink_config()`: i915 compares both, the helper and
  vc4 only `Scrambling_Enable`, since they always set the two together [32]. Every link is
  checked, a plain one too (its expected value is both bits 0, which a reset sink matches),
  unlike the helper lineage, which checks only a link that set something.
- **It writes nothing.** The result is `Matches`, `Lost` (with the bits and byte read),
  `Unreadable` (the read's error), `NotApplicable` (no write is due on this link) or
  `SinkChanged`. A failed read is reported, not acted on, as i915 and vc4 log it and the
  helper returns it [32].

**After `Lost`**, the way back is the caller's. The helper lineage does a full mode set and
dw-hdmi its whole setup; Xilinx rewrites with the stream running [32][33][34]. A majority does
the full bring-up, which in this crate is `tear_down` followed by `bring_up`; the quick restore
is the option.

### The quick restore

`quick_restore(link, config)` is Xilinx's way back [34], with the check added:

1. **`TMDS_Config` in one write**, with the output left running. There is no wait, because
   the output never stops: the sink switches under a clock that keeps running. After `Lost`
   on a 1/40 link the sink's ratio bit was reset, so this write switches the sink's clock
   ratio with TMDS running, as Xilinx and Amlogic do; the DRM helper, i915 and dw-hdmi
   avoid exactly that with a full mode set, their comments say [32][12], which is why the
   full bring-up is the default. On a 1/10 link, or a sink that kept its bits (a check that
   ended `NotSet`), nothing switches. `tmds_config_write` and `on_tmds_config_failure` apply
   as in bring-up; a write under `CarryOn` that fails is kept in `Restored::write_failed`.
2. **The source's scrambler set again** to the link's, as Xilinx does with the sink write
   [34] (Amlogic writes only the sink [35]): one PHY call that covers a source that lost its
   state with the sink. A plain link gets it too, set off.
3. **The check**, as in bring-up, from the scrambler, on a scrambled link.

It does not touch the PHY's rate or clock ratio, stops nothing and tears nothing down on an
error (`RestoreError`): the link was running, and what to do next is the caller's. If the
source side may have changed too, the full bring-up is the way back. It reads the cancel flag
only in its check: the write and the scrambler are one call each, and a restore stopped
between them would leave the sink and the source disagreeing. A cancelled check ends
`CheckResult::Cancelled`, with the link left running.

---

## Key Types

### Choosing the link

```rust
/// The TMDS bit clock ratio: the TMDS clock runs at the bit rate / 10 or / 40.
/// Exhaustive: `TMDS_Bit_Clock_Ratio` is one bit. hdmi-hal's type, so the link's ratio
/// passes straight to the PHY.
pub use hdmi_hal::phy::TmdsClockRatio as ClockRatio;   // { Div10, Div40 }

/// Which character rate first requires scrambling and 1/40 (rule 4).
#[non_exhaustive]
pub enum ScramblingThreshold {
    Above340,       // default: > 340 000 kHz
    AtOrAbove340,   // ≥ 340 000 kHz
}

/// What the sink declares (`new`, which sets `frl_capable` to `scdc_present`; `NONE` for a sink without HDMI
/// Forum capabilities, e.g. a DVI or HDMI 1.x sink; `with_frl_capable`). With the
/// `display-types` feature, `From<&HdmiForumSinkCap>` and `From<Option<&HdmiForumSinkCap>>`.
#[non_exhaustive]
pub struct SinkTmdsFacts {
    pub scdc_present: bool,
    pub scrambling_supported: bool,   // SCDC and a non-zero Max_TMDS_Character_Rate
    pub lte_340mcsc_scramble: bool,   // counts only with scrambling_supported
    pub frl_capable: bool,            // a non-zero Max_FRL_Rate: bring-up's FRL clear
}

/// What the source's PHY can do: `From<&TmdsPhyCapabilities>`, or `new(low_rate_scrambling)`
/// with a scrambler and no maximum (`u32::MAX`), and `with_scrambling`,
/// `with_max_character_rate_khz`.
#[non_exhaustive]
pub struct SourceTmdsFacts {
    pub scrambling: bool,
    pub low_rate_scrambling: bool,
    pub max_character_rate_khz: u32,
}

/// The caller's choices (rules 3, 4 and 6). `Default`/`DEFAULT`: low-rate scrambling on,
/// `Above340`, `AnyScdcSink`; a `with_…` setter for each.
#[non_exhaustive]
pub struct TmdsPolicy {
    pub low_rate_scrambling: bool,
    pub threshold: ScramblingThreshold,
    pub tmds_config_gate: TmdsConfigGate,
}

/// Which SCDC sinks get a `TMDS_Config` write on a plain link (rule 6).
#[non_exhaustive]
pub enum TmdsConfigGate { AnyScdcSink /* default */, ScramblingSink }

/// The two fields of `TMDS_Config` (0x20), what is written and what a read decodes to
/// (`new`). Its bit layout belongs to the SCDC implementation.
#[non_exhaustive]
pub struct SinkTmdsConfig { pub scrambling_enable: bool, pub high_tmds_clock_ratio: bool }

/// A read of `TMDS_Config`: the two fields and the byte as read (`new`), so reserved bits a
/// sink sets stay visible.
#[non_exhaustive]
pub struct TmdsConfigReading { pub config: SinkTmdsConfig, pub raw: u8 }

/// Why the link is or is not scrambled.
#[non_exhaustive]
pub enum ScramblingDecision {
    Required,             // above the threshold (rule 1)
    LowRate,              // at or below; source, sink and policy all allow it (rule 3)
    Off(ScramblingOff),   // 1/10, not scrambled (at or below, or the rule 5 fallback)
}

/// Every condition that keeps a 1/10 link unscrambled; at least one is set. Each flag
/// is judged on its own fact, independently of the others.
#[non_exhaustive]
pub struct ScramblingOff {
    pub no_scdc: bool,
    pub no_scrambling_support: bool,   // scrambling_supported not set
    pub sink_does_not_declare: bool,   // LTE_340Mcsc_scramble not set
    pub source_cannot: bool,
    pub policy_off: bool,
}

/// The chosen link, built only by `choose`: `rate_khz()`, `clock_ratio()`,
/// `scrambling()` (true for `Required` and `LowRate`), `scrambling_decision()`,
/// `sink_config() -> Option<SinkTmdsConfig>` (`None` exactly when no write is due),
/// `sink() -> SinkTmdsFacts`, `fits(SinkTmdsFacts) -> bool`. Equality compares the source
/// facts and policy it was chosen with too.
pub struct TmdsLinkParams { /* private */ }

impl TmdsLinkParams {
    pub const fn choose(
        rate_khz: u32,
        sink: SinkTmdsFacts,
        source: SourceTmdsFacts,
        policy: TmdsPolicy,
    ) -> Result<Self, ParamsError>;
}

/// `Display` and `core::error::Error`. Both variants are `#[non_exhaustive]` too.
#[non_exhaustive]
pub enum ParamsError {
    /// A rate above 340 000 kHz on a sink that cannot take scrambling or a source without
    /// a scrambler (rule 5); every missing fact is set.
    ScramblingUnsupported {
        rate_khz: u32,
        no_scdc: bool,
        no_scrambling_support: bool,
        source_cannot_scramble: bool,
    },
    /// A rate above the source's own maximum (rule 0).
    AboveSourceMaximum { rate_khz: u32, max_khz: u32 },
}
```

All are `Debug, Clone, Copy, PartialEq, Eq, Hash`; all constructors are `const fn`, so a
firmware can fix its policy and facts at compile time. `ScramblingStatus`, what the sink
reports in `Scrambling_Status` (`set`, with the byte read in `raw()`), is the procedures'
and is described with them.

- **Why private fields on `TmdsLinkParams`:** the PHY and the sink must agree. With public
  fields a caller could change the ratio and leave the sink's value stale; with getters the
  only way to a `TmdsLinkParams` is through the rules.
- **Why `ScramblingDecision`:** an unscrambled low-rate link is not a failure, but a
  caller expecting scrambling should see which of source, sink or policy declined it.
- **Why the sink facts are a struct of their own,** not `HdmiForumSinkCap` directly: the
  decision needs three flags, a caller can override a misbehaving sink without editing
  parsed EDID data, and the API is tied to display-types only through the `From` impls.

### The procedures' settings

```rust
/// Bring-up's and the quick restore's settings. `Default`/`DEFAULT`; a `with_…` setter
/// for each; the quick restore reads `tmds_config_write`, `on_tmds_config_failure` and
/// the check's two timings.
#[non_exhaustive]
pub struct BringUpConfig {
    pub ratio_wait: Duration,                          // 1 ms
    pub scrambling_deadline: Duration,                 // 100 ms
    pub check_window: Duration,                        // 200 ms
    pub check_interval: Duration,                      // 1 ms
    pub clear_frl: ClearFrl,                           // IfSinkDeclaresFrl
    pub source_version: SourceVersionWrite,            // EveryBringUp
    pub output_during_sink_write: OutputDuringSinkWrite, // Stopped
    pub tmds_config_write: TmdsConfigWrite,            // ReadModifyWrite
    pub on_tmds_config_failure: OnTmdsConfigFailure,   // CarryOn
    pub tear_down_on_error: bool,                      // true
    pub tear_down: TearDownConfig,                     // used after an error or a cancel
}
impl BringUpConfig {
    /// A deadline not longer than the wait, an interval not shorter than the window, or an
    /// interval of 0.
    pub const fn validate(&self) -> Result<(), ConfigError>;
}

#[non_exhaustive]
pub struct TearDownConfig {
    pub clear_sink: bool,                   // false
    pub sink_clear_timing: SinkClearTiming, // BeforeOutputStops
    pub scrambler_off: ScramblerOff,        // AfterSink
}

#[non_exhaustive] pub enum OutputDuringSinkWrite { Stopped, Running }
#[non_exhaustive] pub enum TmdsConfigWrite { ReadModifyWrite, WholeByte }
#[non_exhaustive] pub enum OnTmdsConfigFailure { CarryOn, Stop }
#[non_exhaustive] pub enum ClearFrl { IfSinkDeclaresFrl, EveryScdcSink }
#[non_exhaustive] pub enum SourceVersionWrite { EveryBringUp, IfSinkVersion1, WhenScrambling, Never }
#[non_exhaustive] pub enum SinkClearTiming { BeforeOutputStops, AfterOutputStops }
#[non_exhaustive] pub enum ScramblerOff { AfterSink, BeforeSink }
/// Tear-down's argument: whether the sink is still there. Exhaustive.
pub enum SinkPresence { Present, Gone }

/// Every problem `validate` found; `Display` and `core::error::Error`.
#[non_exhaustive]
pub struct ConfigError {
    pub deadline_always_missed: bool,
    pub check_reads_once: bool,
    pub check_interval_zero: bool,
}
```

All are `Copy`, every setter is a `const fn`, so firmware fixes its settings at compile time.

### The procedures' results

`S` is the SCDC error (`TmdsScdc::Error`), `P` the PHY error (`TmdsPhy::Error`).

```rust
#[non_exhaustive]
pub enum BringUpOutcome<S, P> {
    Up(LinkUp<S>),
    #[non_exhaustive]
    Cancelled { at: CancelPoint, cleanup: Cleanup<S, P>, warnings: Warnings<S> },
}

#[non_exhaustive]
pub struct LinkUp<S> {
    pub link: TmdsLinkParams,
    pub sink_written_at: Option<Timestamp>,   // None: no write was due
    pub output_started_at: Timestamp,
    pub check: ScramblingCheck<S>,            // never CheckResult::Cancelled
    pub warnings: Warnings<S>,
}

/// Each kind at most once per bring-up.
#[non_exhaustive]
pub enum BringUpWarning<S> {
    FrlRateClearFailed(S),
    FltUpdateClearFailed(UpdateError<S>),
    SinkVersionReadFailed(S),
    SourceVersionWriteFailed(S),
    TmdsConfigWriteFailed {
        error: UpdateError<S>,                               // Read: nothing was written
        read_back: Option<Result<TmdsConfigReading, S>>,     // a plain link's read-back
    },
    DeadlineMissed { by: Duration },
    ScramblingNotConfirmed { result: CheckResult },          // NotSet or Unreadable
}

/// Fixed storage for the warnings, in the order they came: `iter_warnings`, `len`, `is_empty`.
pub struct Warnings<S> { /* private */ }

#[non_exhaustive]
pub enum BringUpError<S, P> {
    Scdc { step: TmdsStep, error: S, output: OutputState, cleanup: Cleanup<S, P>, warnings: Warnings<S> },
    Phy { step: TmdsStep, error: P, output: OutputState, cleanup: Cleanup<S, P>, warnings: Warnings<S> },
    VideoMismatch { link_rate_khz: u32, video_rate_khz: Option<u32> },   // before any I/O
}

#[non_exhaustive]
pub enum Cleanup<S, P> {
    TornDown(Result<TornDown<S>, TearDownError<S, P>>),
    Skipped,   // tear_down_on_error off, or a cancel seen at entry
}

pub enum OutputState { Stopped, MayBeRunning }   // exhaustive

#[non_exhaustive]
pub struct ScramblingCheck<S> {
    pub result: CheckResult,
    pub reads: u32,
    pub failed_reads: u32,
    pub first_error: Option<FailedRead<S>>,   // { error, after }
    pub set_after: Option<Duration>,          // from the check's start
    pub read_cap_reached: bool,
}
#[non_exhaustive]
pub enum CheckResult { NotApplicable, Set, NotSet, Unreadable, Cancelled }

#[non_exhaustive] pub struct TornDown<S> { pub sink: SinkClear<S> }
/// At least one PHY step failed; each field holds that step's error.
#[non_exhaustive]
pub struct TearDownError<S, P> { pub sink: SinkClear<S>, pub scrambler: Option<P>, pub output: Option<P> }
#[non_exhaustive]
pub enum SinkClear<S> { NotRequested, NothingToClear, SkippedSinkGone, Cleared, Failed(S) }

#[non_exhaustive]
pub enum ReconnectCheck<S> {
    Matches, Lost { read: TmdsConfigReading }, Unreadable(S), NotApplicable, SinkChanged,
}

#[non_exhaustive]
pub struct Restored<S> {
    pub sink_written_at: Option<Timestamp>,
    pub check: ScramblingCheck<S>,
    pub write_failed: Option<UpdateError<S>>,
}
#[non_exhaustive]
pub enum RestoreError<S, P> {
    Scdc(UpdateError<S>),
    Phy { error: P, sink_written_at: Option<Timestamp>, write_failed: Option<UpdateError<S>> },
}
```

All are `Debug, Clone, Copy, PartialEq, Eq` where `S` and `P` are. `BringUpError`,
`TearDownError` and `RestoreError` implement `Display` and `core::error::Error`, with the
SCDC error as the source (a PHY error, which is only `Debug`, has none). The warnings live in fixed
storage, one slot per kind, so an outcome needs no `alloc`.

- **Why `Cancelled` is an outcome, not an error:** the caller asked for it, and the link
  was torn down as asked.
- **Why the check is part of `LinkUp`, not a condition of it:** the link is up and running
  whatever the sink reports; the result tells the caller whether to repeat, and how soon.
- **Why the errors carry the warnings and the cleanup:** a caller that only sees the error
  still learns everything that happened before it.

### The SCDC trait

```rust
pub trait TmdsScdc {
    type Error: hdmi_hal::ddc::DdcError;
    fn write_tmds_config(&mut self, config: SinkTmdsConfig) -> Result<(), Self::Error>;
    fn update_tmds_config(&mut self, config: SinkTmdsConfig) -> Result<(), UpdateError<Self::Error>>;
    fn read_tmds_config(&mut self) -> Result<TmdsConfigReading, Self::Error>;
    fn read_scrambling_status(&mut self) -> Result<ScramblingStatus, Self::Error>;
    fn read_sink_version(&mut self) -> Result<u8, Self::Error>;
    fn write_source_version(&mut self, version: u8) -> Result<(), Self::Error>;
    fn clear_frl_rate(&mut self) -> Result<(), Self::Error>;
    fn clear_flt_update(&mut self) -> Result<bool, UpdateError<Self::Error>>;   // whether it was set
}

/// An operation of a read and a write, and which failed: exhaustive, as it has two halves.
/// `Display`, `core::error::Error`, and `DdcError` with the failed half's kind.
pub enum UpdateError<E> { Read(E), Write(E) }

/// What the sink reports in `Scrambling_Status` (0x21), with the byte read (`raw()`).
#[non_exhaustive]
pub struct ScramblingStatus { pub set: bool /* , raw: private */ }
```

The sink-side operations the procedures make, and nothing more:

- **`write_tmds_config`** writes the whole byte, the two bits as given and the others 0;
  **`update_tmds_config`** reads `TMDS_Config`, sets the two bits and writes the byte back
  with the others as read, writing nothing after a failed read. The bit layout is the
  implementation's, so the read-modify-write is too.
- **`clear_frl_rate`** writes `Config_1` (0x31) as 0, `FRL_Rate` and `FFE_Levels` both, as
  Amlogic does; amdgpu reads it first and writes only when `FRL_Rate` is not 0 [36]. The
  setting has already decided the clear is wanted, so the read would save nothing.
- **`clear_flt_update`** reads `Update_0` (0x10) and, when `FLT_update` is set, writes it
  back as 1, which clears it, as both sources do [36]. It writes that flag alone, as amdgpu
  does; Amlogic writes back every flag it read. Chosen, because the other flags belong to
  whoever reads them next, such as a link health monitor. Two methods, so the bring-up can say which
  register's clear failed.
- **The error is a `DdcError`**, whose kind tells a failure that will not pass (`Detached`,
  `Unsupported`) from one that may; the procedures poll through the second and stop on the
  first. An implementation over an `ScdcTransport` passes its errors through.

It is the crate's own trait, not culvert's client, so a change to it touches only this crate,
and a firmware with its own SCDC code, a kernel driver whose platform already has SCDC
helpers, or a test double implements eight methods rather than a whole register map.

**The culvert adapter** (`culvert` feature): `TmdsScdc` for `culvert::Scdc<T>` over any
`ScdcTransport`. Its error, `CulvertError<E>`, wraps culvert's `ScdcError<E>`: its kind is
the transport's own for a transport error, and `Unsupported` for a request culvert refuses,
which would be refused again. It is `Copy` and `PartialEq` where culvert's error is, so the
outcomes stay so, and prints and chains as culvert's error does. `update_tmds_config` uses culvert's own read-modify-write, and
the bytes read reach `TmdsConfigReading::raw` and `ScramblingStatus::raw`.

---

## Diagnostics

Each procedure has a plain form and a `_with_events` form that calls `FnMut(TmdsEvent)` with
every step (`bring_up` and `bring_up_with_events`, and so on). A callback needs no buffer, so
nothing overflows and the API is the same in every build; a caller that wants a list pushes
each event into its own. There is no logging.

```rust
#[non_exhaustive]
pub struct TmdsEvent {
    pub at: Timestamp,          // from the procedure's own clock
    pub kind: TmdsEventKind,    // #[non_exhaustive], as is each variant with fields
}
```

- **Stamped by the procedure,** from the clock it already holds: the timing is the point
  (the write, the wait, output start, the check).
- **One kind per step and per decision**, with the values written or read: the start, with
  the link and the settings in force; each step done (the FRL clear, `Sink_Version` read,
  `Source_Version` written, output stopped, `TMDS_Config` written or read, the PHY
  configured, the scrambler set, the wait spent, output started); each step skipped, with
  the rule that skipped it (`FrlClearSkip`, `SourceVersionSkip`, `TmdsConfigSkip`,
  `SinkClearSkip`); each step failed, with its `TmdsStep`, whether it ends the procedure, and
  for SCDC the error's `DdcErrorKind`; a missed deadline; the check, **one event per window**
  with what `ScramblingCheck` records; a cancellation, with its `CancelPoint`; and the end.
- **No error values,** only their kinds: the values stay in the outcome or the error, which
  own them, so neither error type has to be `Clone`, and `TmdsEvent` is `Copy` with no type
  parameters, so an embedded caller can send it through a channel.
- **Events explain outcomes:** every warning and every error is also an event, with its
  step, so a tool that only listens can explain every result. A failed read-modify-write of
  `TMDS_Config` names its half by its step (`ReadTmdsConfig` or `WriteTmdsConfig`); which
  half of the `FLT_update` clear failed is only in the warning's value, as are the error
  values themselves.

**A fixed maximum per procedure,** since every step records at most one event per call and
the check one per window: `MAX_BRING_UP_EVENTS` (which includes the tear-down after an error
or a cancel), `MAX_TEAR_DOWN_EVENTS`, `MAX_RECONNECT_CHECK_EVENTS` and
`MAX_QUICK_RESTORE_EVENTS`. A caller without `alloc` sizes its channel or buffer from them and
never drops an event.

---

## Interface Boundaries

### The core and the sync driver

```rust
// spiritlevel::procedure: the core, written once as async fns
#[allow(async_fn_in_trait)]
pub trait TmdsIo {
    type ScdcError: hdmi_hal::ddc::DdcError;
    type PhyError: core::fmt::Debug;
    // `TmdsScdc`'s eight methods and `TmdsPhy`'s four I/O methods, as `async fn`
    fn now(&self) -> Timestamp;
    async fn delay(&mut self, duration: Duration);
    fn cancelled(&self) -> bool;
}
pub async fn bring_up<Io: TmdsIo, F: FnMut(TmdsEvent)>(
    io: &mut Io, link: &TmdsLinkParams, video: TmdsVideo, config: &BringUpConfig, record: &mut F,
) -> Result<BringUpOutcome<Io::ScdcError, Io::PhyError>, BringUpError<Io::ScdcError, Io::PhyError>>;
// tear_down(io, link, config, presence, record), check_reconnect(io, link, current_sink, record),
// quick_restore(io, link, config, record)

// spiritlevel: the sync driver
pub struct TmdsLink<S, P, K, D, X = NoCancel> { /* the five parts */ }
impl<S: TmdsScdc, P: TmdsPhy, K: Clock, D: Delay> TmdsLink<S, P, K, D, NoCancel> {
    pub fn new(scdc: S, phy: P, clock: K, delay: D) -> Self;
}
impl<S: TmdsScdc, P: TmdsPhy, K: Clock, D: Delay, X: Cancel> TmdsLink<S, P, K, D, X> {
    pub fn with_cancel<X2: Cancel>(self, cancel: X2) -> TmdsLink<S, P, K, D, X2>;
    pub fn bring_up(&mut self, link: &TmdsLinkParams, video: TmdsVideo, config: &BringUpConfig) -> …;
    // bring_up_with_events, tear_down(_with_events), check_reconnect(_with_events),
    // quick_restore(_with_events)
    pub fn into_parts(self) -> (S, P, K, D, X);
    // scdc, scdc_mut, phy, phy_mut, clock: the parts between procedures
}

pub use hdmi_hal::cancel::{Cancel, NoCancel};   // for AtomicBool, &T and NoCancel
```

- **`TmdsIo` flattens the I/O** into one trait, so the core sees one bound and a test drives
  it through one double; a driver implements it over its parts. `TmdsLink` is that driver for
  sync parts: their calls complete at once, so it polls the core's future to completion
  without a runtime, and the `Delay` blocks inside it. An async driver awaits the same
  futures.
- **`Cancel` is a trait,** not a bare `&AtomicBool`, so the driver needs no lifetime unless
  it is given a flag, and a platform with its own primitive implements one method.
  `NoCancel`, the default, never cancels. It is hdmi-hal's, so one flag type serves every
  procedure in the stack, FRL training included.
- **One value can be both clock and delay:** implement `Clock` and `Delay` for a reference
  to it (`&Time`, keeping the time in a `Cell`) and pass the reference twice.

### Below: hdmi-hal and the SCDC implementation

From [hdmi-hal](https://github.com/ashlar-display/hdmi-hal) the procedures use:

| Trait | What for |
|---|---|
| `TmdsPhy` | `stop_output` (bring-up step 1, tear-down), `configure` (rate, ratio, video) and `set_scrambling` (step 3, tear-down, the quick restore), `start_output` (step 5); `capabilities`, through `SourceTmdsFacts::from`, for `choose` |
| `Clock` | `now()`: the write time, the deadline, the check's window, the events |
| `Delay` | the ratio wait and the check's interval, "at least" the duration given |

Start and stop are separate calls, so the output stays off while the sink is written, and
`configure` sets rate, ratio and video without starting output. Powering the PHY on and off
is hdmi-hal's `PhyPower`, which the caller calls, not the procedures: on unplug, after a
tear-down with `SinkPresence::Gone`.

The SCDC side is `TmdsScdc` ("The SCDC trait"), implemented by the caller or by culvert's
adapter.

### Above: the caller

The caller owns hotplug, the EDID and negotiation, and retries. How a caller maps its events
onto the procedures:

| When | Calls |
|---|---|
| A TMDS mode is to be shown | `choose` (sink facts from the EDID, source facts from `TmdsPhy::capabilities`, the policy), then `bring_up` |
| Before a mode change | `tear_down` with the sink present |
| Before FRL training, from a TMDS link | `tear_down` with `clear_sink` ("Tear-down") |
| On unplug | `tear_down` with `SinkPresence::Gone`, then power the PHY off |
| A hotplug while the link is up | read the EDID again; for the same sink, `check_reconnect` with its current facts; on `Lost`, `tear_down` and `bring_up`, or `quick_restore` |
| The check ended `NotSet` | `quick_restore` again later |

A DRM driver maps them onto its hooks the same way: atomic enable to `bring_up`, disable to
`tear_down`, its hotplug handler to `check_reconnect`; `tear_down_on_error` keeps a failed
enable, which the hook cannot report, from leaving a half-started output.

---

## `no_std`, `alloc`, and `async`

`#![no_std]` without `alloc` in every build, and `#![forbid(unsafe_code)]`. `choose` is a
pure `const fn`. The procedures are `async fn`s over `TmdsIo`, and `TmdsLink` polls them to
completion with a no-op waker, without a runtime; their outcomes use fixed storage and their
events a callback, so nothing needs `alloc`. CI builds the crate for a bare target
(`thumbv7em-none-eabi`) with and without default features and with `culvert`, and checks the
MSRV (Rust 1.85).

An async driver over hdmi-hal-async's traits, with futures that can be `Send`, is planned
as a companion crate; it drives the same core. Whatever drives it, a procedure is stopped
through its cancel flag, not by dropping its future (with `select`, a timeout or an
aborted task): a dropped call leaves the PHY and the sink in an unknown state, and the
caller loses the tear-down that `Cancelled` carries.

---

## Testing

**Choosing the link.** The input space is small, so the tests cover it whole:

- **Every combination:** both thresholds × the sink facts × the source facts × the policy,
  at rates either side of and at 340 000 kHz, from 0 to `u32::MAX`; each case checked
  against the rules, including the `ScramblingDecision` and `ParamsError`.
- **The boundary:** 340 000 kHz gives 1/10 with `Above340`; with `AtOrAbove340` it gives
  1/40 when both ends can scramble and the plain 1/10 link, with the reason, when one
  cannot; 340 001 kHz gives 1/40, or `ScramblingUnsupported`.
- **The gate on `LTE_340Mcsc_scramble`:** a sink that declares it without scrambling
  support gets no low-rate scrambling.
- **Every reason:** each `ScramblingOff` flag and each `ScramblingUnsupported` flag is set
  exactly when its own fact blocks scrambling, whatever the others are.
- **Invariants:** `sink_config()` is `None` exactly when no write is due (no SCDC, or a
  plain link the gate leaves unwritten), and otherwise matches `clock_ratio()` and
  `scrambling()`; `scrambling()` is true exactly for `Required` and `LowRate`;
  `rate_khz()` returns the input.
- **`const` use:** tests evaluate `choose` and the constructors in `const` items, so a
  change that breaks `const fn` fails the build.
- **`From` impls:** every combination of the HF-SCDB fields against a literal table of
  expected facts, and `None` maps to `SinkTmdsFacts::NONE`; the PHY's capabilities map to
  the source facts.

**The procedures** run against a double of `TmdsIo` that records every call, answers from a
few registers, fails what a test tells it to, and advances its clock on every read and
delay:

- **Each step and its order,** for both bring-up orders, plain and scrambled links, both
  write forms, and every setting's options.
- **Every failure:** each SCDC step failing with a transient and a non-transient error, each
  PHY call failing, and what each leaves (the warning, the error, the output's state, the
  cleanup).
- **The check:** a sink that reports at once, late or never; failed reads; a gone bus; a
  clock that does not advance, ended by the read count; a zero window.
- **Cancellation:** a sweep that sets the flag after every operation of a full bring-up and
  checks where it is seen and that the tear-down follows.
- **The event bounds:** every combination of link, sink, order, write form and failure,
  checked against `MAX_BRING_UP_EVENTS`, and each other procedure against its own.
- **The sync driver** over simple parts, and the culvert adapter over a register-level
  `ScdcTransport`.
- **The README's examples** run as doctests.

CI measures line coverage and fails if it drops more than 0.1 percentage points below the recorded
baseline.

---

## Design Principles

- **Procedure, not policy.** Where HDMI sources differ, the behaviour is a setting with the
  majority as default (rules 3 and 4); the defaults are documented and changeable.
- **Every reason, not the first.** A decision or an error carries every condition that
  applies, each judged on its own fact, so a diagnostic tool's user sees all of them at
  once instead of fixing one and meeting the next. They fit in a `Copy` value without
  `alloc`.
- **Cited behaviour.** Each rule cites the public implementations it follows; where
  `spiritlevel` departs from them, the rule says so and why.
- **The output stays consistent.** The PHY's settings and the sink's register come from one
  value that only the rules can build.
- **Stable output types.** Output structs and enums are `#[non_exhaustive]`, so fields and
  reasons can be added without breaking callers; `ClockRatio`, a single register bit, is
  exhaustive.
- **Interfaces, not implementations.** The procedures run over traits: hdmi-hal's for the
  PHY, clock and delay, and the crate's own `TmdsScdc`; culvert's adapter and
  display-types' conversions are optional conveniences.

---

## What comes next

An async companion crate, testing against a simulated sink, and what is under
consideration are on the [roadmap](roadmap.md).

---

## Sources

Driver source read at these commits; line numbers refer to them.

- Linux, github.com/torvalds/linux `e9954f3fbddd` (2026-10-31)
- Xilinx embeddedsw, github.com/Xilinx/embeddedsw `97f2baf7f69e` (2026-06-24)
- Amlogic, github.com/CoreELEC/common_drivers `8ca9b6c3b715` (2026-10-31)

|      | Source                              | Location                                                                                                                                                                                 |
|------|-------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [1]  | Linux DRM helper, vc4 (one lineage) | `drivers/gpu/drm/display/drm_hdmi_helper.c:460` (threshold), `476–482`; `drivers/gpu/drm/display/drm_hdmi_state_helper.c:600` (threshold); `drivers/gpu/drm/vc4/vc4_hdmi.c:134–141`, `815–816` |
| [2]  | Linux DRM state helper              | `drivers/gpu/drm/display/drm_hdmi_state_helper.c:599` (low-rate scrambling a TODO)                                                                                                       |
| [3]  | i915                                | `drivers/gpu/drm/i915/display/intel_hdmi.c:2433–2435`, `2793–2795`                                                                                                                       |
| [4]  | dw-hdmi                             | `drivers/gpu/drm/bridge/synopsys/dw-hdmi.c:1392–1394`, `1400–1402`, `1424–1431`, `2101–2102`, `2118`                                                                                     |
| [5]  | amdgpu                              | `drivers/gpu/drm/amd/display/dc/link/protocols/link_ddc.c:571–613`; `dc/core/dc_stream.c:158`; `amdgpu_dm/amdgpu_dm_connector.c:1520–1521`; `dc/dce/dce_stream_encoder.c:621`, `629–640` |
| [6]  | nouveau                             | `drivers/gpu/drm/nouveau/dispnv50/disp.c:797`, `800–815`                                                                                                                                 |
| [7]  | Tegra                               | `drivers/gpu/drm/tegra/sor.c:2165–2181`, `2202`                                                                                                                                          |
| [8]  | MediaTek v2                         | `drivers/gpu/drm/mediatek/mtk_hdmi_v2.c:86–100`, `746`                                                                                                                                   |
| [9]  | Xilinx                              | `XilinxProcessorIPLib/drivers/v_hdmitx1/src/xv_hdmitx1.c:630–635`, `742–744`; `v_hdmitxss1/src/xv_hdmitxss1.c:2938–2957`                                                                 |
| [10] | Amlogic                             | `drivers/media/vout/hdmitx21/hw/hdmi_tx_hw.c:668–676`, `2780–2799`, `2889–2906`                                                                                                          |
| [11] | Linux EDID parser                   | `drivers/gpu/drm/drm_edid.c:6340–6356` (`scrambling.supported`: SCDC present and a non-zero `Max_TMDS_Character_Rate`; `scrambling.low_rates` only within that)                          |
| [12] | dw-hdmi family (dw-hdmi, Meson and Rockchip glue) | `drivers/gpu/drm/bridge/synopsys/dw-hdmi.c:1406–1413` (comment: 1 to 100 ms from the ratio write until transmission resumes), `1646–1675` (PHY off, ratio write, 100 ms above 340 Mcsc, PHY on); `meson/meson_dw_hdmi.c:399–403`; `rockchip/dw_hdmi-rockchip.c:352–354` |
| [13] | i915, enable path                   | `drivers/gpu/drm/i915/display/intel_ddi.c:3440–3445` (sink write), `3528` (port buffers enabled)                                                                                          |
| [14] | amdgpu, TMDS enable                 | `drivers/gpu/drm/amd/display/dc/link/link_dpms.c:1908–1912` (sink write), `1931–1940` (output enabled), `1942–1943`; `link/protocols/link_ddc.c:602–613` (one byte, `3` above 340 MHz)    |
| [15] | MediaTek v2, enable path            | `drivers/gpu/drm/mediatek/mtk_hdmi_v2.c:87–101`, `746` (scrambler, then sink), `1039` → `1045` (`phy_power_on` after)                                                                    |
| [16] | Xilinx, stream start                | `v_hdmitxss1/src/xv_hdmitxss1.c:2213–2217`; `v_hdmitx1/src/xv_hdmitx1.c:633–638`; pass-through example `v_hdmitxss1/examples/xhdmi_example/PassThrough/xhdmi_exdes_sm_tx.c:601`, `2118–2121` (TMDS clock off), `2531–2545` (stream start, then clock on) |
| [17] | Amlogic, mode set                   | `drivers/media/vout/hdmitx_common/hdmitx_mode_set.c:457–460` (PHY off); `hdmitx21/hw/hdmi_tx_hw.c:1475` → `3628–3631` → `2889–2904` (one byte, then source), `1578` (PHY on)               |
| [18] | vc4, Tegra (output running)         | `drivers/gpu/drm/vc4/vc4_hdmi.c:1690–1692`, `815–820`; `drivers/gpu/drm/tegra/sor.c:2606`, `2631`, `2658`, `2177–2180`                                                                  |
| [19] | i915, scrambling check              | `drivers/gpu/drm/i915/display/intel_hdmi.c:2749–2754` (1 ms polls for 200 ms, logged only), `2767–2770` (comment: 100 ms)                                                                |
| [20] | Plain link: `TMDS_Config` written at every bring-up | i915 `intel_hdmi.c:2794–2795`; amdgpu `link_ddc.c:602–613`; dw-hdmi `dw-hdmi.c:1428–1430`, `2131–2134`, `2303–2306`; nouveau `disp.c:800–812`; MediaTek v2 `mtk_hdmi_v2.c:87–101`, `746`; Xilinx `xv_hdmitxss1.c:2213–2217`, `xv_hdmitx1.c:663–668`, `737–744`; Amlogic `hdmi_tx_hw.c:2889–2904` |
| [21] | Low-rate scrambling check           | i915 `intel_hdmi.c:2433–2435`, `2745–2754`; amdgpu `link_ddc.c:629–643`                                                                                                                 |
| [22] | amdgpu, before `TMDS_Config`        | `drivers/gpu/drm/amd/display/dc/link/protocols/link_ddc.c:585–588` (SCDC gate), `589–590` (FRL cleared), `592–600` (`Source_Version` when `Sink_Version` is 1), `602` (`TMDS_Config`)    |
| [23] | Amlogic, clearing FRL               | `drivers/media/vout/hdmitx21/hdmi_tx_main.c:466–488` (only with FRL and SCDC declared)                                                                                                    |
| [24] | Helper lineage, Tegra: tear-down only | `drivers/gpu/drm/vc4/vc4_hdmi.c:807–810`, `857–858`, `922`; `drivers/gpu/drm/tegra/sor.c:2149–2155`, `2202`, `2218`                                                                     |
| [25] | Which sinks get the write           | any SCDC sink: amdgpu `link_ddc.c:585–588`, MediaTek v2 `mtk_hdmi_v2.c:96–99`, Xilinx `xv_hdmitx1.c:789–806`; scrambling support: i915 `intel_hdmi.c:2785–2786`, dw-hdmi `dw-hdmi.c:1380–1404`, nouveau `disp.c:796`; every sink: Amlogic `hdmi_tx_hw.c:2893–2901` |
| [26] | A failed `TMDS_Config` write        | logged, then continued: i915 `intel_ddi.c:3440–3445`, dw-hdmi-qp `dw-hdmi-qp.c:558–560`, nouveau `disp.c:812–815`; result unused: amdgpu `link_ddc.c:611`, Xilinx `xv_hdmitxss1.c:2214–2217`, vc4 `vc4_hdmi.c:815–816`, Tegra `sor.c:2177–2178`, MediaTek v2 `mtk_hdmi_v2.c:98–99`, dw-hdmi `dw-hdmi.c:1428–1430`; no result: Amlogic `hdmi_tx_hw.c:2780–2798` |
| [27] | A failed FRL clear                  | amdgpu `drivers/gpu/drm/amd/display/dc/link/protocols/link_hdmi_frl.h:30`, `32` (`void`), called at `link_ddc.c:589–590`; Amlogic `drivers/media/vout/hdmitx21/hdmi_tx_main.c:484–487` (results unused) |
| [28] | Tear-down without clearing          | dw-hdmi `dw-hdmi.c:2408–2416`, `2979–2990`; nouveau `disp.c:800–812` (enable only); MediaTek v2 `mtk_hdmi_v2.c:1071–1104`; Xilinx `xhdmi_exdes_sm_tx.c:2020–2035`, `2620–2636`; Amlogic `hdmitx_common/hdmitx_mode_set.c:785–792`, `hdmitx21/hdmi_tx_main.c:4199–4222` |
| [29] | Tear-down clearing the sink, and its order | i915 `intel_ddi.c:3614–3626` (in `disable`, logged), `3230` (buffers off in `post_disable`), `3281` (the scrambling transcoder off, after the sink), `5345–5347`; amdgpu `link_dpms.c:2442`, `2460–2465`, `2487–2491`; helper `drm_hdmi_helper.c:602–630`; vc4 `vc4_hdmi.c:831–860`, `908–922`; dw-hdmi-qp `dw-hdmi-qp.c:599–601`; Tegra `sor.c:2149–2162`, `2218–2220` |
| [30] | Tear-down with the sink gone        | helper `drm_hdmi_helper.c:622–624` (connected only); amdgpu `link_ddc.c:582–583` (only with a sink); vc4 `vc4_hdmi.c:831–860`, Tegra `sor.c:2149–2162` (regardless)                       |
| [31] | Amlogic, clearing on suspend (quirk) | `hdmitx21/hdmi_tx_main.c:331`, `353–361`; `hdmitx_common/hdmitx_compliance.c:21–25`, `63–76`                                                                                       |
| [32] | Helper lineage, reconnect check     | i915 `intel_ddi.c:4824`, `4847–4869` (conditions, read, both bits), `4858–4862` (failed read logged), `4871–4880` (full mode set), `4908–4915` (on hotplug); helper `drm_hdmi_helper.c:632–731` (`drm_connector_hdmi_sync_scdc`; comment 640–641, check 677–709, reset 712–726); vc4 `vc4_hdmi.c:320–354`, `376–392` |
| [33] | dw-hdmi, reconnect                  | `drivers/gpu/drm/bridge/synopsys/dw-hdmi.c:3084–3109` (HPD and RX sense), `2397–2438` (PHY off, then the whole setup)                                                                  |
| [34] | Xilinx, HPD toggle                  | pass-through example `xhdmi_exdes_sm_tx.c:1394–1403` (`StreamStart` on a toggle); `xv_hdmitxss1.c:2213–2217`; toggle timing `xv_hdmitx1.c:205–224`                                     |
| [35] | Amlogic, restores without reading   | `drivers/media/vout/hdmitx21/hdmi_tx_main.c:5053–5062` (start-up with HPD high), `4744–4796` (stalled clock); `hw/hdmi_tx_hw.c:2972–2985` (the sink write only)                                                                             |
| [36] | The FRL clear's registers          | amdgpu `drivers/gpu/drm/amd/display/dc/link/protocols/link_hdmi_frl.c:178–200` (`FLT_update`), `394–415` (`Config_1`); Amlogic `drivers/media/vout/hdmitx21/hdmi_tx_main.c:484–487` |
| [37] | Linux's SCDC helper                 | `drivers/gpu/drm/display/drm_scdc_helper.c:221–245`, `277–307` (read-modify-write; nothing written after a failed read), `300–305` (1–2 ms after every ratio write; the comment gives 1 to 100 ms); its callers `intel_hdmi.c:2794–2795`, `vc4_hdmi.c:815–816`, `drm_hdmi_helper.c:477–481`, `dw-hdmi.c:1428–1430`, `sor.c:2177–2178`, `mtk_hdmi_v2.c:98–99`; nouveau `disp.c:800–812` and Xilinx `xv_hdmitx1.c:643–680`, 715–757 (read-modify-write in their own code) |
| [38] | A failed `TMDS_Config` write, dissent | DRM helper `drivers/gpu/drm/display/drm_hdmi_helper.c:576–586` (no source scrambler, both sink bits cleared); nouveau `drivers/gpu/drm/nouveau/dispnv50/disp.c:800–804` (returns on a failed read) |
| [39] | When `Source_Version` is written    | amdgpu `link_ddc.c:592–600` (when `Sink_Version` is 1); helper `drm_hdmi_helper.c:544`, `564`, `drm_scdc_helper.c:322–350` (scrambled links, only to a sink reporting a version); dw-hdmi `dw-hdmi.c:2112–2115` (scrambled links, its version, 0 included); Xilinx `xv_hdmitx1.c:789–806` (unconditionally, at detection); Amlogic `hdmitx21/hdmi_tx_main.c:3859–3867` (FRL path only) |