1.. SPDX-License-Identifier: GPL-2.0 2 3======== 4HDMI CEC 5======== 6 7Supported hardware in mainline 8============================== 9 10HDMI Transmitters: 11 12- Exynos4 13- Exynos5 14- STIH4xx HDMI CEC 15- V4L2 adv7511 (same HW, but a different driver from the drm adv7511) 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, nouveau and amdgpu 27- ChromeOS EC CEC 28- CEC for SECO boards (UDOO x86). 29- Chrontel CH7322 30 31 32HDMI Receivers: 33 34- adv7604/11/12 35- adv7842 36- tc358743 37 38USB Dongles (see below for additional information on how to use these 39dongles): 40 41- Pulse-Eight: the pulse8-cec driver implements the following module option: 42 ``persistent_config``: by default this is off, but when set to 1 the driver 43 will store the current settings to the device's internal eeprom and restore 44 it the next time the device is connected to the USB port. 45 46- RainShadow Tech. Note: this driver does not support the persistent_config 47 module option of the Pulse-Eight driver. The hardware supports it, but I 48 have no plans to add this feature. But I accept patches :-) 49 50- Extron DA HD 4K PLUS HDMI Distribution Amplifier. See 51 :ref:`extron_da_hd_4k_plus` for more information. 52 53Miscellaneous: 54 55- vivid: emulates a CEC receiver and CEC transmitter. 56 Can be used to test CEC applications without actual CEC hardware. 57 58- cec-gpio. If the CEC pin is hooked up to a GPIO pin then 59 you can control the CEC line through this driver. This supports error 60 injection as well. 61 62- cec-gpio and Allwinner A10 (or any other driver that uses the CEC pin 63 framework to drive the CEC pin directly): the CEC pin framework uses 64 high-resolution timers. These timers are affected by NTP daemons that 65 speed up or slow down the clock to sync with the official time. The 66 chronyd server will by default increase or decrease the clock by 67 1/12th. This will cause the CEC timings to go out of spec. To fix this, 68 add a 'maxslewrate 40000' line to chronyd.conf. This limits the clock 69 frequency change to 1/25th, which keeps the CEC timings within spec. 70 71 72Utilities 73========= 74 75Utilities are available here: https://git.linuxtv.org/v4l-utils.git 76 77``utils/cec-ctl``: control a CEC device 78 79``utils/cec-compliance``: test compliance of a remote CEC device 80 81``utils/cec-follower``: emulate a CEC follower device 82 83Note that ``cec-ctl`` has support for the CEC Hospitality Profile as is 84used in some hotel displays. See http://www.htng.org. 85 86Note that the libcec library (https://github.com/Pulse-Eight/libcec) supports 87the linux CEC framework. 88 89If you want to get the CEC specification, then look at the References of 90the HDMI wikipedia page: https://en.wikipedia.org/wiki/HDMI. CEC is part 91of the HDMI specification. HDMI 1.3 is freely available (very similar to 92HDMI 1.4 w.r.t. CEC) and should be good enough for most things. 93 94 95DisplayPort to HDMI Adapters with working CEC 96============================================= 97 98Background: most adapters do not support the CEC Tunneling feature, 99and of those that do many did not actually connect the CEC pin. 100Unfortunately, this means that while a CEC device is created, it 101is actually all alone in the world and will never be able to see other 102CEC devices. 103 104This is a list of known working adapters that have CEC Tunneling AND 105that properly connected the CEC pin. If you find adapters that work 106but are not in this list, then drop me a note. 107 108To test: hook up your DP-to-HDMI adapter to a CEC capable device 109(typically a TV), then run:: 110 111 cec-ctl --playback # Configure the PC as a CEC Playback device 112 cec-ctl -S # Show the CEC topology 113 114The ``cec-ctl -S`` command should show at least two CEC devices, 115ourselves and the CEC device you are connected to (i.e. typically the TV). 116 117General note: I have only seen this work with the Parade PS175, PS176 and 118PS186 chipsets and the MegaChips 2900. While MegaChips 28x0 claims CEC support, 119I have never seen it work. 120 121USB-C to HDMI 122------------- 123 124Samsung Multiport Adapter EE-PW700: https://www.samsung.com/ie/support/model/EE-PW700BBEGWW/ 125 126Kramer ADC-U31C/HF: https://www.kramerav.com/product/ADC-U31C/HF 127 128Club3D CAC-2504: https://www.club-3d.com/en/detail/2449/usb_3.1_type_c_to_hdmi_2.0_uhd_4k_60hz_active_adapter/ 129 130DisplayPort to HDMI 131------------------- 132 133Club3D CAC-1080: https://www.club-3d.com/en/detail/2442/displayport_1.4_to_hdmi_2.0b_hdr/ 134 135CableCreation (SKU: CD0712): https://www.cablecreation.com/products/active-displayport-to-hdmi-adapter-4k-hdr 136 137HP DisplayPort to HDMI True 4k Adapter (P/N 2JA63AA): https://www.hp.com/us-en/shop/pdp/hp-displayport-to-hdmi-true-4k-adapter 138 139Mini-DisplayPort to HDMI 140------------------------ 141 142Club3D CAC-1180: https://www.club-3d.com/en/detail/2443/mini_displayport_1.4_to_hdmi_2.0b_hdr/ 143 144Note that passive adapters will never work, you need an active adapter. 145 146The Club3D adapters in this list are all MegaChips 2900 based. Other Club3D adapters 147are PS176 based and do NOT have the CEC pin hooked up, so only the three Club3D 148adapters above are known to work. 149 150I suspect that MegaChips 2900 based designs in general are likely to work 151whereas with the PS176 it is more hit-and-miss (mostly miss). The PS186 is 152likely to have the CEC pin hooked up, it looks like they changed the reference 153design for that chipset. 154 155 156USB CEC Dongles 157=============== 158 159These dongles appear as ``/dev/ttyACMX`` devices and need the ``inputattach`` 160utility to create the ``/dev/cecX`` devices. Support for the Pulse-Eight 161has been added to ``inputattach`` 1.6.0. Support for the Rainshadow Tech has 162been added to ``inputattach`` 1.6.1. 163 164You also need udev rules to automatically start systemd services:: 165 166 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1002", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service" 167 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1001", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service" 168 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="ff59", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="rainshadow-cec-inputattach@%k.service" 169 170and these systemd services: 171 172For Pulse-Eight make /lib/systemd/system/pulse8-cec-inputattach@.service:: 173 174 [Unit] 175 Description=inputattach for pulse8-cec device on %I 176 177 [Service] 178 Type=simple 179 ExecStart=/usr/bin/inputattach --pulse8-cec /dev/%I 180 181For the RainShadow Tech make /lib/systemd/system/rainshadow-cec-inputattach@.service:: 182 183 [Unit] 184 Description=inputattach for rainshadow-cec device on %I 185 186 [Service] 187 Type=simple 188 ExecStart=/usr/bin/inputattach --rainshadow-cec /dev/%I 189 190 191For proper suspend/resume support create: /lib/systemd/system/restart-cec-inputattach.service:: 192 193 [Unit] 194 Description=restart inputattach for cec devices 195 After=suspend.target 196 197 [Service] 198 Type=forking 199 ExecStart=/bin/bash -c 'for d in /dev/serial/by-id/usb-Pulse-Eight*; do /usr/bin/inputattach --daemon --pulse8-cec $d; done; for d in /dev/serial/by-id/usb-RainShadow_Tech*; do /usr/bin/inputattach --daemon --rainshadow-cec $d; done' 200 201 [Install] 202 WantedBy=suspend.target 203 204And run ``systemctl enable restart-cec-inputattach``. 205 206To automatically set the physical address of the CEC device whenever the 207EDID changes, you can use ``cec-ctl`` with the ``-E`` option:: 208 209 cec-ctl -E /sys/class/drm/card0-DP-1/edid 210 211This assumes the dongle is connected to the card0-DP-1 output (``xrandr`` will tell 212you which output is used) and it will poll for changes to the EDID and update 213the Physical Address whenever they occur. 214 215To automatically run this command you can use cron. Edit crontab with 216``crontab -e`` and add this line:: 217 218 @reboot /usr/local/bin/cec-ctl -E /sys/class/drm/card0-DP-1/edid 219 220This only works for display drivers that expose the EDID in ``/sys/class/drm``, 221such as the i915 driver. 222 223 224CEC Without HPD 225=============== 226 227Some displays when in standby mode have no HDMI Hotplug Detect signal, but 228CEC is still enabled so connected devices can send an <Image View On> CEC 229message in order to wake up such displays. Unfortunately, not all CEC 230adapters can support this. An example is the Odroid-U3 SBC that has a 231level-shifter that is powered off when the HPD signal is low, thus 232blocking the CEC pin. Even though the SoC can use CEC without a HPD, 233the level-shifter will prevent this from functioning. 234 235There is a CEC capability flag to signal this: ``CEC_CAP_NEEDS_HPD``. 236If set, then the hardware cannot wake up displays with this behavior. 237 238Note for CEC application implementers: the <Image View On> message must 239be the first message you send, don't send any other messages before. 240Certain very bad but unfortunately not uncommon CEC implementations 241get very confused if they receive anything else but this message and 242they won't wake up. 243 244When writing a driver it can be tricky to test this. There are two 245ways to do this: 246 2471) Get a Pulse-Eight USB CEC dongle, connect an HDMI cable from your 248 device to the Pulse-Eight, but do not connect the Pulse-Eight to 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.f.f. Now run this 264 command:: 265 266 cec-ctl -t0 --image-view-on 267 268 The Pulse-Eight should see the <Image View On> message. If not, 269 then something (hardware and/or software) is preventing the CEC 270 message from going out. 271 272 To make sure you have the wiring correct just connect the 273 Pulse-Eight to a CEC-enabled display and run the same command 274 on your device: now there is a HPD, so you should see the command 275 arriving at the Pulse-Eight. 276 2772) If you have another linux device supporting CEC without HPD, then 278 you can just connect your device to that device. Yes, you can connect 279 two HDMI outputs together. You won't have a HPD (which is what we 280 want for this test), but the second device can monitor the CEC pin. 281 282 Otherwise use the same commands as in 1. 283 284If CEC messages do not come through when there is no HPD, then you 285need to figure out why. Typically it is either a hardware restriction 286or the software powers off the CEC core when the HPD goes low. The 287first cannot be corrected of course, the second will likely required 288driver changes. 289 290 291Microcontrollers & CEC 292====================== 293 294We have seen some CEC implementations in displays that use a microcontroller 295to sample the bus. This does not have to be a problem, but some implementations 296have timing issues. This is hard to discover unless you can hook up a low-level 297CEC debugger (see the next section). 298 299You will see cases where the CEC transmitter holds the CEC line high or low for 300a longer time than is allowed. For directed messages this is not a problem since 301if that happens the message will not be Acked and it will be retransmitted. 302For broadcast messages no such mechanism exists. 303 304It's not clear what to do about this. It is probably wise to transmit some 305broadcast messages twice to reduce the chance of them being lost. Specifically 306<Standby> and <Active Source> are candidates for that. 307 308 309Making a CEC debugger 310===================== 311 312By using a Raspberry Pi 4B and some cheap components you can make 313your own low-level CEC debugger. 314 315The critical component is one of these HDMI female-female passthrough connectors 316(full soldering type 1): 317 318https://elabbay.myshopify.com/collections/camera/products/hdmi-af-af-v1a-hdmi-type-a-female-to-hdmi-type-a-female-pass-through-adapter-breakout-board?variant=45533926147 319 320The video quality is variable and certainly not enough to pass-through 4kp60 321(594 MHz) video. You might be able to support 4kp30, but more likely you will 322be limited to 1080p60 (148.5 MHz). But for CEC testing that is fine. 323 324You need a breadboard and some breadboard wires: 325 326http://www.dx.com/p/diy-40p-male-to-female-male-to-male-female-to-female-dupont-line-wire-3pcs-356089#.WYLOOXWGN7I 327 328If you want to monitor the HPD and/or 5V lines as well, then you need one of 329these 5V to 3.3V level shifters: 330 331https://www.adafruit.com/product/757 332 333(This is just where I got these components, there are many other places you 334can get similar things). 335 336The ground pin of the HDMI connector needs to be connected to a ground 337pin of the Raspberry Pi, of course. 338 339The CEC pin of the HDMI connector needs to be connected to these pins: 340GPIO 6 and GPIO 7. The optional HPD pin of the HDMI connector should 341be connected via the level shifter to these pins: GPIO 23 and GPIO 12. 342The optional 5V pin of the HDMI connector should be connected via the 343level shifter to these pins: GPIO 25 and GPIO 22. Monitoring the HPD and 3445V lines is not necessary, but it is helpful. 345 346This device tree addition in ``arch/arm/boot/dts/bcm2711-rpi-4-b.dts`` 347will hook up the cec-gpio driver correctly:: 348 349 cec@6 { 350 compatible = "cec-gpio"; 351 cec-gpios = <&gpio 6 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; 352 hpd-gpios = <&gpio 23 GPIO_ACTIVE_HIGH>; 353 v5-gpios = <&gpio 25 GPIO_ACTIVE_HIGH>; 354 }; 355 356 cec@7 { 357 compatible = "cec-gpio"; 358 cec-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; 359 hpd-gpios = <&gpio 12 GPIO_ACTIVE_HIGH>; 360 v5-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; 361 }; 362 363If you haven't hooked up the HPD and/or 5V lines, then just delete those 364lines. 365 366This dts change will enable two cec GPIO devices: I typically use one to 367send/receive CEC commands and the other to monitor. If you monitor using 368an unconfigured CEC adapter then it will use GPIO interrupts which makes 369monitoring very accurate. 370 371If you just want to monitor traffic, then a single instance is sufficient. 372The minimum configuration is one HDMI female-female passthrough connector 373and two female-female breadboard wires: one for connecting the HDMI ground 374pin to a ground pin on the Raspberry Pi, and the other to connect the HDMI 375CEC pin to GPIO 6 on the Raspberry Pi. 376 377The documentation on how to use the error injection is here: :ref:`cec_pin_error_inj`. 378 379``cec-ctl --monitor-pin`` will do low-level CEC bus sniffing and analysis. 380You can also store the CEC traffic to file using ``--store-pin`` and analyze 381it later using ``--analyze-pin``. 382 383You can also use this as a full-fledged CEC device by configuring it 384using ``cec-ctl --tv -p0.0.0.0`` or ``cec-ctl --playback -p1.0.0.0``. 385 386.. _extron_da_hd_4k_plus: 387 388Extron DA HD 4K PLUS CEC Adapter driver 389======================================= 390 391This driver is for the Extron DA HD 4K PLUS series of HDMI Distribution 392Amplifiers: https://www.extron.com/product/dahd4kplusseries 393 394The 2, 4 and 6 port models are supported. 395 396Firmware version 1.02.0001 or higher is required. 397 398Note that older Extron hardware revisions have a problem with the CEC voltage, 399which may mean that CEC will not work. This is fixed in hardware revisions 400E34814 and up. 401 402The CEC support has two modes: the first is a manual mode where userspace has 403to manually control CEC for the HDMI Input and all HDMI Outputs. While this gives 404full control, it is also complicated. 405 406The second mode is an automatic mode, which is selected if the module option 407``vendor_id`` is set. In that case the driver controls CEC and CEC messages 408received in the input will be distributed to the outputs. It is still possible 409to use the /dev/cecX devices to talk to the connected devices directly, but it is 410the driver that configures everything and deals with things like Hotplug Detect 411changes. 412 413The driver also takes care of the EDIDs: /dev/videoX devices are created to 414read the EDIDs and (for the HDMI Input port) to set the EDID. 415 416By default userspace is responsible to set the EDID for the HDMI Input 417according to the EDIDs of the connected displays. But if the ``manufacturer_name`` 418module option is set, then the driver will take care of setting the EDID 419of the HDMI Input based on the supported resolutions of the connected displays. 420Currently the driver only supports resolutions 1080p60 and 4kp60: if all connected 421displays support 4kp60, then it will advertise 4kp60 on the HDMI input, otherwise 422it will fall back to an EDID that just reports 1080p60. 423 424The status of the Extron is reported in ``/sys/kernel/debug/cec/cecX/status``. 425 426The extron-da-hd-4k-plus driver implements the following module options: 427 428``debug`` 429--------- 430 431If set to 1, then all serial port traffic is shown. 432 433``vendor_id`` 434------------- 435 436The CEC Vendor ID to report to connected displays. 437 438If set, then the driver will take care of distributing CEC messages received 439on the input to the HDMI outputs. This is done for the following CEC messages: 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 447If not set, then userspace is responsible for this, and it will have to 448configure the CEC devices for HDMI Input and the HDMI Outputs manually. 449 450``manufacturer_name`` 451--------------------- 452 453A three character manufacturer name that is used in the EDID for the HDMI 454Input. If not set, then userspace is reponsible for configuring an EDID. 455If set, then the driver will update the EDID automatically based on the 456resolutions supported by the connected displays, and it will not be possible 457anymore to manually set the EDID for the HDMI Input. 458 459``hpd_never_low`` 460----------------- 461 462If set, then the Hotplug Detect pin of the HDMI Input will always be high, 463even if nothing is connected to the HDMI Outputs. If not set (the default) 464then the Hotplug Detect pin of the HDMI input will go low if all the detected 465Hotplug Detect pins of the HDMI Outputs are also low. 466 467This option may be changed dynamically. 468