1 .. SPDX-License-Identifier: GPL-2.0
7 Supported hardware in mainline
8 ==============================
15 - V4L2 adv7511 (same HW, but a different driver from the drm adv7511)
17 - Allwinner A10 (sun4i)
19 - dw-hdmi (Synopsis IP)
20 - amlogic (meson ao-cec and ao-cec-g12a)
26 - DisplayPort CEC-Tunneling-over-AUX on i915, nouveau and amdgpu
28 - CEC for SECO boards (UDOO x86).
38 USB Dongles (see below for additional information on how to use these
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 :-)
51 - vivid: emulates a CEC receiver and CEC transmitter.
52 Can be used to test CEC applications without actual CEC hardware.
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
58 - cec-gpio and Allwinner A10 (or any other driver that uses the CEC pin
59 framework to drive the CEC pin directly): the CEC pin framework uses
60 high-resolution timers. These timers are affected by NTP daemons that
61 speed up or slow down the clock to sync with the official time. The
62 chronyd server will by default increase or decrease the clock by
63 1/12th. This will cause the CEC timings to go out of spec. To fix this,
64 add a 'maxslewrate 40000' line to chronyd.conf. This limits the clock
65 frequency change to 1/25th, which keeps the CEC timings within spec.
71 Utilities are available here: https://git.linuxtv.org/v4l-utils.git
73 ``utils/cec-ctl``: control a CEC device
75 ``utils/cec-compliance``: test compliance of a remote CEC device
77 ``utils/cec-follower``: emulate a CEC follower device
79 Note that ``cec-ctl`` has support for the CEC Hospitality Profile as is
80 used in some hotel displays. See http://www.htng.org.
82 Note that the libcec library (https://github.com/Pulse-Eight/libcec) supports
83 the linux CEC framework.
85 If you want to get the CEC specification, then look at the References of
86 the HDMI wikipedia page: https://en.wikipedia.org/wiki/HDMI. CEC is part
87 of the HDMI specification. HDMI 1.3 is freely available (very similar to
88 HDMI 1.4 w.r.t. CEC) and should be good enough for most things.
91 DisplayPort to HDMI Adapters with working CEC
92 =============================================
94 Background: most adapters do not support the CEC Tunneling feature,
95 and of those that do many did not actually connect the CEC pin.
96 Unfortunately, this means that while a CEC device is created, it
97 is actually all alone in the world and will never be able to see other
100 This is a list of known working adapters that have CEC Tunneling AND
101 that properly connected the CEC pin. If you find adapters that work
102 but are not in this list, then drop me a note.
104 To test: hook up your DP-to-HDMI adapter to a CEC capable device
105 (typically a TV), then run::
107 cec-ctl --playback # Configure the PC as a CEC Playback device
108 cec-ctl -S # Show the CEC topology
110 The ``cec-ctl -S`` command should show at least two CEC devices,
111 ourselves and the CEC device you are connected to (i.e. typically the TV).
113 General note: I have only seen this work with the Parade PS175, PS176 and
114 PS186 chipsets and the MegaChips 2900. While MegaChips 28x0 claims CEC support,
115 I have never seen it work.
120 Samsung Multiport Adapter EE-PW700: https://www.samsung.com/ie/support/model/EE-PW700BBEGWW/
122 Kramer ADC-U31C/HF: https://www.kramerav.com/product/ADC-U31C/HF
124 Club3D 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 Club3D CAC-1080: https://www.club-3d.com/en/detail/2442/displayport_1.4_to_hdmi_2.0b_hdr/
131 CableCreation (SKU: CD0712): https://www.cablecreation.com/products/active-displayport-to-hdmi-adapter-4k-hdr
133 HP DisplayPort to HDMI True 4k Adapter (P/N 2JA63AA): https://www.hp.com/us-en/shop/pdp/hp-displayport-to-hdmi-true-4k-adapter
135 Mini-DisplayPort to HDMI
136 ------------------------
138 Club3D CAC-1180: https://www.club-3d.com/en/detail/2443/mini_displayport_1.4_to_hdmi_2.0b_hdr/
140 Note that passive adapters will never work, you need an active adapter.
142 The Club3D adapters in this list are all MegaChips 2900 based. Other Club3D adapters
143 are PS176 based and do NOT have the CEC pin hooked up, so only the three Club3D
144 adapters above are known to work.
146 I suspect that MegaChips 2900 based designs in general are likely to work
147 whereas with the PS176 it is more hit-and-miss (mostly miss). The PS186 is
148 likely to have the CEC pin hooked up, it looks like they changed the reference
149 design for that chipset.
155 These dongles appear as ``/dev/ttyACMX`` devices and need the ``inputattach``
156 utility to create the ``/dev/cecX`` devices. Support for the Pulse-Eight
157 has been added to ``inputattach`` 1.6.0. Support for the Rainshadow Tech has
158 been added to ``inputattach`` 1.6.1.
160 You also need udev rules to automatically start systemd services::
162 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1002", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service"
163 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="2548", ATTRS{idProduct}=="1001", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="pulse8-cec-inputattach@%k.service"
164 SUBSYSTEM=="tty", KERNEL=="ttyACM[0-9]*", ATTRS{idVendor}=="04d8", ATTRS{idProduct}=="ff59", ACTION=="add", TAG+="systemd", ENV{SYSTEMD_WANTS}+="rainshadow-cec-inputattach@%k.service"
166 and these systemd services:
168 For Pulse-Eight make /lib/systemd/system/pulse8-cec-inputattach@.service::
171 Description=inputattach for pulse8-cec device on %I
175 ExecStart=/usr/bin/inputattach --pulse8-cec /dev/%I
177 For the RainShadow Tech make /lib/systemd/system/rainshadow-cec-inputattach@.service::
180 Description=inputattach for rainshadow-cec device on %I
184 ExecStart=/usr/bin/inputattach --rainshadow-cec /dev/%I
187 For proper suspend/resume support create: /lib/systemd/system/restart-cec-inputattach.service::
190 Description=restart inputattach for cec devices
195 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'
198 WantedBy=suspend.target
200 And run ``systemctl enable restart-cec-inputattach``.
202 To automatically set the physical address of the CEC device whenever the
203 EDID changes, you can use ``cec-ctl`` with the ``-E`` option::
205 cec-ctl -E /sys/class/drm/card0-DP-1/edid
207 This assumes the dongle is connected to the card0-DP-1 output (``xrandr`` will tell
208 you which output is used) and it will poll for changes to the EDID and update
209 the Physical Address whenever they occur.
211 To automatically run this command you can use cron. Edit crontab with
212 ``crontab -e`` and add this line::
214 @reboot /usr/local/bin/cec-ctl -E /sys/class/drm/card0-DP-1/edid
216 This only works for display drivers that expose the EDID in ``/sys/class/drm``,
217 such as the i915 driver.
223 Some displays when in standby mode have no HDMI Hotplug Detect signal, but
224 CEC is still enabled so connected devices can send an <Image View On> CEC
225 message in order to wake up such displays. Unfortunately, not all CEC
226 adapters can support this. An example is the Odroid-U3 SBC that has a
227 level-shifter that is powered off when the HPD signal is low, thus
228 blocking the CEC pin. Even though the SoC can use CEC without a HPD,
229 the level-shifter will prevent this from functioning.
231 There is a CEC capability flag to signal this: ``CEC_CAP_NEEDS_HPD``.
232 If set, then the hardware cannot wake up displays with this behavior.
234 Note for CEC application implementers: the <Image View On> message must
235 be the first message you send, don't send any other messages before.
236 Certain very bad but unfortunately not uncommon CEC implementations
237 get very confused if they receive anything else but this message and
240 When writing a driver it can be tricky to test this. There are two
243 1) Get a Pulse-Eight USB CEC dongle, connect an HDMI cable from your
244 device to the Pulse-Eight, but do not connect the Pulse-Eight to
247 Now configure the Pulse-Eight dongle::
249 cec-ctl -p0.0.0.0 --tv
251 and start monitoring::
255 On the device you are testing run::
259 It should report a physical address of f.f.f.f. Now run this
262 cec-ctl -t0 --image-view-on
264 The Pulse-Eight should see the <Image View On> message. If not,
265 then something (hardware and/or software) is preventing the CEC
266 message from going out.
268 To make sure you have the wiring correct just connect the
269 Pulse-Eight to a CEC-enabled display and run the same command
270 on your device: now there is a HPD, so you should see the command
271 arriving at the Pulse-Eight.
273 2) If you have another linux device supporting CEC without HPD, then
274 you can just connect your device to that device. Yes, you can connect
275 two HDMI outputs together. You won't have a HPD (which is what we
276 want for this test), but the second device can monitor the CEC pin.
278 Otherwise use the same commands as in 1.
280 If CEC messages do not come through when there is no HPD, then you
281 need to figure out why. Typically it is either a hardware restriction
282 or the software powers off the CEC core when the HPD goes low. The
283 first cannot be corrected of course, the second will likely required
287 Microcontrollers & CEC
288 ======================
290 We have seen some CEC implementations in displays that use a microcontroller
291 to sample the bus. This does not have to be a problem, but some implementations
292 have timing issues. This is hard to discover unless you can hook up a low-level
293 CEC debugger (see the next section).
295 You will see cases where the CEC transmitter holds the CEC line high or low for
296 a longer time than is allowed. For directed messages this is not a problem since
297 if that happens the message will not be Acked and it will be retransmitted.
298 For broadcast messages no such mechanism exists.
300 It's not clear what to do about this. It is probably wise to transmit some
301 broadcast messages twice to reduce the chance of them being lost. Specifically
302 <Standby> and <Active Source> are candidates for that.
305 Making a CEC debugger
306 =====================
308 By using a Raspberry Pi 4B and some cheap components you can make
309 your own low-level CEC debugger.
311 The critical component is one of these HDMI female-female passthrough connectors
312 (full soldering type 1):
314 https://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
316 The video quality is variable and certainly not enough to pass-through 4kp60
317 (594 MHz) video. You might be able to support 4kp30, but more likely you will
318 be limited to 1080p60 (148.5 MHz). But for CEC testing that is fine.
320 You need a breadboard and some breadboard wires:
322 http://www.dx.com/p/diy-40p-male-to-female-male-to-male-female-to-female-dupont-line-wire-3pcs-356089#.WYLOOXWGN7I
324 If you want to monitor the HPD and/or 5V lines as well, then you need one of
325 these 5V to 3.3V level shifters:
327 https://www.adafruit.com/product/757
329 (This is just where I got these components, there are many other places you
330 can get similar things).
332 The ground pin of the HDMI connector needs to be connected to a ground
333 pin of the Raspberry Pi, of course.
335 The CEC pin of the HDMI connector needs to be connected to these pins:
336 GPIO 6 and GPIO 7. The optional HPD pin of the HDMI connector should
337 be connected via the level shifter to these pins: GPIO 23 and GPIO 12.
338 The optional 5V pin of the HDMI connector should be connected via the
339 level shifter to these pins: GPIO 25 and GPIO 22. Monitoring the HPD and
340 5V lines is not necessary, but it is helpful.
342 This device tree addition in ``arch/arm/boot/dts/bcm2711-rpi-4-b.dts``
343 will hook up the cec-gpio driver correctly::
346 compatible = "cec-gpio";
347 cec-gpios = <&gpio 6 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
348 hpd-gpios = <&gpio 23 GPIO_ACTIVE_HIGH>;
349 v5-gpios = <&gpio 25 GPIO_ACTIVE_HIGH>;
353 compatible = "cec-gpio";
354 cec-gpios = <&gpio 7 (GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN)>;
355 hpd-gpios = <&gpio 12 GPIO_ACTIVE_HIGH>;
356 v5-gpios = <&gpio 22 GPIO_ACTIVE_HIGH>;
359 If you haven't hooked up the HPD and/or 5V lines, then just delete those
362 This dts change will enable two cec GPIO devices: I typically use one to
363 send/receive CEC commands and the other to monitor. If you monitor using
364 an unconfigured CEC adapter then it will use GPIO interrupts which makes
365 monitoring very accurate.
367 If you just want to monitor traffic, then a single instance is sufficient.
368 The minimum configuration is one HDMI female-female passthrough connector
369 and two female-female breadboard wires: one for connecting the HDMI ground
370 pin to a ground pin on the Raspberry Pi, and the other to connect the HDMI
371 CEC pin to GPIO 6 on the Raspberry Pi.
373 The documentation on how to use the error injection is here: :ref:`cec_pin_error_inj`.
375 ``cec-ctl --monitor-pin`` will do low-level CEC bus sniffing and analysis.
376 You can also store the CEC traffic to file using ``--store-pin`` and analyze
377 it later using ``--analyze-pin``.
379 You can also use this as a full-fledged CEC device by configuring it
380 using ``cec-ctl --tv -p0.0.0.0`` or ``cec-ctl --playback -p1.0.0.0``.