xref: /linux/Documentation/userspace-api/media/cec/cec-intro.rst (revision 95298d63c67673c654c08952672d016212b26054) 
1.. Permission is granted to copy, distribute and/or modify this
2.. document under the terms of the GNU Free Documentation License,
3.. Version 1.1 or any later version published by the Free Software
4.. Foundation, with no Invariant Sections, no Front-Cover Texts
5.. and no Back-Cover Texts. A copy of the license is included at
6.. Documentation/userspace-api/media/fdl-appendix.rst.
7..
8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10.. _cec-intro:
11
12Introduction
13============
14
15HDMI connectors provide a single pin for use by the Consumer Electronics
16Control protocol. This protocol allows different devices connected by an
17HDMI cable to communicate. The protocol for CEC version 1.4 is defined
18in supplements 1 (CEC) and 2 (HEAC or HDMI Ethernet and Audio Return
19Channel) of the HDMI 1.4a (:ref:`hdmi`) specification and the
20extensions added to CEC version 2.0 are defined in chapter 11 of the
21HDMI 2.0 (:ref:`hdmi2`) specification.
22
23The bitrate is very slow (effectively no more than 36 bytes per second)
24and is based on the ancient AV.link protocol used in old SCART
25connectors. The protocol closely resembles a crazy Rube Goldberg
26contraption and is an unholy mix of low and high level messages. Some
27messages, especially those part of the HEAC protocol layered on top of
28CEC, need to be handled by the kernel, others can be handled either by
29the kernel or by userspace.
30
31In addition, CEC can be implemented in HDMI receivers, transmitters and
32in USB devices that have an HDMI input and an HDMI output and that
33control just the CEC pin.
34
35Drivers that support CEC will create a CEC device node (/dev/cecX) to
36give userspace access to the CEC adapter. The
37:ref:`CEC_ADAP_G_CAPS` ioctl will tell userspace what it is allowed to do.
38
39In order to check the support and test it, it is suggested to download
40the `v4l-utils <https://git.linuxtv.org/v4l-utils.git/>`_ package. It
41provides three tools to handle CEC:
42
43- cec-ctl: the Swiss army knife of CEC. Allows you to configure, transmit
44  and monitor CEC messages.
45
46- cec-compliance: does a CEC compliance test of a remote CEC device to
47  determine how compliant the CEC implementation is.
48
49- cec-follower: emulates a CEC follower.
50