1 .. SPDX-License-Identifier: GPL-2.0
2
3 ========
4 HDMI CEC
5 ========
6
7 Supported hardware in mainline
8 ==============================
9
10 HDMI Transmitters:
11
12 - Exynos4
13 - Exynos5
14 - STIH4xx HDMI CEC
15 - V4L2 adv7511 (same HW, but a different drive
16 - stm32
17 - Allwinner A10 (sun4i)
18 - Raspberry Pi
19 - dw-hdmi (Synopsis IP)
20 - amlogic (meson ao-cec and ao-cec-g12a)
21 - drm adv7511/adv7533
22 - omap4
23 - tegra
24 - rk3288, rk3399
25 - tda998x
26 - DisplayPort CEC-Tunneling-over-AUX on i915,
27 - ChromeOS EC CEC
28 - CEC for SECO boards (UDOO x86).
29 - Chrontel CH7322
30
31
32 HDMI Receivers:
33
34 - adv7604/11/12
35 - adv7842
36 - tc358743
37
38 USB Dongles (see below for additional informat
39 dongles):
40
41 - Pulse-Eight: the pulse8-cec driver implement
42 ``persistent_config``: by default this is of
43 will store the current settings to the devic
44 it the next time the device is connected to
45
46 - RainShadow Tech. Note: this driver does not
47 module option of the Pulse-Eight driver. The
48 have no plans to add this feature. But I acc
49
50 - Extron DA HD 4K PLUS HDMI Distribution Ampli
51 :ref:`extron_da_hd_4k_plus` for more informa
52
53 Miscellaneous:
54
55 - vivid: emulates a CEC receiver and CEC trans
56 Can be used to test CEC applications without
57
58 - cec-gpio. If the CEC pin is hooked up to a G
59 you can control the CEC line through this dr
60 injection as well.
61
62 - cec-gpio and Allwinner A10 (or any other dri
63 framework to drive the CEC pin directly): th
64 high-resolution timers. These timers are aff
65 speed up or slow down the clock to sync with
66 chronyd server will by default increase or d
67 1/12th. This will cause the CEC timings to g
68 add a 'maxslewrate 40000' line to chronyd.co
69 frequency change to 1/25th, which keeps the
70
71
72 Utilities
73 =========
74
75 Utilities are available here: https://git.linu
76
77 ``utils/cec-ctl``: control a CEC device
78
79 ``utils/cec-compliance``: test compliance of a
80
81 ``utils/cec-follower``: emulate a CEC follower
82
83 Note that ``cec-ctl`` has support for the CEC
84 used in some hotel displays. See http://www.ht
85
86 Note that the libcec library (https://github.c
87 the linux CEC framework.
88
89 If you want to get the CEC specification, then
90 the HDMI wikipedia page: https://en.wikipedia.
91 of the HDMI specification. HDMI 1.3 is freely
92 HDMI 1.4 w.r.t. CEC) and should be good enough
93
94
95 DisplayPort to HDMI Adapters with working CEC
96 =============================================
97
98 Background: most adapters do not support the C
99 and of those that do many did not actually con
100 Unfortunately, this means that while a CEC dev
101 is actually all alone in the world and will ne
102 CEC devices.
103
104 This is a list of known working adapters that
105 that properly connected the CEC pin. If you fi
106 but are not in this list, then drop me a note.
107
108 To test: hook up your DP-to-HDMI adapter to a
109 (typically a TV), then run::
110
111 cec-ctl --playback # Configure th
112 cec-ctl -S # Show the CEC
113
114 The ``cec-ctl -S`` command should show at leas
115 ourselves and the CEC device you are connected
116
117 General note: I have only seen this work with
118 PS186 chipsets and the MegaChips 2900. While M
119 I have never seen it work.
120
121 USB-C to HDMI
122 -------------
123
124 Samsung Multiport Adapter EE-PW700: https://ww
125
126 Kramer ADC-U31C/HF: https://www.kramerav.com/p
127
128 Club3D CAC-2504: https://www.club-3d.com/en/de
129
130 DisplayPort to HDMI
131 -------------------
132
133 Club3D CAC-1080: https://www.club-3d.com/en/de
134
135 CableCreation (SKU: CD0712): https://www.cable
136
137 HP DisplayPort to HDMI True 4k Adapter (P/N 2J
138
139 Mini-DisplayPort to HDMI
140 ------------------------
141
142 Club3D CAC-1180: https://www.club-3d.com/en/de
143
144 Note that passive adapters will never work, yo
145
146 The Club3D adapters in this list are all MegaC
147 are PS176 based and do NOT have the CEC pin ho
148 adapters above are known to work.
149
150 I suspect that MegaChips 2900 based designs in
151 whereas with the PS176 it is more hit-and-miss
152 likely to have the CEC pin hooked up, it looks
153 design for that chipset.
154
155
156 USB CEC Dongles
157 ===============
158
159 These dongles appear as ``/dev/ttyACMX`` devic
160 utility to create the ``/dev/cecX`` devices. S
161 has been added to ``inputattach`` 1.6.0. Suppo
162 been added to ``inputattach`` 1.6.1.
163
164 You also need udev rules to automatically star
165
166 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]
167 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]
168 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]
169
170 and these systemd services:
171
172 For Pulse-Eight make /lib/systemd/system/pulse
173
174 [Unit]
175 Description=inputattach for pulse8-cec
176
177 [Service]
178 Type=simple
179 ExecStart=/usr/bin/inputattach --pulse
180
181 For the RainShadow Tech make /lib/systemd/syst
182
183 [Unit]
184 Description=inputattach for rainshadow
185
186 [Service]
187 Type=simple
188 ExecStart=/usr/bin/inputattach --rains
189
190
191 For proper suspend/resume support create: /lib
192
193 [Unit]
194 Description=restart inputattach for ce
195 After=suspend.target
196
197 [Service]
198 Type=forking
199 ExecStart=/bin/bash -c 'for d in /dev/
200
201 [Install]
202 WantedBy=suspend.target
203
204 And run ``systemctl enable restart-cec-inputat
205
206 To automatically set the physical address of t
207 EDID changes, you can use ``cec-ctl`` with the
208
209 cec-ctl -E /sys/class/drm/card0-DP-1/e
210
211 This assumes the dongle is connected to the ca
212 you which output is used) and it will poll for
213 the Physical Address whenever they occur.
214
215 To automatically run this command you can use
216 ``crontab -e`` and add this line::
217
218 @reboot /usr/local/bin/cec-ctl -E /sys
219
220 This only works for display drivers that expos
221 such as the i915 driver.
222
223
224 CEC Without HPD
225 ===============
226
227 Some displays when in standby mode have no HDM
228 CEC is still enabled so connected devices can
229 message in order to wake up such displays. Unf
230 adapters can support this. An example is the O
231 level-shifter that is powered off when the HPD
232 blocking the CEC pin. Even though the SoC can
233 the level-shifter will prevent this from funct
234
235 There is a CEC capability flag to signal this:
236 If set, then the hardware cannot wake up displ
237
238 Note for CEC application implementers: the <Im
239 be the first message you send, don't send any
240 Certain very bad but unfortunately not uncommo
241 get very confused if they receive anything els
242 they won't wake up.
243
244 When writing a driver it can be tricky to test
245 ways to do this:
246
247 1) Get a Pulse-Eight USB CEC dongle, connect a
248 device to the Pulse-Eight, but do not conne
249 the display.
250
251 Now configure the Pulse-Eight dongle::
252
253 cec-ctl -p0.0.0.0 --tv
254
255 and start monitoring::
256
257 sudo cec-ctl -M
258
259 On the device you are testing run::
260
261 cec-ctl --playback
262
263 It should report a physical address of f.f.
264 command::
265
266 cec-ctl -t0 --image-view-on
267
268 The Pulse-Eight should see the <Image View
269 then something (hardware and/or software) i
270 message from going out.
271
272 To make sure you have the wiring correct ju
273 Pulse-Eight to a CEC-enabled display and ru
274 on your device: now there is a HPD, so you
275 arriving at the Pulse-Eight.
276
277 2) If you have another linux device supporting
278 you can just connect your device to that de
279 two HDMI outputs together. You won't have a
280 want for this test), but the second device
281
282 Otherwise use the same commands as in 1.
283
284 If CEC messages do not come through when there
285 need to figure out why. Typically it is either
286 or the software powers off the CEC core when t
287 first cannot be corrected of course, the secon
288 driver changes.
289
290
291 Microcontrollers & CEC
292 ======================
293
294 We have seen some CEC implementations in displ
295 to sample the bus. This does not have to be a
296 have timing issues. This is hard to discover u
297 CEC debugger (see the next section).
298
299 You will see cases where the CEC transmitter h
300 a longer time than is allowed. For directed me
301 if that happens the message will not be Acked
302 For broadcast messages no such mechanism exist
303
304 It's not clear what to do about this. It is pr
305 broadcast messages twice to reduce the chance
306 <Standby> and <Active Source> are candidates f
307
308
309 Making a CEC debugger
310 =====================
311
312 By using a Raspberry Pi 4B and some cheap comp
313 your own low-level CEC debugger.
314
315 The critical component is one of these HDMI fe
316 (full soldering type 1):
317
318 https://elabbay.myshopify.com/collections/came
319
320 The video quality is variable and certainly no
321 (594 MHz) video. You might be able to support
322 be limited to 1080p60 (148.5 MHz). But for CEC
323
324 You need a breadboard and some breadboard wire
325
326 http://www.dx.com/p/diy-40p-male-to-female-mal
327
328 If you want to monitor the HPD and/or 5V lines
329 these 5V to 3.3V level shifters:
330
331 https://www.adafruit.com/product/757
332
333 (This is just where I got these components, th
334 can get similar things).
335
336 The ground pin of the HDMI connector needs to
337 pin of the Raspberry Pi, of course.
338
339 The CEC pin of the HDMI connector needs to be
340 GPIO 6 and GPIO 7. The optional HPD pin of the
341 be connected via the level shifter to these pi
342 The optional 5V pin of the HDMI connector shou
343 level shifter to these pins: GPIO 25 and GPIO
344 5V lines is not necessary, but it is helpful.
345
346 This device tree addition in ``arch/arm/boot/d
347 will hook up the cec-gpio driver correctly::
348
349 cec@6 {
350 compatible = "cec-gpio";
351 cec-gpios = <&gpio 6 (GPIO_ACT
352 hpd-gpios = <&gpio 23 GPIO_ACT
353 v5-gpios = <&gpio 25 GPIO_ACTI
354 };
355
356 cec@7 {
357 compatible = "cec-gpio";
358 cec-gpios = <&gpio 7 (GPIO_ACT
359 hpd-gpios = <&gpio 12 GPIO_ACT
360 v5-gpios = <&gpio 22 GPIO_ACTI
361 };
362
363 If you haven't hooked up the HPD and/or 5V lin
364 lines.
365
366 This dts change will enable two cec GPIO devic
367 send/receive CEC commands and the other to mon
368 an unconfigured CEC adapter then it will use G
369 monitoring very accurate.
370
371 If you just want to monitor traffic, then a si
372 The minimum configuration is one HDMI female-f
373 and two female-female breadboard wires: one fo
374 pin to a ground pin on the Raspberry Pi, and t
375 CEC pin to GPIO 6 on the Raspberry Pi.
376
377 The documentation on how to use the error inje
378
379 ``cec-ctl --monitor-pin`` will do low-level CE
380 You can also store the CEC traffic to file usi
381 it later using ``--analyze-pin``.
382
383 You can also use this as a full-fledged CEC de
384 using ``cec-ctl --tv -p0.0.0.0`` or ``cec-ctl
385
386 .. _extron_da_hd_4k_plus:
387
388 Extron DA HD 4K PLUS CEC Adapter driver
389 =======================================
390
391 This driver is for the Extron DA HD 4K PLUS se
392 Amplifiers: https://www.extron.com/product/dah
393
394 The 2, 4 and 6 port models are supported.
395
396 Firmware version 1.02.0001 or higher is requir
397
398 Note that older Extron hardware revisions have
399 which may mean that CEC will not work. This is
400 E34814 and up.
401
402 The CEC support has two modes: the first is a
403 to manually control CEC for the HDMI Input and
404 full control, it is also complicated.
405
406 The second mode is an automatic mode, which is
407 ``vendor_id`` is set. In that case the driver
408 received in the input will be distributed to t
409 to use the /dev/cecX devices to talk to the co
410 the driver that configures everything and deal
411 changes.
412
413 The driver also takes care of the EDIDs: /dev/
414 read the EDIDs and (for the HDMI Input port) t
415
416 By default userspace is responsible to set the
417 according to the EDIDs of the connected displa
418 module option is set, then the driver will tak
419 of the HDMI Input based on the supported resol
420 Currently the driver only supports resolutions
421 displays support 4kp60, then it will advertise
422 it will fall back to an EDID that just reports
423
424 The status of the Extron is reported in ``/sys
425
426 The extron-da-hd-4k-plus driver implements the
427
428 ``debug``
429 ---------
430
431 If set to 1, then all serial port traffic is s
432
433 ``vendor_id``
434 -------------
435
436 The CEC Vendor ID to report to connected displ
437
438 If set, then the driver will take care of dist
439 on the input to the HDMI outputs. This is done
440
441 - <Standby>
442 - <Image View On> and <Text View On>
443 - <Give Device Power Status>
444 - <Set System Audio Mode>
445 - <Request Current Latency>
446
447 If not set, then userspace is responsible for
448 configure the CEC devices for HDMI Input and t
449
450 ``manufacturer_name``
451 ---------------------
452
453 A three character manufacturer name that is us
454 Input. If not set, then userspace is reponsibl
455 If set, then the driver will update the EDID a
456 resolutions supported by the connected display
457 anymore to manually set the EDID for the HDMI
458
459 ``hpd_never_low``
460 -----------------
461
462 If set, then the Hotplug Detect pin of the HDM
463 even if nothing is connected to the HDMI Outpu
464 then the Hotplug Detect pin of the HDMI input
465 Hotplug Detect pins of the HDMI Outputs are al
466
467 This option may be changed dynamically.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.