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- RainShadow Tech. Note: this driver does not support the persistent_config 46 module option of the Pulse-Eight driver. The hardware supports it, but I 47 have no plans to add this feature. But I accept patches :-) 48 49Miscellaneous: 50 51- vivid: emulates a CEC receiver and CEC transmitter. 52 Can be used to test CEC applications without actual CEC hardware. 53 54- cec-gpio. If the CEC pin is hooked up to a GPIO pin then 55 you can control the CEC line through this driver. This supports error 56 injection as well. 57 58 59Utilities 60========= 61 62Utilities are available here: https://git.linuxtv.org/v4l-utils.git 63 64``utils/cec-ctl``: control a CEC device 65 66``utils/cec-compliance``: test compliance of a remote CEC device 67 68``utils/cec-follower``: emulate a CEC follower device 69 70Note that ``cec-ctl`` has support for the CEC Hospitality Profile as is 71used in some hotel displays. See http://www.htng.org. 72 73Note that the libcec library (https://github.com/Pulse-Eight/libcec) supports 74the linux CEC framework. 75 76If you want to get the CEC specification, then look at the References of 77the HDMI wikipedia page: https://en.wikipedia.org/wiki/HDMI. CEC is part 78of the HDMI specification. HDMI 1.3 is freely available (very similar to 79HDMI 1.4 w.r.t. CEC) and should be good enough for most things. 80 81 82DisplayPort to HDMI Adapters with working CEC 83============================================= 84 85Background: most adapters do not support the CEC Tunneling feature, 86and of those that do many did not actually connect the CEC pin. 87Unfortunately, this means that while a CEC device is created, it 88is actually all alone in the world and will never be able to see other 89CEC devices. 90 91This is a list of known working adapters that have CEC Tunneling AND 92that properly connected the CEC pin. If you find adapters that work 93but are not in this list, then drop me a note. 94 95To test: hook up your DP-to-HDMI adapter to a CEC capable device 96(typically a TV), then run:: 97 98 cec-ctl --playback # Configure the PC as a CEC Playback device 99 cec-ctl -S # Show the CEC topology 100 101The ``cec-ctl -S`` command should show at least two CEC devices, 102ourselves and the CEC device you are connected to (i.e. typically the TV). 103 104General note: I have only seen this work with the Parade PS175, PS176 and 105PS186 chipsets and the MegaChips 2900. While MegaChips 28x0 claims CEC support, 106I have never seen it work. 107 108USB-C to HDMI 109------------- 110 111Samsung Multiport Adapter EE-PW700: https://www.samsung.com/ie/support/model/EE-PW700BBEGWW/ 112 113Kramer ADC-U31C/HF: https://www.kramerav.com/product/ADC-U31C/HF 114 115Club3D CAC-2504: https://www.club-3d.com/en/detail/2449/usb_3.1_type_c_to_hdmi_2.0_uhd_4k_60hz_active_adapter/ 116 117DisplayPort to HDMI 118------------------- 119 120Club3D CAC-1080: https://www.club-3d.com/en/detail/2442/displayport_1.4_to_hdmi_2.0b_hdr/ 121 122CableCreation (SKU: CD0712): https://www.cablecreation.com/products/active-displayport-to-hdmi-adapter-4k-hdr 123 124HP DisplayPort to HDMI True 4k Adapter (P/N 2JA63AA): https://www.hp.com/us-en/shop/pdp/hp-displayport-to-hdmi-true-4k-adapter 125 126Mini-DisplayPort to HDMI 127------------------------ 128 129Club3D CAC-1180: https://www.club-3d.com/en/detail/2443/mini_displayport_1.4_to_hdmi_2.0b_hdr/ 130 131Note that passive adapters will never work, you need an active adapter. 132 133The Club3D adapters in this list are all MegaChips 2900 based. Other Club3D adapters 134are PS176 based and do NOT have the CEC pin hooked up, so only the three Club3D 135adapters above are known to work. 136 137I suspect that MegaChips 2900 based designs in general are likely to work 138whereas with the PS176 it is more hit-and-miss (mostly miss). The PS186 is 139likely to have the CEC pin hooked up, it looks like they changed the reference 140design for that chipset. 141 142 143USB CEC Dongles 144=============== 145 146These dongles appear as ``/dev/ttyACMX`` devices and need the ``inputattach`` 147utility to create the ``/dev/cecX`` devices. Support for the Pulse-Eight 148has been added to ``inputattach`` 1.6.0. Support for the Rainshadow Tech has 149been added to ``inputattach`` 1.6.1. 150 151You also need udev rules to automatically start systemd services:: 152 153 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1002", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service" 154 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1001", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service" 155 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="ff59", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="rainshadow-cec-inputattach@%k.service" 156 157and these systemd services: 158 159For Pulse-Eight make /lib/systemd/system/pulse8-cec-inputattach@.service:: 160 161 [Unit] 162 Description=inputattach for pulse8-cec device on %I 163 164 [Service] 165 Type=simple 166 ExecStart=/usr/bin/inputattach --pulse8-cec /dev/%I 167 168For the RainShadow Tech make /lib/systemd/system/rainshadow-cec-inputattach@.service:: 169 170 [Unit] 171 Description=inputattach for rainshadow-cec device on %I 172 173 [Service] 174 Type=simple 175 ExecStart=/usr/bin/inputattach --rainshadow-cec /dev/%I 176 177 178For proper suspend/resume support create: /lib/systemd/system/restart-cec-inputattach.service:: 179 180 [Unit] 181 Description=restart inputattach for cec devices 182 After=suspend.target 183 184 [Service] 185 Type=forking 186 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' 187 188 [Install] 189 WantedBy=suspend.target 190 191And run ``systemctl enable restart-cec-inputattach``. 192 193To automatically set the physical address of the CEC device whenever the 194EDID changes, you can use ``cec-ctl`` with the ``-E`` option:: 195 196 cec-ctl -E /sys/class/drm/card0-DP-1/edid 197 198This assumes the dongle is connected to the card0-DP-1 output (``xrandr`` will tell 199you which output is used) and it will poll for changes to the EDID and update 200the Physical Address whenever they occur. 201 202To automatically run this command you can use cron. Edit crontab with 203``crontab -e`` and add this line:: 204 205 @reboot /usr/local/bin/cec-ctl -E /sys/class/drm/card0-DP-1/edid 206 207This only works for display drivers that expose the EDID in ``/sys/class/drm``, 208such as the i915 driver. 209 210 211CEC Without HPD 212=============== 213 214Some displays when in standby mode have no HDMI Hotplug Detect signal, but 215CEC is still enabled so connected devices can send an <Image View On> CEC 216message in order to wake up such displays. Unfortunately, not all CEC 217adapters can support this. An example is the Odroid-U3 SBC that has a 218level-shifter that is powered off when the HPD signal is low, thus 219blocking the CEC pin. Even though the SoC can use CEC without a HPD, 220the level-shifter will prevent this from functioning. 221 222There is a CEC capability flag to signal this: ``CEC_CAP_NEEDS_HPD``. 223If set, then the hardware cannot wake up displays with this behavior. 224 225Note for CEC application implementers: the <Image View On> message must 226be the first message you send, don't send any other messages before. 227Certain very bad but unfortunately not uncommon CEC implementations 228get very confused if they receive anything else but this message and 229they won't wake up. 230 231When writing a driver it can be tricky to test this. There are two 232ways to do this: 233 2341) Get a Pulse-Eight USB CEC dongle, connect an HDMI cable from your 235 device to the Pulse-Eight, but do not connect the Pulse-Eight to 236 the display. 237 238 Now configure the Pulse-Eight dongle:: 239 240 cec-ctl -p0.0.0.0 --tv 241 242 and start monitoring:: 243 244 sudo cec-ctl -M 245 246 On the device you are testing run:: 247 248 cec-ctl --playback 249 250 It should report a physical address of f.f.f.f. Now run this 251 command:: 252 253 cec-ctl -t0 --image-view-on 254 255 The Pulse-Eight should see the <Image View On> message. If not, 256 then something (hardware and/or software) is preventing the CEC 257 message from going out. 258 259 To make sure you have the wiring correct just connect the 260 Pulse-Eight to a CEC-enabled display and run the same command 261 on your device: now there is a HPD, so you should see the command 262 arriving at the Pulse-Eight. 263 2642) If you have another linux device supporting CEC without HPD, then 265 you can just connect your device to that device. Yes, you can connect 266 two HDMI outputs together. You won't have a HPD (which is what we 267 want for this test), but the second device can monitor the CEC pin. 268 269 Otherwise use the same commands as in 1. 270 271If CEC messages do not come through when there is no HPD, then you 272need to figure out why. Typically it is either a hardware restriction 273or the software powers off the CEC core when the HPD goes low. The 274first cannot be corrected of course, the second will likely required 275driver changes. 276 277 278Microcontrollers & CEC 279====================== 280 281We have seen some CEC implementations in displays that use a microcontroller 282to sample the bus. This does not have to be a problem, but some implementations 283have timing issues. This is hard to discover unless you can hook up a low-level 284CEC debugger (see the next section). 285 286You will see cases where the CEC transmitter holds the CEC line high or low for 287a longer time than is allowed. For directed messages this is not a problem since 288if that happens the message will not be Acked and it will be retransmitted. 289For broadcast messages no such mechanism exists. 290 291It's not clear what to do about this. It is probably wise to transmit some 292broadcast messages twice to reduce the chance of them being lost. Specifically 293<Standby> and <Active Source> are candidates for that. 294 295 296Making a CEC debugger 297===================== 298 299By using a Raspberry Pi 2B/3/4 and some cheap components you can make 300your own low-level CEC debugger. 301 302Here is a picture of my setup: 303 304https://hverkuil.home.xs4all.nl/rpi3-cec.jpg 305 306It's a Raspberry Pi 3 together with a breadboard and some breadboard wires: 307 308http://www.dx.com/p/diy-40p-male-to-female-male-to-male-female-to-female-dupont-line-wire-3pcs-356089#.WYLOOXWGN7I 309 310Finally on of these HDMI female-female passthrough connectors (full soldering type 1): 311 312https://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 313 314We've tested this and it works up to 4kp30 (297 MHz). The quality is not high 315enough to pass-through 4kp60 (594 MHz). 316 317I also added an RTC and a breakout shield: 318 319https://www.amazon.com/Makerfire%C2%AE-Raspberry-Module-DS1307-Battery/dp/B00ZOXWHK4 320 321https://www.dx.com/p/raspberry-pi-gpio-expansion-board-breadboard-easy-multiplexing-board-one-to-three-with-screw-for-raspberry-pi-2-3-b-b-2729992.html#.YGRCG0MzZ7I 322 323These two are not needed but they make life a bit easier. 324 325If you want to monitor the HPD line as well, then you need one of these 326level shifters: 327 328https://www.adafruit.com/product/757 329 330(This is just where I got these components, there are many other places you 331can get similar things). 332 333The CEC pin of the HDMI connector needs to be connected to these pins: 334CE0/IO8 and CE1/IO7 (pull-up GPIOs). The (optional) HPD pin of the HDMI 335connector should be connected (via a level shifter to convert the 5V 336to 3.3V) to these pins: IO17 and IO27. The (optional) 5V pin of the HDMI 337connector should be connected (via a level shifter) to these pins: IO22 338and IO24. Monitoring the HPD an 5V lines is not necessary, but it is helpful. 339 340This kernel patch will hook up the cec-gpio driver correctly to 341e.g. ``arch/arm/boot/dts/bcm2837-rpi-3-b-plus.dts``:: 342 343 cec-gpio@7 { 344 compatible = "cec-gpio"; 345 cec-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; 346 hpd-gpios = <&gpio 17 GPIO_ACTIVE_HIGH>; 347 v5-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>; 348 }; 349 350 cec-gpio@8 { 351 compatible = "cec-gpio"; 352 cec-gpios = <&gpio 8 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>; 353 hpd-gpios = <&gpio 27 GPIO_ACTIVE_HIGH>; 354 v5-gpios = <&gpio 24 GPIO_ACTIVE_HIGH>; 355 }; 356 357This dts change will enable two cec GPIO devices: I typically use one to 358send/receive CEC commands and the other to monitor. If you monitor using 359an unconfigured CEC adapter then it will use GPIO interrupts which makes 360monitoring very accurate. 361 362The documentation on how to use the error injection is here: :ref:`cec_pin_error_inj`. 363 364``cec-ctl --monitor-pin`` will do low-level CEC bus sniffing and analysis. 365You can also store the CEC traffic to file using ``--store-pin`` and analyze 366it later using ``--analyze-pin``. 367 368You can also use this as a full-fledged CEC device by configuring it 369using ``cec-ctl --tv -p0.0.0.0`` or ``cec-ctl --playback -p1.0.0.0``. 370
