aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2016-07-26 21:59:59 -0400
committerLinus Torvalds <torvalds@linux-foundation.org>2016-07-26 21:59:59 -0400
commit9c1958fc326a0a0a533ec8e86ea6fa30977207de (patch)
tree9d76e6a146c2622fad0eefbb8ff0503caefe33cc /Documentation
parent1b3fc0bef8859268d542230172f80e85553fdab4 (diff)
parent009a620848218d521f008141c62f56bf19294dd9 (diff)
Merge tag 'media/v4.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab: - new framework support for HDMI CEC and remote control support - new encoding codec driver for Mediatek SoC - new frontend driver: helene tuner - added support for NetUp almost universal devices, with supports DVB-C/S/S2/T/T2 and ISDB-T - the mn88472 frontend driver got promoted from staging - a new driver for RCar video input - some soc_camera legacy drivers got removed: timb, omap1, mx2, mx3 - lots of driver cleanups, improvements and fixups * tag 'media/v4.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (377 commits) [media] cec: always check all_device_types and features [media] cec: poll should check if there is room in the tx queue [media] vivid: support monitor all mode [media] cec: fix test for unconfigured adapter in main message loop [media] cec: limit the size of the transmit queue [media] cec: zero unused msg part after msg->len [media] cec: don't set fh to NULL in CEC_TRANSMIT [media] cec: clear all status fields before transmit and always fill in sequence [media] cec: CEC_RECEIVE overwrote the timeout field [media] cxd2841er: Reading SNR for DVB-C added [media] cxd2841er: Reading BER and UCB for DVB-C added [media] cxd2841er: fix switch-case for DVB-C [media] cxd2841er: fix signal strength scale for ISDB-T [media] cxd2841er: adjust the dB scale for DVB-C [media] cxd2841er: provide signal strength for DVB-C [media] cxd2841er: fix BER report via DVBv5 stats API [media] mb86a20s: apply mask to val after checking for read failure [media] airspy: fix error logic during device register [media] s5p-cec/TODO: add TODO item [media] cec/TODO: drop comment about sphinx documentation ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/device-drivers.tmpl3
-rw-r--r--Documentation/DocBook/media/Makefile2
-rw-r--r--Documentation/DocBook/media/v4l/biblio.xml10
-rw-r--r--Documentation/DocBook/media/v4l/cec-api.xml75
-rw-r--r--Documentation/DocBook/media/v4l/cec-func-close.xml64
-rw-r--r--Documentation/DocBook/media/v4l/cec-func-ioctl.xml78
-rw-r--r--Documentation/DocBook/media/v4l/cec-func-open.xml104
-rw-r--r--Documentation/DocBook/media/v4l/cec-func-poll.xml94
-rw-r--r--Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml151
-rw-r--r--Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml329
-rw-r--r--Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml86
-rw-r--r--Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml202
-rw-r--r--Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml255
-rw-r--r--Documentation/DocBook/media/v4l/cec-ioc-receive.xml274
-rw-r--r--Documentation/DocBook/media/v4l/io.xml4
-rw-r--r--Documentation/DocBook/media/v4l/lirc_device_interface.xml2
-rw-r--r--Documentation/DocBook/media/v4l/media-types.xml64
-rw-r--r--Documentation/DocBook/media/v4l/pixfmt-z16.xml2
-rw-r--r--Documentation/DocBook/media/v4l/vidioc-reqbufs.xml2
-rw-r--r--Documentation/DocBook/media_api.tmpl6
-rw-r--r--Documentation/cec.txt267
-rw-r--r--Documentation/devicetree/bindings/media/mediatek-vcodec.txt59
-rw-r--r--Documentation/devicetree/bindings/media/mediatek-vpu.txt31
-rw-r--r--Documentation/devicetree/bindings/media/renesas,fcp.txt32
-rw-r--r--Documentation/devicetree/bindings/media/renesas,vsp1.txt5
-rw-r--r--Documentation/devicetree/bindings/media/s5p-cec.txt31
-rw-r--r--Documentation/devicetree/bindings/media/s5p-mfc.txt39
-rw-r--r--Documentation/video4linux/CARDLIST.cx238851
-rw-r--r--Documentation/video4linux/v4l2-controls.txt15
-rw-r--r--Documentation/video4linux/vivid.txt36
30 files changed, 2289 insertions, 34 deletions
diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index 8c68768ebee5..58af32b01b90 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -300,6 +300,9 @@ X!Isound/sound_firmware.c
300!Iinclude/media/media-devnode.h 300!Iinclude/media/media-devnode.h
301!Iinclude/media/media-entity.h 301!Iinclude/media/media-entity.h
302 </sect1> 302 </sect1>
303 <sect1><title>Consumer Electronics Control devices</title>
304!Iinclude/media/cec-edid.h
305 </sect1>
303 306
304 </chapter> 307 </chapter>
305 308
diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile
index 2840ff483d5a..fdc138624800 100644
--- a/Documentation/DocBook/media/Makefile
+++ b/Documentation/DocBook/media/Makefile
@@ -64,6 +64,7 @@ IOCTLS = \
64 $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/net.h) \ 64 $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/net.h) \
65 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/video.h) \ 65 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/video.h) \
66 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/media.h) \ 66 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/media.h) \
67 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/cec.h) \
67 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ 68 $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \
68 69
69DEFINES = \ 70DEFINES = \
@@ -100,6 +101,7 @@ STRUCTS = \
100 $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/ && !/_old/)' $(srctree)/include/uapi/linux/dvb/net.h) \ 101 $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/ && !/_old/)' $(srctree)/include/uapi/linux/dvb/net.h) \
101 $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \ 102 $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \
102 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ 103 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \
104 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/cec.h) \
103 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ 105 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \
104 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) 106 $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h)
105 107
diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml
index 9beb30f0071b..87f1d24958aa 100644
--- a/Documentation/DocBook/media/v4l/biblio.xml
+++ b/Documentation/DocBook/media/v4l/biblio.xml
@@ -342,6 +342,16 @@ in the frequency range from 87,5 to 108,0 MHz</title>
342 <subtitle>Specification Version 1.4a</subtitle> 342 <subtitle>Specification Version 1.4a</subtitle>
343 </biblioentry> 343 </biblioentry>
344 344
345 <biblioentry id="hdmi2">
346 <abbrev>HDMI2</abbrev>
347 <authorgroup>
348 <corpauthor>HDMI Licensing LLC
349(<ulink url="http://www.hdmi.org">http://www.hdmi.org</ulink>)</corpauthor>
350 </authorgroup>
351 <title>High-Definition Multimedia Interface</title>
352 <subtitle>Specification Version 2.0</subtitle>
353 </biblioentry>
354
345 <biblioentry id="dp"> 355 <biblioentry id="dp">
346 <abbrev>DP</abbrev> 356 <abbrev>DP</abbrev>
347 <authorgroup> 357 <authorgroup>
diff --git a/Documentation/DocBook/media/v4l/cec-api.xml b/Documentation/DocBook/media/v4l/cec-api.xml
new file mode 100644
index 000000000000..7062c1fa4904
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-api.xml
@@ -0,0 +1,75 @@
1<partinfo>
2 <authorgroup>
3 <author>
4 <firstname>Hans</firstname>
5 <surname>Verkuil</surname>
6 <affiliation><address><email>hans.verkuil@cisco.com</email></address></affiliation>
7 <contrib>Initial version.</contrib>
8 </author>
9 </authorgroup>
10 <copyright>
11 <year>2016</year>
12 <holder>Hans Verkuil</holder>
13 </copyright>
14
15 <revhistory>
16 <!-- Put document revisions here, newest first. -->
17 <revision>
18 <revnumber>1.0.0</revnumber>
19 <date>2016-03-17</date>
20 <authorinitials>hv</authorinitials>
21 <revremark>Initial revision</revremark>
22 </revision>
23 </revhistory>
24</partinfo>
25
26<title>CEC API</title>
27
28<chapter id="cec-api">
29 <title>CEC: Consumer Electronics Control</title>
30
31 <section id="cec-intro">
32 <title>Introduction</title>
33 <para>
34 Note: this documents the proposed CEC API. This API is not yet finalized and
35 is currently only available as a staging kernel module.
36 </para>
37 <para>HDMI connectors provide a single pin for use by the Consumer Electronics
38 Control protocol. This protocol allows different devices connected by an HDMI cable
39 to communicate. The protocol for CEC version 1.4 is defined in supplements 1 (CEC)
40 and 2 (HEAC or HDMI Ethernet and Audio Return Channel) of the HDMI 1.4a
41 (<xref linkend="hdmi" />) specification and the extensions added to CEC version 2.0
42 are defined in chapter 11 of the HDMI 2.0 (<xref linkend="hdmi2" />) specification.
43 </para>
44
45 <para>The bitrate is very slow (effectively no more than 36 bytes per second) and
46 is based on the ancient AV.link protocol used in old SCART connectors. The protocol
47 closely resembles a crazy Rube Goldberg contraption and is an unholy mix of low and
48 high level messages. Some messages, especially those part of the HEAC protocol layered
49 on top of CEC, need to be handled by the kernel, others can be handled either by the
50 kernel or by userspace.</para>
51
52 <para>In addition, CEC can be implemented in HDMI receivers, transmitters and in USB
53 devices that have an HDMI input and an HDMI output and that control just the CEC pin.</para>
54
55 <para>Drivers that support CEC will create a CEC device node (/dev/cecX)
56 to give userspace access to the CEC adapter. The &CEC-ADAP-G-CAPS; ioctl will tell userspace
57 what it is allowed to do.</para>
58 </section>
59</chapter>
60
61<appendix id="cec-user-func">
62 <title>Function Reference</title>
63 <!-- Keep this alphabetically sorted. -->
64 &sub-cec-func-open;
65 &sub-cec-func-close;
66 &sub-cec-func-ioctl;
67 &sub-cec-func-poll;
68 <!-- All ioctls go here. -->
69 &sub-cec-ioc-adap-g-caps;
70 &sub-cec-ioc-adap-g-log-addrs;
71 &sub-cec-ioc-adap-g-phys-addr;
72 &sub-cec-ioc-dqevent;
73 &sub-cec-ioc-g-mode;
74 &sub-cec-ioc-receive;
75</appendix>
diff --git a/Documentation/DocBook/media/v4l/cec-func-close.xml b/Documentation/DocBook/media/v4l/cec-func-close.xml
new file mode 100644
index 000000000000..0812c8cd9634
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-func-close.xml
@@ -0,0 +1,64 @@
1<refentry id="cec-func-close">
2 <refmeta>
3 <refentrytitle>cec close()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>cec-close</refname>
9 <refpurpose>Close a cec device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;unistd.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>close</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 </funcprototype>
19 </funcsynopsis>
20 </refsynopsisdiv>
21
22 <refsect1>
23 <title>Arguments</title>
24
25 <variablelist>
26 <varlistentry>
27 <term><parameter>fd</parameter></term>
28 <listitem>
29 <para>&fd;</para>
30 </listitem>
31 </varlistentry>
32 </variablelist>
33 </refsect1>
34
35 <refsect1>
36 <title>Description</title>
37
38 <para>
39 Note: this documents the proposed CEC API. This API is not yet finalized and
40 is currently only available as a staging kernel module.
41 </para>
42
43 <para>Closes the cec device. Resources associated with the file descriptor
44 are freed. The device configuration remain unchanged.</para>
45 </refsect1>
46
47 <refsect1>
48 <title>Return Value</title>
49
50 <para><function>close</function> returns 0 on success. On error, -1 is
51 returned, and <varname>errno</varname> is set appropriately. Possible error
52 codes are:</para>
53
54 <variablelist>
55 <varlistentry>
56 <term><errorcode>EBADF</errorcode></term>
57 <listitem>
58 <para><parameter>fd</parameter> is not a valid open file descriptor.
59 </para>
60 </listitem>
61 </varlistentry>
62 </variablelist>
63 </refsect1>
64</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-func-ioctl.xml b/Documentation/DocBook/media/v4l/cec-func-ioctl.xml
new file mode 100644
index 000000000000..f92817a2dc80
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-func-ioctl.xml
@@ -0,0 +1,78 @@
1<refentry id="cec-func-ioctl">
2 <refmeta>
3 <refentrytitle>cec ioctl()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>cec-ioctl</refname>
9 <refpurpose>Control a cec device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;sys/ioctl.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>void *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>&fd;</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>CEC ioctl request code as defined in the cec.h header file,
38 for example CEC_ADAP_G_CAPS.</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para>Pointer to a request-specific structure.</para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52 <para>
53 Note: this documents the proposed CEC API. This API is not yet finalized and
54 is currently only available as a staging kernel module.
55 </para>
56
57 <para>The <function>ioctl()</function> function manipulates cec device
58 parameters. The argument <parameter>fd</parameter> must be an open file
59 descriptor.</para>
60 <para>The ioctl <parameter>request</parameter> code specifies the cec
61 function to be called. It has encoded in it whether the argument is an
62 input, output or read/write parameter, and the size of the argument
63 <parameter>argp</parameter> in bytes.</para>
64 <para>Macros and structures definitions specifying cec ioctl requests and
65 their parameters are located in the cec.h header file. All cec ioctl
66 requests, their respective function and parameters are specified in
67 <xref linkend="cec-user-func" />.</para>
68 </refsect1>
69
70 <refsect1>
71 &return-value;
72
73 <para>Request-specific error codes are listed in the
74 individual requests descriptions.</para>
75 <para>When an ioctl that takes an output or read/write parameter fails,
76 the parameter remains unmodified.</para>
77 </refsect1>
78</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-func-open.xml b/Documentation/DocBook/media/v4l/cec-func-open.xml
new file mode 100644
index 000000000000..2edc5555b81a
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-func-open.xml
@@ -0,0 +1,104 @@
1<refentry id="cec-func-open">
2 <refmeta>
3 <refentrytitle>cec open()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>cec-open</refname>
9 <refpurpose>Open a cec device</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;fcntl.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>open</function></funcdef>
17 <paramdef>const char *<parameter>device_name</parameter></paramdef>
18 <paramdef>int <parameter>flags</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>device_name</parameter></term>
29 <listitem>
30 <para>Device to be opened.</para>
31 </listitem>
32 </varlistentry>
33 <varlistentry>
34 <term><parameter>flags</parameter></term>
35 <listitem>
36 <para>Open flags. Access mode must be <constant>O_RDWR</constant>.
37 </para>
38 <para>When the <constant>O_NONBLOCK</constant> flag is
39given, the &CEC-RECEIVE; ioctl will return &EAGAIN; when no message is
40available, and the &CEC-TRANSMIT;, &CEC-ADAP-S-PHYS-ADDR; and
41&CEC-ADAP-S-LOG-ADDRS; ioctls all act in non-blocking mode.</para>
42 <para>Other flags have no effect.</para>
43 </listitem>
44 </varlistentry>
45 </variablelist>
46 </refsect1>
47 <refsect1>
48 <title>Description</title>
49 <para>
50 Note: this documents the proposed CEC API. This API is not yet finalized and
51 is currently only available as a staging kernel module.
52 </para>
53
54 <para>To open a cec device applications call <function>open()</function>
55 with the desired device name. The function has no side effects; the device
56 configuration remain unchanged.</para>
57 <para>When the device is opened in read-only mode, attempts to modify its
58 configuration will result in an error, and <varname>errno</varname> will be
59 set to <errorcode>EBADF</errorcode>.</para>
60 </refsect1>
61 <refsect1>
62 <title>Return Value</title>
63
64 <para><function>open</function> returns the new file descriptor on success.
65 On error, -1 is returned, and <varname>errno</varname> is set appropriately.
66 Possible error codes include:</para>
67
68 <variablelist>
69 <varlistentry>
70 <term><errorcode>EACCES</errorcode></term>
71 <listitem>
72 <para>The requested access to the file is not allowed.</para>
73 </listitem>
74 </varlistentry>
75 <varlistentry>
76 <term><errorcode>EMFILE</errorcode></term>
77 <listitem>
78 <para>The process already has the maximum number of files open.
79 </para>
80 </listitem>
81 </varlistentry>
82 <varlistentry>
83 <term><errorcode>ENFILE</errorcode></term>
84 <listitem>
85 <para>The system limit on the total number of open files has been
86 reached.</para>
87 </listitem>
88 </varlistentry>
89 <varlistentry>
90 <term><errorcode>ENOMEM</errorcode></term>
91 <listitem>
92 <para>Insufficient kernel memory was available.</para>
93 </listitem>
94 </varlistentry>
95 <varlistentry>
96 <term><errorcode>ENXIO</errorcode></term>
97 <listitem>
98 <para>No device corresponding to this device special file exists.
99 </para>
100 </listitem>
101 </varlistentry>
102 </variablelist>
103 </refsect1>
104</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-func-poll.xml b/Documentation/DocBook/media/v4l/cec-func-poll.xml
new file mode 100644
index 000000000000..1bddbde0142d
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-func-poll.xml
@@ -0,0 +1,94 @@
1<refentry id="cec-func-poll">
2 <refmeta>
3 <refentrytitle>cec poll()</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>cec-poll</refname>
9 <refpurpose>Wait for some event on a file descriptor</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcsynopsisinfo>#include &lt;sys/poll.h&gt;</funcsynopsisinfo>
15 <funcprototype>
16 <funcdef>int <function>poll</function></funcdef>
17 <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef>
18 <paramdef>unsigned int <parameter>nfds</parameter></paramdef>
19 <paramdef>int <parameter>timeout</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Description</title>
26
27 <para>
28 Note: this documents the proposed CEC API. This API is not yet finalized and
29 is currently only available as a staging kernel module.
30 </para>
31
32 <para>With the <function>poll()</function> function applications
33can wait for CEC events.</para>
34
35 <para>On success <function>poll()</function> returns the number of
36file descriptors that have been selected (that is, file descriptors
37for which the <structfield>revents</structfield> field of the
38respective <structname>pollfd</structname> structure is non-zero).
39CEC devices set the <constant>POLLIN</constant> and
40<constant>POLLRDNORM</constant> flags in the
41<structfield>revents</structfield> field if there are messages in the
42receive queue. If the transmit queue has room for new messages, the
43<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant>
44flags are set. If there are events in the event queue, then the
45<constant>POLLPRI</constant> flag is set.
46When the function timed out it returns a value of zero, on
47failure it returns <returnvalue>-1</returnvalue> and the
48<varname>errno</varname> variable is set appropriately.
49</para>
50
51 <para>For more details see the
52<function>poll()</function> manual page.</para>
53 </refsect1>
54
55 <refsect1>
56 <title>Return Value</title>
57
58 <para>On success, <function>poll()</function> returns the number
59structures which have non-zero <structfield>revents</structfield>
60fields, or zero if the call timed out. On error
61<returnvalue>-1</returnvalue> is returned, and the
62<varname>errno</varname> variable is set appropriately:</para>
63
64 <variablelist>
65 <varlistentry>
66 <term><errorcode>EBADF</errorcode></term>
67 <listitem>
68 <para>One or more of the <parameter>ufds</parameter> members
69specify an invalid file descriptor.</para>
70 </listitem>
71 </varlistentry>
72 <varlistentry>
73 <term><errorcode>EFAULT</errorcode></term>
74 <listitem>
75 <para><parameter>ufds</parameter> references an inaccessible
76memory area.</para>
77 </listitem>
78 </varlistentry>
79 <varlistentry>
80 <term><errorcode>EINTR</errorcode></term>
81 <listitem>
82 <para>The call was interrupted by a signal.</para>
83 </listitem>
84 </varlistentry>
85 <varlistentry>
86 <term><errorcode>EINVAL</errorcode></term>
87 <listitem>
88 <para>The <parameter>nfds</parameter> argument is greater
89than <constant>OPEN_MAX</constant>.</para>
90 </listitem>
91 </varlistentry>
92 </variablelist>
93 </refsect1>
94</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml
new file mode 100644
index 000000000000..3523ef2259b1
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml
@@ -0,0 +1,151 @@
1<refentry id="cec-ioc-adap-g-caps">
2 <refmeta>
3 <refentrytitle>ioctl CEC_ADAP_G_CAPS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>CEC_ADAP_G_CAPS</refname>
9 <refpurpose>Query device capabilities</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct cec_caps *<parameter>argp</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>fd</parameter></term>
29 <listitem>
30 <para>File descriptor returned by
31 <link linkend='cec-func-open'><function>open()</function></link>.</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>CEC_ADAP_G_CAPS</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <para>
53 Note: this documents the proposed CEC API. This API is not yet finalized and
54 is currently only available as a staging kernel module.
55 </para>
56
57 <para>All cec devices must support the <constant>CEC_ADAP_G_CAPS</constant>
58 ioctl. To query device information, applications call the ioctl with a
59 pointer to a &cec-caps;. The driver fills the structure and returns
60 the information to the application.
61 The ioctl never fails.</para>
62
63 <table pgwide="1" frame="none" id="cec-caps">
64 <title>struct <structname>cec_caps</structname></title>
65 <tgroup cols="3">
66 &cs-str;
67 <tbody valign="top">
68 <row>
69 <entry>char</entry>
70 <entry><structfield>driver[32]</structfield></entry>
71 <entry>The name of the cec adapter driver.</entry>
72 </row>
73 <row>
74 <entry>char</entry>
75 <entry><structfield>name[32]</structfield></entry>
76 <entry>The name of this CEC adapter. The combination <structfield>driver</structfield>
77 and <structfield>name</structfield> must be unique.</entry>
78 </row>
79 <row>
80 <entry>__u32</entry>
81 <entry><structfield>capabilities</structfield></entry>
82 <entry>The capabilities of the CEC adapter, see <xref
83 linkend="cec-capabilities" />.</entry>
84 </row>
85 <row>
86 <entry>__u32</entry>
87 <entry><structfield>version</structfield></entry>
88 <entry>CEC Framework API version, formatted with the
89 <constant>KERNEL_VERSION()</constant> macro.</entry>
90 </row>
91 </tbody>
92 </tgroup>
93 </table>
94
95 <table pgwide="1" frame="none" id="cec-capabilities">
96 <title>CEC Capabilities Flags</title>
97 <tgroup cols="3">
98 &cs-def;
99 <tbody valign="top">
100 <row>
101 <entry><constant>CEC_CAP_PHYS_ADDR</constant></entry>
102 <entry>0x00000001</entry>
103 <entry>Userspace has to configure the physical address by
104 calling &CEC-ADAP-S-PHYS-ADDR;. If this capability isn't set,
105 then setting the physical address is handled by the kernel
106 whenever the EDID is set (for an HDMI receiver) or read (for
107 an HDMI transmitter).</entry>
108 </row>
109 <row>
110 <entry><constant>CEC_CAP_LOG_ADDRS</constant></entry>
111 <entry>0x00000002</entry>
112 <entry>Userspace has to configure the logical addresses by
113 calling &CEC-ADAP-S-LOG-ADDRS;. If this capability isn't set,
114 then the kernel will have configured this.</entry>
115 </row>
116 <row>
117 <entry><constant>CEC_CAP_TRANSMIT</constant></entry>
118 <entry>0x00000004</entry>
119 <entry>Userspace can transmit CEC messages by calling &CEC-TRANSMIT;. This
120 implies that userspace can be a follower as well, since being able to
121 transmit messages is a prerequisite of becoming a follower. If this
122 capability isn't set, then the kernel will handle all CEC transmits
123 and process all CEC messages it receives.
124 </entry>
125 </row>
126 <row>
127 <entry><constant>CEC_CAP_PASSTHROUGH</constant></entry>
128 <entry>0x00000008</entry>
129 <entry>Userspace can use the passthrough mode by
130 calling &CEC-S-MODE;.</entry>
131 </row>
132 <row>
133 <entry><constant>CEC_CAP_RC</constant></entry>
134 <entry>0x00000010</entry>
135 <entry>This adapter supports the remote control protocol.</entry>
136 </row>
137 <row>
138 <entry><constant>CEC_CAP_MONITOR_ALL</constant></entry>
139 <entry>0x00000020</entry>
140 <entry>The CEC hardware can monitor all messages, not just directed and
141 broadcast messages.</entry>
142 </row>
143 </tbody>
144 </tgroup>
145 </table>
146 </refsect1>
147
148 <refsect1>
149 &return-value;
150 </refsect1>
151</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml
new file mode 100644
index 000000000000..302b8294f7fc
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml
@@ -0,0 +1,329 @@
1<refentry id="cec-ioc-adap-g-log-addrs">
2 <refmeta>
3 <refentrytitle>ioctl CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>CEC_ADAP_G_LOG_ADDRS</refname>
9 <refname>CEC_ADAP_S_LOG_ADDRS</refname>
10 <refpurpose>Get or set the logical addresses</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>struct cec_log_addrs *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>File descriptor returned by
32 <link linkend='cec-func-open'><function>open()</function></link>.</para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term><parameter>request</parameter></term>
37 <listitem>
38 <para>CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para></para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <para>
54 Note: this documents the proposed CEC API. This API is not yet finalized and
55 is currently only available as a staging kernel module.
56 </para>
57
58 <para>To query the current CEC logical addresses, applications call the
59<constant>CEC_ADAP_G_LOG_ADDRS</constant> ioctl with a pointer to a
60<structname>cec_log_addrs</structname> structure where the drivers stores the
61logical addresses.</para>
62
63 <para>To set new logical addresses, applications fill in struct <structname>cec_log_addrs</structname>
64and call the <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl with a pointer to this struct.
65The <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl is only available if
66<constant>CEC_CAP_LOG_ADDRS</constant> is set (&ENOTTY; is returned otherwise). This ioctl will block until all
67requested logical addresses have been claimed. <constant>CEC_ADAP_S_LOG_ADDRS</constant>
68can only be called by a file handle in initiator mode (see &CEC-S-MODE;).</para>
69
70 <table pgwide="1" frame="none" id="cec-log-addrs">
71 <title>struct <structname>cec_log_addrs</structname></title>
72 <tgroup cols="3">
73 &cs-str;
74 <tbody valign="top">
75 <row>
76 <entry>__u8</entry>
77 <entry><structfield>log_addr</structfield>[CEC_MAX_LOG_ADDRS]</entry>
78 <entry>The actual logical addresses that were claimed. This is set by the
79 driver. If no logical address could be claimed, then it is set to
80 <constant>CEC_LOG_ADDR_INVALID</constant>. If this adapter is Unregistered,
81 then <structfield>log_addr[0]</structfield> is set to 0xf and all others to
82 <constant>CEC_LOG_ADDR_INVALID</constant>.</entry>
83 </row>
84 <row>
85 <entry>__u16</entry>
86 <entry><structfield>log_addr_mask</structfield></entry>
87 <entry>The bitmask of all logical addresses this adapter has claimed.
88 If this adapter is Unregistered then <structfield>log_addr_mask</structfield>
89 sets bit 15 and clears all other bits. If this adapter is not configured at all, then
90 <structfield>log_addr_mask</structfield> is set to 0. Set by the driver.</entry>
91 </row>
92 <row>
93 <entry>__u8</entry>
94 <entry><structfield>cec_version</structfield></entry>
95 <entry>The CEC version that this adapter shall use. See
96 <xref linkend="cec-versions" />.
97 Used to implement the <constant>CEC_MSG_CEC_VERSION</constant> and
98 <constant>CEC_MSG_REPORT_FEATURES</constant> messages. Note that
99 <constant>CEC_OP_CEC_VERSION_1_3A</constant> is not allowed
100 by the CEC framework.
101 </entry>
102 </row>
103 <row>
104 <entry>__u8</entry>
105 <entry><structfield>num_log_addrs</structfield></entry>
106 <entry>Number of logical addresses to set up. Must be &le;
107 <structfield>available_log_addrs</structfield> as returned by
108 &CEC-ADAP-G-CAPS;. All arrays in this structure are only filled up to
109 index <structfield>available_log_addrs</structfield>-1. The remaining
110 array elements will be ignored. Note that the CEC 2.0 standard allows
111 for a maximum of 2 logical addresses, although some hardware has support
112 for more. <constant>CEC_MAX_LOG_ADDRS</constant> is 4. The driver will
113 return the actual number of logical addresses it could claim, which may
114 be less than what was requested. If this field is set to 0, then the
115 CEC adapter shall clear all claimed logical addresses and all other
116 fields will be ignored.</entry>
117 </row>
118 <row>
119 <entry>__u32</entry>
120 <entry><structfield>vendor_id</structfield></entry>
121 <entry>The vendor ID is a 24-bit number that identifies the specific
122 vendor or entity. Based on this ID vendor specific commands may be
123 defined. If you do not want a vendor ID then set it to
124 <constant>CEC_VENDOR_ID_NONE</constant>.</entry>
125 </row>
126 <row>
127 <entry>__u32</entry>
128 <entry><structfield>flags</structfield></entry>
129 <entry>Flags. No flags are defined yet, so set this to 0.</entry>
130 </row>
131 <row>
132 <entry>char</entry>
133 <entry><structfield>osd_name</structfield>[15]</entry>
134 <entry>The On-Screen Display name as is returned by the
135 <constant>CEC_MSG_SET_OSD_NAME</constant> message.</entry>
136 </row>
137 <row>
138 <entry>__u8</entry>
139 <entry><structfield>primary_device_type</structfield>[CEC_MAX_LOG_ADDRS]</entry>
140 <entry>Primary device type for each logical address. See
141 <xref linkend="cec-prim-dev-types" /> for possible types.</entry>
142 </row>
143 <row>
144 <entry>__u8</entry>
145 <entry><structfield>log_addr_type</structfield>[CEC_MAX_LOG_ADDRS]</entry>
146 <entry>Logical address types. See <xref linkend="cec-log-addr-types" /> for
147 possible types. The driver will update this with the actual logical address
148 type that it claimed (e.g. it may have to fallback to
149 <constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant>).</entry>
150 </row>
151 <row>
152 <entry>__u8</entry>
153 <entry><structfield>all_device_types</structfield>[CEC_MAX_LOG_ADDRS]</entry>
154 <entry>CEC 2.0 specific: all device types. See <xref linkend="cec-all-dev-types-flags" />.
155 Used to implement the <constant>CEC_MSG_REPORT_FEATURES</constant> message.
156 This field is ignored if <structfield>cec_version</structfield> &lt;
157 <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry>
158 </row>
159 <row>
160 <entry>__u8</entry>
161 <entry><structfield>features</structfield>[CEC_MAX_LOG_ADDRS][12]</entry>
162 <entry>Features for each logical address. Used to implement the
163 <constant>CEC_MSG_REPORT_FEATURES</constant> message. The 12 bytes include
164 both the RC Profile and the Device Features.
165 This field is ignored if <structfield>cec_version</structfield> &lt;
166 <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry>
167 </row>
168 </tbody>
169 </tgroup>
170 </table>
171
172 <table pgwide="1" frame="none" id="cec-versions">
173 <title>CEC Versions</title>
174 <tgroup cols="3">
175 &cs-def;
176 <tbody valign="top">
177 <row>
178 <entry><constant>CEC_OP_CEC_VERSION_1_3A</constant></entry>
179 <entry>4</entry>
180 <entry>CEC version according to the HDMI 1.3a standard.</entry>
181 </row>
182 <row>
183 <entry><constant>CEC_OP_CEC_VERSION_1_4B</constant></entry>
184 <entry>5</entry>
185 <entry>CEC version according to the HDMI 1.4b standard.</entry>
186 </row>
187 <row>
188 <entry><constant>CEC_OP_CEC_VERSION_2_0</constant></entry>
189 <entry>6</entry>
190 <entry>CEC version according to the HDMI 2.0 standard.</entry>
191 </row>
192 </tbody>
193 </tgroup>
194 </table>
195
196 <table pgwide="1" frame="none" id="cec-prim-dev-types">
197 <title>CEC Primary Device Types</title>
198 <tgroup cols="3">
199 &cs-def;
200 <tbody valign="top">
201 <row>
202 <entry><constant>CEC_OP_PRIM_DEVTYPE_TV</constant></entry>
203 <entry>0</entry>
204 <entry>Use for a TV.</entry>
205 </row>
206 <row>
207 <entry><constant>CEC_OP_PRIM_DEVTYPE_RECORD</constant></entry>
208 <entry>1</entry>
209 <entry>Use for a recording device.</entry>
210 </row>
211 <row>
212 <entry><constant>CEC_OP_PRIM_DEVTYPE_TUNER</constant></entry>
213 <entry>3</entry>
214 <entry>Use for a device with a tuner.</entry>
215 </row>
216 <row>
217 <entry><constant>CEC_OP_PRIM_DEVTYPE_PLAYBACK</constant></entry>
218 <entry>4</entry>
219 <entry>Use for a playback device.</entry>
220 </row>
221 <row>
222 <entry><constant>CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM</constant></entry>
223 <entry>5</entry>
224 <entry>Use for an audio system (e.g. an audio/video receiver).</entry>
225 </row>
226 <row>
227 <entry><constant>CEC_OP_PRIM_DEVTYPE_SWITCH</constant></entry>
228 <entry>6</entry>
229 <entry>Use for a CEC switch.</entry>
230 </row>
231 <row>
232 <entry><constant>CEC_OP_PRIM_DEVTYPE_VIDEOPROC</constant></entry>
233 <entry>7</entry>
234 <entry>Use for a video processor device.</entry>
235 </row>
236 </tbody>
237 </tgroup>
238 </table>
239
240 <table pgwide="1" frame="none" id="cec-log-addr-types">
241 <title>CEC Logical Address Types</title>
242 <tgroup cols="3">
243 &cs-def;
244 <tbody valign="top">
245 <row>
246 <entry><constant>CEC_LOG_ADDR_TYPE_TV</constant></entry>
247 <entry>0</entry>
248 <entry>Use for a TV.</entry>
249 </row>
250 <row>
251 <entry><constant>CEC_LOG_ADDR_TYPE_RECORD</constant></entry>
252 <entry>1</entry>
253 <entry>Use for a recording device.</entry>
254 </row>
255 <row>
256 <entry><constant>CEC_LOG_ADDR_TYPE_TUNER</constant></entry>
257 <entry>2</entry>
258 <entry>Use for a tuner device.</entry>
259 </row>
260 <row>
261 <entry><constant>CEC_LOG_ADDR_TYPE_PLAYBACK</constant></entry>
262 <entry>3</entry>
263 <entry>Use for a playback device.</entry>
264 </row>
265 <row>
266 <entry><constant>CEC_LOG_ADDR_TYPE_AUDIOSYSTEM</constant></entry>
267 <entry>4</entry>
268 <entry>Use for an audio system device.</entry>
269 </row>
270 <row>
271 <entry><constant>CEC_LOG_ADDR_TYPE_SPECIFIC</constant></entry>
272 <entry>5</entry>
273 <entry>Use for a second TV or for a video processor device.</entry>
274 </row>
275 <row>
276 <entry><constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant></entry>
277 <entry>6</entry>
278 <entry>Use this if you just want to remain unregistered.
279 Used for pure CEC switches or CDC-only devices (CDC:
280 Capability Discovery and Control).</entry>
281 </row>
282 </tbody>
283 </tgroup>
284 </table>
285
286 <table pgwide="1" frame="none" id="cec-all-dev-types-flags">
287 <title>CEC All Device Types Flags</title>
288 <tgroup cols="3">
289 &cs-def;
290 <tbody valign="top">
291 <row>
292 <entry><constant>CEC_OP_ALL_DEVTYPE_TV</constant></entry>
293 <entry>0x80</entry>
294 <entry>This supports the TV type.</entry>
295 </row>
296 <row>
297 <entry><constant>CEC_OP_ALL_DEVTYPE_RECORD</constant></entry>
298 <entry>0x40</entry>
299 <entry>This supports the Recording type.</entry>
300 </row>
301 <row>
302 <entry><constant>CEC_OP_ALL_DEVTYPE_TUNER</constant></entry>
303 <entry>0x20</entry>
304 <entry>This supports the Tuner type.</entry>
305 </row>
306 <row>
307 <entry><constant>CEC_OP_ALL_DEVTYPE_PLAYBACK</constant></entry>
308 <entry>0x10</entry>
309 <entry>This supports the Playback type.</entry>
310 </row>
311 <row>
312 <entry><constant>CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM</constant></entry>
313 <entry>0x08</entry>
314 <entry>This supports the Audio System type.</entry>
315 </row>
316 <row>
317 <entry><constant>CEC_OP_ALL_DEVTYPE_SWITCH</constant></entry>
318 <entry>0x04</entry>
319 <entry>This supports the CEC Switch or Video Processing type.</entry>
320 </row>
321 </tbody>
322 </tgroup>
323 </table>
324 </refsect1>
325
326 <refsect1>
327 &return-value;
328 </refsect1>
329</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml
new file mode 100644
index 000000000000..d95f1785080c
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml
@@ -0,0 +1,86 @@
1<refentry id="cec-ioc-adap-g-phys-addr">
2 <refmeta>
3 <refentrytitle>ioctl CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>CEC_ADAP_G_PHYS_ADDR</refname>
9 <refname>CEC_ADAP_S_PHYS_ADDR</refname>
10 <refpurpose>Get or set the physical address</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>__u16 *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>File descriptor returned by
32 <link linkend='cec-func-open'><function>open()</function></link>.</para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term><parameter>request</parameter></term>
37 <listitem>
38 <para>CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para></para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <para>
54 Note: this documents the proposed CEC API. This API is not yet finalized and
55 is currently only available as a staging kernel module.
56 </para>
57
58 <para>To query the current physical address applications call the
59<constant>CEC_ADAP_G_PHYS_ADDR</constant> ioctl with a pointer to an __u16
60where the driver stores the physical address.</para>
61
62 <para>To set a new physical address applications store the physical address in
63an __u16 and call the <constant>CEC_ADAP_S_PHYS_ADDR</constant> ioctl with a
64pointer to this integer. <constant>CEC_ADAP_S_PHYS_ADDR</constant> is only
65available if <constant>CEC_CAP_PHYS_ADDR</constant> is set (&ENOTTY; will be returned
66otherwise). <constant>CEC_ADAP_S_PHYS_ADDR</constant>
67can only be called by a file handle in initiator mode (see &CEC-S-MODE;), if not
68&EBUSY; will be returned.</para>
69
70 <para>The physical address is a 16-bit number where each group of 4 bits
71represent a digit of the physical address a.b.c.d where the most significant
724 bits represent 'a'. The CEC root device (usually the TV) has address 0.0.0.0.
73Every device that is hooked up to an input of the TV has address a.0.0.0 (where
74'a' is &ge; 1), devices hooked up to those in turn have addresses a.b.0.0, etc.
75So a topology of up to 5 devices deep is supported. The physical address a
76device shall use is stored in the EDID of the sink.</para>
77
78<para>For example, the EDID for each HDMI input of the TV will have a different
79physical address of the form a.0.0.0 that the sources will read out and use as
80their physical address.</para>
81 </refsect1>
82
83 <refsect1>
84 &return-value;
85 </refsect1>
86</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml b/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml
new file mode 100644
index 000000000000..697dde575cd4
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml
@@ -0,0 +1,202 @@
1<refentry id="cec-ioc-g-event">
2 <refmeta>
3 <refentrytitle>ioctl CEC_DQEVENT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>CEC_DQEVENT</refname>
9 <refpurpose>Dequeue a CEC event</refpurpose>
10 </refnamediv>
11
12 <refsynopsisdiv>
13 <funcsynopsis>
14 <funcprototype>
15 <funcdef>int <function>ioctl</function></funcdef>
16 <paramdef>int <parameter>fd</parameter></paramdef>
17 <paramdef>int <parameter>request</parameter></paramdef>
18 <paramdef>struct cec_event *<parameter>argp</parameter></paramdef>
19 </funcprototype>
20 </funcsynopsis>
21 </refsynopsisdiv>
22
23 <refsect1>
24 <title>Arguments</title>
25
26 <variablelist>
27 <varlistentry>
28 <term><parameter>fd</parameter></term>
29 <listitem>
30 <para>File descriptor returned by
31 <link linkend='cec-func-open'><function>open()</function></link>.</para>
32 </listitem>
33 </varlistentry>
34 <varlistentry>
35 <term><parameter>request</parameter></term>
36 <listitem>
37 <para>CEC_DQEVENT</para>
38 </listitem>
39 </varlistentry>
40 <varlistentry>
41 <term><parameter>argp</parameter></term>
42 <listitem>
43 <para></para>
44 </listitem>
45 </varlistentry>
46 </variablelist>
47 </refsect1>
48
49 <refsect1>
50 <title>Description</title>
51
52 <para>
53 Note: this documents the proposed CEC API. This API is not yet finalized and
54 is currently only available as a staging kernel module.
55 </para>
56
57 <para>CEC devices can send asynchronous events. These can be retrieved by calling
58 the <constant>CEC_DQEVENT</constant> ioctl. If the file descriptor is in non-blocking
59 mode and no event is pending, then it will return -1 and set errno to the &EAGAIN;.</para>
60
61 <para>The internal event queues are per-filehandle and per-event type. If there is
62 no more room in a queue then the last event is overwritten with the new one. This
63 means that intermediate results can be thrown away but that the latest event is always
64 available. This also means that is it possible to read two successive events that have
65 the same value (e.g. two CEC_EVENT_STATE_CHANGE events with the same state). In that
66 case the intermediate state changes were lost but it is guaranteed that the state
67 did change in between the two events.</para>
68
69 <table pgwide="1" frame="none" id="cec-event-state-change">
70 <title>struct <structname>cec_event_state_change</structname></title>
71 <tgroup cols="3">
72 &cs-str;
73 <tbody valign="top">
74 <row>
75 <entry>__u16</entry>
76 <entry><structfield>phys_addr</structfield></entry>
77 <entry>The current physical address.</entry>
78 </row>
79 <row>
80 <entry>__u16</entry>
81 <entry><structfield>log_addr_mask</structfield></entry>
82 <entry>The current set of claimed logical addresses.</entry>
83 </row>
84 </tbody>
85 </tgroup>
86 </table>
87
88 <table pgwide="1" frame="none" id="cec-event-lost-msgs">
89 <title>struct <structname>cec_event_lost_msgs</structname></title>
90 <tgroup cols="3">
91 &cs-str;
92 <tbody valign="top">
93 <row>
94 <entry>__u32</entry>
95 <entry><structfield>lost_msgs</structfield></entry>
96 <entry>Set to the number of lost messages since the filehandle
97 was opened or since the last time this event was dequeued for
98 this filehandle. The messages lost are the oldest messages. So
99 when a new message arrives and there is no more room, then the
100 oldest message is discarded to make room for the new one. The
101 internal size of the message queue guarantees that all messages
102 received in the last two seconds will be stored. Since messages
103 should be replied to within a second according to the CEC
104 specification, this is more than enough.
105 </entry>
106 </row>
107 </tbody>
108 </tgroup>
109 </table>
110
111 <table pgwide="1" frame="none" id="cec-event">
112 <title>struct <structname>cec_event</structname></title>
113 <tgroup cols="4">
114 &cs-str;
115 <tbody valign="top">
116 <row>
117 <entry>__u64</entry>
118 <entry><structfield>ts</structfield></entry>
119 <entry>Timestamp of the event in ns.</entry>
120 <entry></entry>
121 </row>
122 <row>
123 <entry>__u32</entry>
124 <entry><structfield>event</structfield></entry>
125 <entry>The CEC event type, see <xref linkend="cec-events" />.</entry>
126 <entry></entry>
127 </row>
128 <row>
129 <entry>__u32</entry>
130 <entry><structfield>flags</structfield></entry>
131 <entry>Event flags, see <xref linkend="cec-event-flags" />.</entry>
132 <entry></entry>
133 </row>
134 <row>
135 <entry>union</entry>
136 <entry>(anonymous)</entry>
137 <entry></entry>
138 <entry></entry>
139 </row>
140 <row>
141 <entry></entry>
142 <entry>struct cec_event_state_change</entry>
143 <entry><structfield>state_change</structfield></entry>
144 <entry>The new adapter state as sent by the <constant>CEC_EVENT_STATE_CHANGE</constant>
145 event.</entry>
146 </row>
147 <row>
148 <entry></entry>
149 <entry>struct cec_event_lost_msgs</entry>
150 <entry><structfield>lost_msgs</structfield></entry>
151 <entry>The number of lost messages as sent by the <constant>CEC_EVENT_LOST_MSGS</constant>
152 event.</entry>
153 </row>
154 </tbody>
155 </tgroup>
156 </table>
157
158 <table pgwide="1" frame="none" id="cec-events">
159 <title>CEC Events Types</title>
160 <tgroup cols="3">
161 &cs-def;
162 <tbody valign="top">
163 <row>
164 <entry><constant>CEC_EVENT_STATE_CHANGE</constant></entry>
165 <entry>1</entry>
166 <entry>Generated when the CEC Adapter's state changes. When open() is
167 called an initial event will be generated for that filehandle with the
168 CEC Adapter's state at that time.
169 </entry>
170 </row>
171 <row>
172 <entry><constant>CEC_EVENT_LOST_MSGS</constant></entry>
173 <entry>2</entry>
174 <entry>Generated if one or more CEC messages were lost because the
175 application didn't dequeue CEC messages fast enough.</entry>
176 </row>
177 </tbody>
178 </tgroup>
179 </table>
180
181 <table pgwide="1" frame="none" id="cec-event-flags">
182 <title>CEC Event Flags</title>
183 <tgroup cols="3">
184 &cs-def;
185 <tbody valign="top">
186 <row>
187 <entry><constant>CEC_EVENT_FL_INITIAL_VALUE</constant></entry>
188 <entry>1</entry>
189 <entry>Set for the initial events that are generated when the device is
190 opened. See the table above for which events do this. This allows
191 applications to learn the initial state of the CEC adapter at open()
192 time.</entry>
193 </row>
194 </tbody>
195 </tgroup>
196 </table>
197 </refsect1>
198
199 <refsect1>
200 &return-value;
201 </refsect1>
202</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml b/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml
new file mode 100644
index 000000000000..26b4282ad134
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml
@@ -0,0 +1,255 @@
1<refentry id="cec-ioc-g-mode">
2 <refmeta>
3 <refentrytitle>ioctl CEC_G_MODE, CEC_S_MODE</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>CEC_G_MODE</refname>
9 <refname>CEC_S_MODE</refname>
10 <refpurpose>Get or set exclusive use of the CEC adapter</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>__u32 *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>File descriptor returned by
32 <link linkend='cec-func-open'><function>open()</function></link>.</para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term><parameter>request</parameter></term>
37 <listitem>
38 <para>CEC_G_MODE, CEC_S_MODE</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para></para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <para>
54 Note: this documents the proposed CEC API. This API is not yet finalized and
55 is currently only available as a staging kernel module.
56 </para>
57
58 <para>By default any filehandle can use &CEC-TRANSMIT; and &CEC-RECEIVE;, but
59in order to prevent applications from stepping on each others toes it must be possible
60to obtain exclusive access to the CEC adapter. This ioctl sets the filehandle
61to initiator and/or follower mode which can be exclusive depending on the chosen
62mode. The initiator is the filehandle that is used
63to initiate messages, i.e. it commands other CEC devices. The follower is the filehandle
64that receives messages sent to the CEC adapter and processes them. The same filehandle
65can be both initiator and follower, or this role can be taken by two different
66filehandles.</para>
67
68 <para>When a CEC message is received, then the CEC framework will decide how
69it will be processed. If the message is a reply to an earlier transmitted message,
70then the reply is sent back to the filehandle that is waiting for it. In addition
71the CEC framework will process it.</para>
72
73 <para>If the message is not a reply, then the CEC framework will process it
74first. If there is no follower, then the message is just discarded and a feature
75abort is sent back to the initiator if the framework couldn't process it. If there
76is a follower, then the message is passed on to the follower who will use
77&CEC-RECEIVE; to dequeue the new message. The framework expects the follower to
78make the right decisions.</para>
79
80 <para>The CEC framework will process core messages unless requested otherwise
81by the follower. The follower can enable the passthrough mode. In that case, the
82CEC framework will pass on most core messages without processing them and
83the follower will have to implement those messages. There are some messages
84that the core will always process, regardless of the passthrough mode. See
85<xref linkend="cec-core-processing" /> for details.</para>
86
87 <para>If there is no initiator, then any CEC filehandle can use &CEC-TRANSMIT;.
88If there is an exclusive initiator then only that initiator can call &CEC-TRANSMIT;.
89The follower can of course always call &CEC-TRANSMIT;.</para>
90
91 <para>Available initiator modes are:</para>
92
93 <table pgwide="1" frame="none" id="cec-mode-initiator">
94 <title>Initiator Modes</title>
95 <tgroup cols="3">
96 &cs-def;
97 <tbody valign="top">
98 <row>
99 <entry><constant>CEC_MODE_NO_INITIATOR</constant></entry>
100 <entry>0x0</entry>
101 <entry>This is not an initiator, i.e. it cannot transmit CEC messages
102 or make any other changes to the CEC adapter.</entry>
103 </row>
104 <row>
105 <entry><constant>CEC_MODE_INITIATOR</constant></entry>
106 <entry>0x1</entry>
107 <entry>This is an initiator (the default when the device is opened) and it
108 can transmit CEC messages and make changes to the CEC adapter, unless there
109 is an exclusive initiator.</entry>
110 </row>
111 <row>
112 <entry><constant>CEC_MODE_EXCL_INITIATOR</constant></entry>
113 <entry>0x2</entry>
114 <entry>This is an exclusive initiator and this file descriptor is the only one
115 that can transmit CEC messages and make changes to the CEC adapter. If someone
116 else is already the exclusive initiator then an attempt to become one will return
117 the &EBUSY; error.</entry>
118 </row>
119 </tbody>
120 </tgroup>
121 </table>
122
123 <para>Available follower modes are:</para>
124
125 <table pgwide="1" frame="none" id="cec-mode-follower">
126 <title>Follower Modes</title>
127 <tgroup cols="3">
128 &cs-def;
129 <tbody valign="top">
130 <row>
131 <entry><constant>CEC_MODE_NO_FOLLOWER</constant></entry>
132 <entry>0x00</entry>
133 <entry>This is not a follower (the default when the device is opened).</entry>
134 </row>
135 <row>
136 <entry><constant>CEC_MODE_FOLLOWER</constant></entry>
137 <entry>0x10</entry>
138 <entry>This is a follower and it will receive CEC messages unless there is
139 an exclusive follower. You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant>
140 is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified,
141 &EINVAL; is returned in that case.</entry>
142 </row>
143 <row>
144 <entry><constant>CEC_MODE_EXCL_FOLLOWER</constant></entry>
145 <entry>0x20</entry>
146 <entry>This is an exclusive follower and only this file descriptor will receive
147 CEC messages for processing. If someone else is already the exclusive follower
148 then an attempt to become one will return the &EBUSY; error. You cannot become
149 a follower if <constant>CEC_CAP_TRANSMIT</constant> is not set or if
150 <constant>CEC_MODE_NO_INITIATOR</constant> was specified, &EINVAL; is returned
151 in that case.</entry>
152 </row>
153 <row>
154 <entry><constant>CEC_MODE_EXCL_FOLLOWER_PASSTHRU</constant></entry>
155 <entry>0x30</entry>
156 <entry>This is an exclusive follower and only this file descriptor will receive
157 CEC messages for processing. In addition it will put the CEC device into
158 passthrough mode, allowing the exclusive follower to handle most core messages
159 instead of relying on the CEC framework for that. If someone else is already the
160 exclusive follower then an attempt to become one will return the &EBUSY; error.
161 You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant>
162 is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified,
163 &EINVAL; is returned in that case.</entry>
164 </row>
165 <row>
166 <entry><constant>CEC_MODE_MONITOR</constant></entry>
167 <entry>0xe0</entry>
168 <entry>Put the file descriptor into monitor mode. Can only be used in combination
169 with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be
170 returned. In monitor mode all messages this CEC device transmits and all messages
171 it receives (both broadcast messages and directed messages for one its logical
172 addresses) will be reported. This is very useful for debugging. This is only
173 allowed if the process has the <constant>CAP_NET_ADMIN</constant>
174 capability. If that is not set, then &EPERM; is returned.</entry>
175 </row>
176 <row>
177 <entry><constant>CEC_MODE_MONITOR_ALL</constant></entry>
178 <entry>0xf0</entry>
179 <entry>Put the file descriptor into 'monitor all' mode. Can only be used in combination
180 with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be
181 returned. In 'monitor all' mode all messages this CEC device transmits and all messages
182 it receives, including directed messages for other CEC devices will be reported. This
183 is very useful for debugging, but not all devices support this. This mode requires that
184 the <constant>CEC_CAP_MONITOR_ALL</constant> capability is set, otherwise &EINVAL; is
185 returned. This is only allowed if the process has the <constant>CAP_NET_ADMIN</constant>
186 capability. If that is not set, then &EPERM; is returned.</entry>
187 </row>
188 </tbody>
189 </tgroup>
190 </table>
191
192 <para>Core message processing details:</para>
193
194 <table pgwide="1" frame="none" id="cec-core-processing">
195 <title>Core Message Processing</title>
196 <tgroup cols="2">
197 &cs-def;
198 <tbody valign="top">
199 <row>
200 <entry><constant>CEC_MSG_GET_CEC_VERSION</constant></entry>
201 <entry>When in passthrough mode this message has to be handled by userspace,
202 otherwise the core will return the CEC version that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry>
203 </row>
204 <row>
205 <entry><constant>CEC_MSG_GIVE_DEVICE_VENDOR_ID</constant></entry>
206 <entry>When in passthrough mode this message has to be handled by userspace,
207 otherwise the core will return the vendor ID that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry>
208 </row>
209 <row>
210 <entry><constant>CEC_MSG_ABORT</constant></entry>
211 <entry>When in passthrough mode this message has to be handled by userspace,
212 otherwise the core will return a feature refused message as per the specification.</entry>
213 </row>
214 <row>
215 <entry><constant>CEC_MSG_GIVE_PHYSICAL_ADDR</constant></entry>
216 <entry>When in passthrough mode this message has to be handled by userspace,
217 otherwise the core will report the current physical address.</entry>
218 </row>
219 <row>
220 <entry><constant>CEC_MSG_GIVE_OSD_NAME</constant></entry>
221 <entry>When in passthrough mode this message has to be handled by userspace,
222 otherwise the core will report the current OSD name as was set with
223 &CEC-ADAP-S-LOG-ADDRS;.</entry>
224 </row>
225 <row>
226 <entry><constant>CEC_MSG_GIVE_FEATURES</constant></entry>
227 <entry>When in passthrough mode this message has to be handled by userspace,
228 otherwise the core will report the current features as was set with
229 &CEC-ADAP-S-LOG-ADDRS; or the message is ignore if the CEC version was
230 older than 2.0.</entry>
231 </row>
232 <row>
233 <entry><constant>CEC_MSG_USER_CONTROL_PRESSED</constant></entry>
234 <entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control
235 key press. This message is always passed on to userspace.</entry>
236 </row>
237 <row>
238 <entry><constant>CEC_MSG_USER_CONTROL_RELEASED</constant></entry>
239 <entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control
240 key release. This message is always passed on to userspace.</entry>
241 </row>
242 <row>
243 <entry><constant>CEC_MSG_REPORT_PHYSICAL_ADDR</constant></entry>
244 <entry>The CEC framework will make note of the reported physical address
245 and then just pass the message on to userspace.</entry>
246 </row>
247 </tbody>
248 </tgroup>
249 </table>
250 </refsect1>
251
252 <refsect1>
253 &return-value;
254 </refsect1>
255</refentry>
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-receive.xml b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml
new file mode 100644
index 000000000000..fde9f8678e67
--- /dev/null
+++ b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml
@@ -0,0 +1,274 @@
1<refentry id="cec-ioc-receive">
2 <refmeta>
3 <refentrytitle>ioctl CEC_RECEIVE, CEC_TRANSMIT</refentrytitle>
4 &manvol;
5 </refmeta>
6
7 <refnamediv>
8 <refname>CEC_RECEIVE</refname>
9 <refname>CEC_TRANSMIT</refname>
10 <refpurpose>Receive or transmit a CEC message</refpurpose>
11 </refnamediv>
12
13 <refsynopsisdiv>
14 <funcsynopsis>
15 <funcprototype>
16 <funcdef>int <function>ioctl</function></funcdef>
17 <paramdef>int <parameter>fd</parameter></paramdef>
18 <paramdef>int <parameter>request</parameter></paramdef>
19 <paramdef>struct cec_msg *<parameter>argp</parameter></paramdef>
20 </funcprototype>
21 </funcsynopsis>
22 </refsynopsisdiv>
23
24 <refsect1>
25 <title>Arguments</title>
26
27 <variablelist>
28 <varlistentry>
29 <term><parameter>fd</parameter></term>
30 <listitem>
31 <para>File descriptor returned by
32 <link linkend='cec-func-open'><function>open()</function></link>.</para>
33 </listitem>
34 </varlistentry>
35 <varlistentry>
36 <term><parameter>request</parameter></term>
37 <listitem>
38 <para>CEC_RECEIVE, CEC_TRANSMIT</para>
39 </listitem>
40 </varlistentry>
41 <varlistentry>
42 <term><parameter>argp</parameter></term>
43 <listitem>
44 <para></para>
45 </listitem>
46 </varlistentry>
47 </variablelist>
48 </refsect1>
49
50 <refsect1>
51 <title>Description</title>
52
53 <para>
54 Note: this documents the proposed CEC API. This API is not yet finalized and
55 is currently only available as a staging kernel module.
56 </para>
57
58 <para>To receive a CEC message the application has to fill in the
59 <structname>cec_msg</structname> structure and pass it to the
60 <constant>CEC_RECEIVE</constant> ioctl. <constant>CEC_RECEIVE</constant> is
61 only available if <constant>CEC_CAP_RECEIVE</constant> is set. If the
62 file descriptor is in non-blocking mode and there are no received
63 messages pending, then it will return -1 and set errno to the &EAGAIN;.
64 If the file descriptor is in blocking mode and <structfield>timeout</structfield>
65 is non-zero and no message arrived within <structfield>timeout</structfield>
66 milliseconds, then it will return -1 and set errno to the &ETIMEDOUT;.</para>
67
68 <para>To send a CEC message the application has to fill in the
69 <structname>cec_msg</structname> structure and pass it to the
70 <constant>CEC_TRANSMIT</constant> ioctl. <constant>CEC_TRANSMIT</constant> is
71 only available if <constant>CEC_CAP_TRANSMIT</constant> is set.
72 If there is no more room in the transmit queue, then it will return
73 -1 and set errno to the &EBUSY;.</para>
74
75 <table pgwide="1" frame="none" id="cec-msg">
76 <title>struct <structname>cec_msg</structname></title>
77 <tgroup cols="3">
78 &cs-str;
79 <tbody valign="top">
80 <row>
81 <entry>__u64</entry>
82 <entry><structfield>ts</structfield></entry>
83 <entry>Timestamp of when the message was transmitted in ns in the case
84 of <constant>CEC_TRANSMIT</constant> with <structfield>reply</structfield>
85 set to 0, or the timestamp of the received message in all other cases.</entry>
86 </row>
87 <row>
88 <entry>__u32</entry>
89 <entry><structfield>len</structfield></entry>
90 <entry>The length of the message. For <constant>CEC_TRANSMIT</constant> this
91 is filled in by the application. The driver will fill this in for
92 <constant>CEC_RECEIVE</constant> and for <constant>CEC_TRANSMIT</constant>
93 it will be filled in with the length of the reply message if
94 <structfield>reply</structfield> was set.</entry>
95 </row>
96 <row>
97 <entry>__u32</entry>
98 <entry><structfield>timeout</structfield></entry>
99 <entry>The timeout in milliseconds. This is the time the device will wait for a message to
100 be received before timing out. If it is set to 0, then it will wait indefinitely when it
101 is called by <constant>CEC_RECEIVE</constant>. If it is 0 and it is called by
102 <constant>CEC_TRANSMIT</constant>, then it will be replaced by 1000 if the
103 <structfield>reply</structfield> is non-zero or ignored if <structfield>reply</structfield>
104 is 0.</entry>
105 </row>
106 <row>
107 <entry>__u32</entry>
108 <entry><structfield>sequence</structfield></entry>
109 <entry>The sequence number is automatically assigned by the CEC
110 framework for all transmitted messages. It can be later used by the
111 framework to generate an event if a reply for a message was
112 requested and the message was transmitted in a non-blocking mode.
113 </entry>
114 </row>
115 <row>
116 <entry>__u32</entry>
117 <entry><structfield>flags</structfield></entry>
118 <entry>Flags. No flags are defined yet, so set this to 0.</entry>
119 </row>
120 <row>
121 <entry>__u8</entry>
122 <entry><structfield>rx_status</structfield></entry>
123 <entry>The status bits of the received message. See <xref linkend="cec-rx-status" />
124 for the possible status values. It is 0 if this message was transmitted, not
125 received, unless this is the reply to a transmitted message. In that case both
126 <structfield>rx_status</structfield> and <structfield>tx_status</structfield>
127 are set.</entry>
128 </row>
129 <row>
130 <entry>__u8</entry>
131 <entry><structfield>tx_status</structfield></entry>
132 <entry>The status bits of the transmitted message. See <xref linkend="cec-tx-status" />
133 for the possible status values. It is 0 if this messages was received, not
134 transmitted.</entry>
135 </row>
136 <row>
137 <entry>__u8</entry>
138 <entry><structfield>msg</structfield>[16]</entry>
139 <entry>The message payload. For <constant>CEC_TRANSMIT</constant> this
140 is filled in by the application. The driver will fill this in for
141 <constant>CEC_RECEIVE</constant> and for <constant>CEC_TRANSMIT</constant>
142 it will be filled in with the payload of the reply message if
143 <structfield>reply</structfield> was set.</entry>
144 </row>
145 <row>
146 <entry>__u8</entry>
147 <entry><structfield>reply</structfield></entry>
148 <entry>Wait until this message is replied. If <structfield>reply</structfield>
149 is 0 and the <structfield>timeout</structfield> is 0, then don't wait for a reply but
150 return after transmitting the message. If there was an error as indicated by a non-zero
151 <structfield>tx_status</structfield> field, then <structfield>reply</structfield> and
152 <structfield>timeout</structfield> are both set to 0 by the driver. Ignored by
153 <constant>CEC_RECEIVE</constant>. The case where <structfield>reply</structfield> is 0
154 (this is the opcode for the Feature Abort message) and <structfield>timeout</structfield>
155 is non-zero is specifically allowed to send a message and wait up to <structfield>timeout</structfield>
156 milliseconds for a Feature Abort reply. In this case <structfield>rx_status</structfield>
157 will either be set to <constant>CEC_RX_STATUS_TIMEOUT</constant> or
158 <constant>CEC_RX_STATUS_FEATURE_ABORT</constant>.</entry>
159 </row>
160 <row>
161 <entry>__u8</entry>
162 <entry><structfield>tx_arb_lost_cnt</structfield></entry>
163 <entry>A counter of the number of transmit attempts that resulted in the
164 Arbitration Lost error. This is only set if the hardware supports this, otherwise
165 it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_ARB_LOST</constant>
166 status bit is set.</entry>
167 </row>
168 <row>
169 <entry>__u8</entry>
170 <entry><structfield>tx_nack_cnt</structfield></entry>
171 <entry>A counter of the number of transmit attempts that resulted in the
172 Not Acknowledged error. This is only set if the hardware supports this, otherwise
173 it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_NACK</constant>
174 status bit is set.</entry>
175 </row>
176 <row>
177 <entry>__u8</entry>
178 <entry><structfield>tx_low_drive_cnt</structfield></entry>
179 <entry>A counter of the number of transmit attempts that resulted in the
180 Arbitration Lost error. This is only set if the hardware supports this, otherwise
181 it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_LOW_DRIVE</constant>
182 status bit is set.</entry>
183 </row>
184 <row>
185 <entry>__u8</entry>
186 <entry><structfield>tx_error_cnt</structfield></entry>
187 <entry>A counter of the number of transmit errors other than Arbitration Lost
188 or Not Acknowledged. This is only set if the hardware supports this, otherwise
189 it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_ERROR</constant>
190 status bit is set.</entry>
191 </row>
192 </tbody>
193 </tgroup>
194 </table>
195
196 <table pgwide="1" frame="none" id="cec-tx-status">
197 <title>CEC Transmit Status</title>
198 <tgroup cols="3">
199 &cs-def;
200 <tbody valign="top">
201 <row>
202 <entry><constant>CEC_TX_STATUS_OK</constant></entry>
203 <entry>0x01</entry>
204 <entry>The message was transmitted successfully. This is mutually exclusive with
205 <constant>CEC_TX_STATUS_MAX_RETRIES</constant>. Other bits can still be set if
206 earlier attempts met with failure before the transmit was eventually successful.</entry>
207 </row>
208 <row>
209 <entry><constant>CEC_TX_STATUS_ARB_LOST</constant></entry>
210 <entry>0x02</entry>
211 <entry>CEC line arbitration was lost.</entry>
212 </row>
213 <row>
214 <entry><constant>CEC_TX_STATUS_NACK</constant></entry>
215 <entry>0x04</entry>
216 <entry>Message was not acknowledged.</entry>
217 </row>
218 <row>
219 <entry><constant>CEC_TX_STATUS_LOW_DRIVE</constant></entry>
220 <entry>0x08</entry>
221 <entry>Low drive was detected on the CEC bus. This indicates that a follower
222 detected an error on the bus and requests a retransmission.</entry>
223 </row>
224 <row>
225 <entry><constant>CEC_TX_STATUS_ERROR</constant></entry>
226 <entry>0x10</entry>
227 <entry>Some error occurred. This is used for any errors that do not
228 fit the previous two, either because the hardware could not tell
229 which error occurred, or because the hardware tested for other conditions
230 besides those two.</entry>
231 </row>
232 <row>
233 <entry><constant>CEC_TX_STATUS_MAX_RETRIES</constant></entry>
234 <entry>0x20</entry>
235 <entry>The transmit failed after one or more retries. This status bit is mutually
236 exclusive with <constant>CEC_TX_STATUS_OK</constant>. Other bits can still be set
237 to explain which failures were seen.</entry>
238 </row>
239 </tbody>
240 </tgroup>
241 </table>
242
243 <table pgwide="1" frame="none" id="cec-rx-status">
244 <title>CEC Receive Status</title>
245 <tgroup cols="3">
246 &cs-def;
247 <tbody valign="top">
248 <row>
249 <entry><constant>CEC_RX_STATUS_OK</constant></entry>
250 <entry>0x01</entry>
251 <entry>The message was received successfully.</entry>
252 </row>
253 <row>
254 <entry><constant>CEC_RX_STATUS_TIMEOUT</constant></entry>
255 <entry>0x02</entry>
256 <entry>The reply to an earlier transmitted message timed out.</entry>
257 </row>
258 <row>
259 <entry><constant>CEC_RX_STATUS_FEATURE_ABORT</constant></entry>
260 <entry>0x04</entry>
261 <entry>The message was received successfully but the reply was
262 <constant>CEC_MSG_FEATURE_ABORT</constant>. This status is only
263 set if this message was the reply to an earlier transmitted
264 message.</entry>
265 </row>
266 </tbody>
267 </tgroup>
268 </table>
269 </refsect1>
270
271 <refsect1>
272 &return-value;
273 </refsect1>
274</refentry>
diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml
index e09025db92bd..21a3dde8f95d 100644
--- a/Documentation/DocBook/media/v4l/io.xml
+++ b/Documentation/DocBook/media/v4l/io.xml
@@ -88,7 +88,7 @@ function.<footnote>
88<structfield>capabilities</structfield> field of &v4l2-capability; 88<structfield>capabilities</structfield> field of &v4l2-capability;
89returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two 89returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two
90streaming methods, to determine if the memory mapping flavor is 90streaming methods, to determine if the memory mapping flavor is
91supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> 91supported applications must call the &VIDIOC-REQBUFS; ioctl with the memory type set to <constant>V4L2_MEMORY_MMAP</constant>.</para>
92 92
93 <para>Streaming is an I/O method where only pointers to buffers 93 <para>Streaming is an I/O method where only pointers to buffers
94are exchanged between application and driver, the data itself is not 94are exchanged between application and driver, the data itself is not
@@ -369,7 +369,7 @@ rest should be evident.</para>
369<structfield>capabilities</structfield> field of &v4l2-capability; 369<structfield>capabilities</structfield> field of &v4l2-capability;
370returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user 370returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user
371pointer method (not only memory mapping) is supported must be 371pointer method (not only memory mapping) is supported must be
372determined by calling the &VIDIOC-REQBUFS; ioctl.</para> 372determined by calling the &VIDIOC-REQBUFS; ioctl with the memory type set to <constant>V4L2_MEMORY_USERPTR</constant>.</para>
373 373
374 <para>This I/O method combines advantages of the read/write and 374 <para>This I/O method combines advantages of the read/write and
375memory mapping methods. Buffers (planes) are allocated by the application 375memory mapping methods. Buffers (planes) are allocated by the application
diff --git a/Documentation/DocBook/media/v4l/lirc_device_interface.xml b/Documentation/DocBook/media/v4l/lirc_device_interface.xml
index 34cada2ca710..71f9dbb81ec7 100644
--- a/Documentation/DocBook/media/v4l/lirc_device_interface.xml
+++ b/Documentation/DocBook/media/v4l/lirc_device_interface.xml
@@ -157,7 +157,7 @@ on working with the default settings initially.</para>
157 <varlistentry> 157 <varlistentry>
158 <term>LIRC_SET_{SEND,REC}_CARRIER</term> 158 <term>LIRC_SET_{SEND,REC}_CARRIER</term>
159 <listitem> 159 <listitem>
160 <para>Set send/receive carrier (in Hz).</para> 160 <para>Set send/receive carrier (in Hz). Return 0 on success.</para>
161 </listitem> 161 </listitem>
162 </varlistentry> 162 </varlistentry>
163 <varlistentry> 163 <varlistentry>
diff --git a/Documentation/DocBook/media/v4l/media-types.xml b/Documentation/DocBook/media/v4l/media-types.xml
index 5e3f20fdcf17..95aa1f9c836a 100644
--- a/Documentation/DocBook/media/v4l/media-types.xml
+++ b/Documentation/DocBook/media/v4l/media-types.xml
@@ -121,6 +121,70 @@
121 <entry><constant>MEDIA_ENT_F_AUDIO_MIXER</constant></entry> 121 <entry><constant>MEDIA_ENT_F_AUDIO_MIXER</constant></entry>
122 <entry>Audio Mixer Function Entity.</entry> 122 <entry>Audio Mixer Function Entity.</entry>
123 </row> 123 </row>
124 <row>
125 <entry><constant>MEDIA_ENT_F_PROC_VIDEO_COMPOSER</constant></entry>
126 <entry>Video composer (blender). An entity capable of video
127 composing must have at least two sink pads and one source
128 pad, and composes input video frames onto output video
129 frames. Composition can be performed using alpha blending,
130 color keying, raster operations (ROP), stitching or any other
131 means.
132 </entry>
133 </row>
134 <row>
135 <entry><constant>MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER</constant></entry>
136 <entry>Video pixel formatter. An entity capable of pixel formatting
137 must have at least one sink pad and one source pad. Read
138 pixel formatters read pixels from memory and perform a subset
139 of unpacking, cropping, color keying, alpha multiplication
140 and pixel encoding conversion. Write pixel formatters perform
141 a subset of dithering, pixel encoding conversion and packing
142 and write pixels to memory.
143 </entry>
144 </row>
145 <row>
146 <entry><constant>MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV</constant></entry>
147 <entry>Video pixel encoding converter. An entity capable of pixel
148 enconding conversion must have at least one sink pad and one
149 source pad, and convert the encoding of pixels received on
150 its sink pad(s) to a different encoding output on its source
151 pad(s). Pixel encoding conversion includes but isn't limited
152 to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB
153 conversions.
154 </entry>
155 </row>
156 <row>
157 <entry><constant>MEDIA_ENT_F_PROC_VIDEO_LUT</constant></entry>
158 <entry>Video look-up table. An entity capable of video lookup table
159 processing must have one sink pad and one source pad. It uses
160 the values of the pixels received on its sink pad to look up
161 entries in internal tables and output them on its source pad.
162 The lookup processing can be performed on all components
163 separately or combine them for multi-dimensional table
164 lookups.
165 </entry>
166 </row>
167 <row>
168 <entry><constant>MEDIA_ENT_F_PROC_VIDEO_SCALER</constant></entry>
169 <entry>Video scaler. An entity capable of video scaling must have
170 at least one sink pad and one source pad, and scale the
171 video frame(s) received on its sink pad(s) to a different
172 resolution output on its source pad(s). The range of
173 supported scaling ratios is entity-specific and can differ
174 between the horizontal and vertical directions (in particular
175 scaling can be supported in one direction only). Binning and
176 skipping are considered as scaling.
177 </entry>
178 </row>
179 <row>
180 <entry><constant>MEDIA_ENT_F_PROC_VIDEO_STATISTICS</constant></entry>
181 <entry>Video statistics computation (histogram, 3A, ...). An entity
182 capable of statistics computation must have one sink pad and
183 one source pad. It computes statistics over the frames
184 received on its sink pad and outputs the statistics data on
185 its source pad.
186 </entry>
187 </row>
124 </tbody> 188 </tbody>
125 </tgroup> 189 </tgroup>
126 </table> 190 </table>
diff --git a/Documentation/DocBook/media/v4l/pixfmt-z16.xml b/Documentation/DocBook/media/v4l/pixfmt-z16.xml
index 3d87e4bf87b8..1d9cb1684bd3 100644
--- a/Documentation/DocBook/media/v4l/pixfmt-z16.xml
+++ b/Documentation/DocBook/media/v4l/pixfmt-z16.xml
@@ -5,7 +5,7 @@
5 </refmeta> 5 </refmeta>
6 <refnamediv> 6 <refnamediv>
7 <refname><constant>V4L2_PIX_FMT_Z16</constant></refname> 7 <refname><constant>V4L2_PIX_FMT_Z16</constant></refname>
8 <refpurpose>Interleaved grey-scale image, e.g. from a stereo-pair</refpurpose> 8 <refpurpose>16-bit depth data with distance values at each pixel</refpurpose>
9 </refnamediv> 9 </refnamediv>
10 <refsect1> 10 <refsect1>
11 <title>Description</title> 11 <title>Description</title>
diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
index 0f193fda0470..6f529e100ea4 100644
--- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
+++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml
@@ -6,7 +6,7 @@
6 6
7 <refnamediv> 7 <refnamediv>
8 <refname>VIDIOC_REQBUFS</refname> 8 <refname>VIDIOC_REQBUFS</refname>
9 <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose> 9 <refpurpose>Initiate Memory Mapping, User Pointer or DMA Buffer I/O</refpurpose>
10 </refnamediv> 10 </refnamediv>
11 11
12 <refsynopsisdiv> 12 <refsynopsisdiv>
diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl
index 7b77e0f7b87d..a2765d8ad05c 100644
--- a/Documentation/DocBook/media_api.tmpl
+++ b/Documentation/DocBook/media_api.tmpl
@@ -75,7 +75,7 @@
75 </mediaobject> 75 </mediaobject>
76 </figure> 76 </figure>
77 <para>The media infrastructure API was designed to control such 77 <para>The media infrastructure API was designed to control such
78 devices. It is divided into four parts.</para> 78 devices. It is divided into five parts.</para>
79 <para>The first part covers radio, video capture and output, 79 <para>The first part covers radio, video capture and output,
80 cameras, analog TV devices and codecs.</para> 80 cameras, analog TV devices and codecs.</para>
81 <para>The second part covers the 81 <para>The second part covers the
@@ -87,6 +87,7 @@
87 <xref linkend="fe-delivery-system-t" />.</para> 87 <xref linkend="fe-delivery-system-t" />.</para>
88 <para>The third part covers the Remote Controller API.</para> 88 <para>The third part covers the Remote Controller API.</para>
89 <para>The fourth part covers the Media Controller API.</para> 89 <para>The fourth part covers the Media Controller API.</para>
90 <para>The fifth part covers the CEC (Consumer Electronics Control) API.</para>
90 <para>It should also be noted that a media device may also have audio 91 <para>It should also be noted that a media device may also have audio
91 components, like mixers, PCM capture, PCM playback, etc, which 92 components, like mixers, PCM capture, PCM playback, etc, which
92 are controlled via ALSA API.</para> 93 are controlled via ALSA API.</para>
@@ -107,6 +108,9 @@
107<part id="media_common"> 108<part id="media_common">
108&sub-media-controller; 109&sub-media-controller;
109</part> 110</part>
111<part id="cec">
112&sub-cec-api;
113</part>
110 114
111<chapter id="gen_errors"> 115<chapter id="gen_errors">
112&sub-gen-errors; 116&sub-gen-errors;
diff --git a/Documentation/cec.txt b/Documentation/cec.txt
new file mode 100644
index 000000000000..75155fe37153
--- /dev/null
+++ b/Documentation/cec.txt
@@ -0,0 +1,267 @@
1CEC Kernel Support
2==================
3
4The CEC framework provides a unified kernel interface for use with HDMI CEC
5hardware. It is designed to handle a multiple types of hardware (receivers,
6transmitters, USB dongles). The framework also gives the option to decide
7what to do in the kernel driver and what should be handled by userspace
8applications. In addition it integrates the remote control passthrough
9feature into the kernel's remote control framework.
10
11
12The CEC Protocol
13----------------
14
15The CEC protocol enables consumer electronic devices to communicate with each
16other through the HDMI connection. The protocol uses logical addresses in the
17communication. The logical address is strictly connected with the functionality
18provided by the device. The TV acting as the communication hub is always
19assigned address 0. The physical address is determined by the physical
20connection between devices.
21
22The CEC framework described here is up to date with the CEC 2.0 specification.
23It is documented in the HDMI 1.4 specification with the new 2.0 bits documented
24in the HDMI 2.0 specification. But for most of the features the freely available
25HDMI 1.3a specification is sufficient:
26
27http://www.microprocessor.org/HDMISpecification13a.pdf
28
29
30The Kernel Interface
31====================
32
33CEC Adapter
34-----------
35
36The struct cec_adapter represents the CEC adapter hardware. It is created by
37calling cec_allocate_adapter() and deleted by calling cec_delete_adapter():
38
39struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops,
40 void *priv, const char *name, u32 caps, u8 available_las,
41 struct device *parent);
42void cec_delete_adapter(struct cec_adapter *adap);
43
44To create an adapter you need to pass the following information:
45
46ops: adapter operations which are called by the CEC framework and that you
47have to implement.
48
49priv: will be stored in adap->priv and can be used by the adapter ops.
50
51name: the name of the CEC adapter. Note: this name will be copied.
52
53caps: capabilities of the CEC adapter. These capabilities determine the
54 capabilities of the hardware and which parts are to be handled
55 by userspace and which parts are handled by kernelspace. The
56 capabilities are returned by CEC_ADAP_G_CAPS.
57
58available_las: the number of simultaneous logical addresses that this
59 adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS.
60
61parent: the parent device.
62
63
64To register the /dev/cecX device node and the remote control device (if
65CEC_CAP_RC is set) you call:
66
67int cec_register_adapter(struct cec_adapter *adap);
68
69To unregister the devices call:
70
71void cec_unregister_adapter(struct cec_adapter *adap);
72
73Note: if cec_register_adapter() fails, then call cec_delete_adapter() to
74clean up. But if cec_register_adapter() succeeded, then only call
75cec_unregister_adapter() to clean up, never cec_delete_adapter(). The
76unregister function will delete the adapter automatically once the last user
77of that /dev/cecX device has closed its file handle.
78
79
80Implementing the Low-Level CEC Adapter
81--------------------------------------
82
83The following low-level adapter operations have to be implemented in
84your driver:
85
86struct cec_adap_ops {
87 /* Low-level callbacks */
88 int (*adap_enable)(struct cec_adapter *adap, bool enable);
89 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
90 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
91 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
92 u32 signal_free_time, struct cec_msg *msg);
93 void (*adap_log_status)(struct cec_adapter *adap);
94
95 /* High-level callbacks */
96 ...
97};
98
99The three low-level ops deal with various aspects of controlling the CEC adapter
100hardware:
101
102
103To enable/disable the hardware:
104
105 int (*adap_enable)(struct cec_adapter *adap, bool enable);
106
107This callback enables or disables the CEC hardware. Enabling the CEC hardware
108means powering it up in a state where no logical addresses are claimed. This
109op assumes that the physical address (adap->phys_addr) is valid when enable is
110true and will not change while the CEC adapter remains enabled. The initial
111state of the CEC adapter after calling cec_allocate_adapter() is disabled.
112
113Note that adap_enable must return 0 if enable is false.
114
115
116To enable/disable the 'monitor all' mode:
117
118 int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable);
119
120If enabled, then the adapter should be put in a mode to also monitor messages
121that not for us. Not all hardware supports this and this function is only
122called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional
123(some hardware may always be in 'monitor all' mode).
124
125Note that adap_monitor_all_enable must return 0 if enable is false.
126
127
128To program a new logical address:
129
130 int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr);
131
132If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses
133are to be erased. Otherwise the given logical address should be programmed.
134If the maximum number of available logical addresses is exceeded, then it
135should return -ENXIO. Once a logical address is programmed the CEC hardware
136can receive directed messages to that address.
137
138Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID.
139
140
141To transmit a new message:
142
143 int (*adap_transmit)(struct cec_adapter *adap, u8 attempts,
144 u32 signal_free_time, struct cec_msg *msg);
145
146This transmits a new message. The attempts argument is the suggested number of
147attempts for the transmit.
148
149The signal_free_time is the number of data bit periods that the adapter should
150wait when the line is free before attempting to send a message. This value
151depends on whether this transmit is a retry, a message from a new initiator or
152a new message for the same initiator. Most hardware will handle this
153automatically, but in some cases this information is needed.
154
155The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to
156microseconds (one data bit period is 2.4 ms).
157
158
159To log the current CEC hardware status:
160
161 void (*adap_status)(struct cec_adapter *adap, struct seq_file *file);
162
163This optional callback can be used to show the status of the CEC hardware.
164The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status
165
166
167Your adapter driver will also have to react to events (typically interrupt
168driven) by calling into the framework in the following situations:
169
170When a transmit finished (successfully or otherwise):
171
172void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt,
173 u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt);
174
175The status can be one of:
176
177CEC_TX_STATUS_OK: the transmit was successful.
178CEC_TX_STATUS_ARB_LOST: arbitration was lost: another CEC initiator
179took control of the CEC line and you lost the arbitration.
180CEC_TX_STATUS_NACK: the message was nacked (for a directed message) or
181acked (for a broadcast message). A retransmission is needed.
182CEC_TX_STATUS_LOW_DRIVE: low drive was detected on the CEC bus. This
183indicates that a follower detected an error on the bus and requested a
184retransmission.
185CEC_TX_STATUS_ERROR: some unspecified error occurred: this can be one of
186the previous two if the hardware cannot differentiate or something else
187entirely.
188CEC_TX_STATUS_MAX_RETRIES: could not transmit the message after
189trying multiple times. Should only be set by the driver if it has hardware
190support for retrying messages. If set, then the framework assumes that it
191doesn't have to make another attempt to transmit the message since the
192hardware did that already.
193
194The *_cnt arguments are the number of error conditions that were seen.
195This may be 0 if no information is available. Drivers that do not support
196hardware retry can just set the counter corresponding to the transmit error
197to 1, if the hardware does support retry then either set these counters to
1980 if the hardware provides no feedback of which errors occurred and how many
199times, or fill in the correct values as reported by the hardware.
200
201When a CEC message was received:
202
203void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg);
204
205Speaks for itself.
206
207Implementing the High-Level CEC Adapter
208---------------------------------------
209
210The low-level operations drive the hardware, the high-level operations are
211CEC protocol driven. The following high-level callbacks are available:
212
213struct cec_adap_ops {
214 /* Low-level callbacks */
215 ...
216
217 /* High-level CEC message callback */
218 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
219};
220
221The received() callback allows the driver to optionally handle a newly
222received CEC message
223
224 int (*received)(struct cec_adapter *adap, struct cec_msg *msg);
225
226If the driver wants to process a CEC message, then it can implement this
227callback. If it doesn't want to handle this message, then it should return
228-ENOMSG, otherwise the CEC framework assumes it processed this message and
229it will not no anything with it.
230
231
232CEC framework functions
233-----------------------
234
235CEC Adapter drivers can call the following CEC framework functions:
236
237int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg,
238 bool block);
239
240Transmit a CEC message. If block is true, then wait until the message has been
241transmitted, otherwise just queue it and return.
242
243void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block);
244
245Change the physical address. This function will set adap->phys_addr and
246send an event if it has changed. If cec_s_log_addrs() has been called and
247the physical address has become valid, then the CEC framework will start
248claiming the logical addresses. If block is true, then this function won't
249return until this process has finished.
250
251When the physical address is set to a valid value the CEC adapter will
252be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID,
253then the CEC adapter will be disabled. If you change a valid physical address
254to another valid physical address, then this function will first set the
255address to CEC_PHYS_ADDR_INVALID before enabling the new physical address.
256
257int cec_s_log_addrs(struct cec_adapter *adap,
258 struct cec_log_addrs *log_addrs, bool block);
259
260Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS
261is set. If block is true, then wait until the logical addresses have been
262claimed, otherwise just queue it and return. To unconfigure all logical
263addresses call this function with log_addrs set to NULL or with
264log_addrs->num_log_addrs set to 0. The block argument is ignored when
265unconfiguring. This function will just return if the physical address is
266invalid. Once the physical address becomes valid, then the framework will
267attempt to claim these logical addresses.
diff --git a/Documentation/devicetree/bindings/media/mediatek-vcodec.txt b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt
new file mode 100644
index 000000000000..59a47a5b924b
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt
@@ -0,0 +1,59 @@
1Mediatek Video Codec
2
3Mediatek Video Codec is the video codec hw present in Mediatek SoCs which
4supports high resolution encoding functionalities.
5
6Required properties:
7- compatible : "mediatek,mt8173-vcodec-enc" for encoder
8- reg : Physical base address of the video codec registers and length of
9 memory mapped region.
10- interrupts : interrupt number to the cpu.
11- mediatek,larb : must contain the local arbiters in the current Socs.
12- clocks : list of clock specifiers, corresponding to entries in
13 the clock-names property.
14- clock-names: encoder must contain "venc_sel_src", "venc_sel",
15- "venc_lt_sel_src", "venc_lt_sel".
16- iommus : should point to the respective IOMMU block with master port as
17 argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt
18 for details.
19- mediatek,vpu : the node of video processor unit
20
21Example:
22vcodec_enc: vcodec@0x18002000 {
23 compatible = "mediatek,mt8173-vcodec-enc";
24 reg = <0 0x18002000 0 0x1000>, /*VENC_SYS*/
25 <0 0x19002000 0 0x1000>; /*VENC_LT_SYS*/
26 interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>,
27 <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>;
28 mediatek,larb = <&larb3>,
29 <&larb5>;
30 iommus = <&iommu M4U_PORT_VENC_RCPU>,
31 <&iommu M4U_PORT_VENC_REC>,
32 <&iommu M4U_PORT_VENC_BSDMA>,
33 <&iommu M4U_PORT_VENC_SV_COMV>,
34 <&iommu M4U_PORT_VENC_RD_COMV>,
35 <&iommu M4U_PORT_VENC_CUR_LUMA>,
36 <&iommu M4U_PORT_VENC_CUR_CHROMA>,
37 <&iommu M4U_PORT_VENC_REF_LUMA>,
38 <&iommu M4U_PORT_VENC_REF_CHROMA>,
39 <&iommu M4U_PORT_VENC_NBM_RDMA>,
40 <&iommu M4U_PORT_VENC_NBM_WDMA>,
41 <&iommu M4U_PORT_VENC_RCPU_SET2>,
42 <&iommu M4U_PORT_VENC_REC_FRM_SET2>,
43 <&iommu M4U_PORT_VENC_BSDMA_SET2>,
44 <&iommu M4U_PORT_VENC_SV_COMA_SET2>,
45 <&iommu M4U_PORT_VENC_RD_COMA_SET2>,
46 <&iommu M4U_PORT_VENC_CUR_LUMA_SET2>,
47 <&iommu M4U_PORT_VENC_CUR_CHROMA_SET2>,
48 <&iommu M4U_PORT_VENC_REF_LUMA_SET2>,
49 <&iommu M4U_PORT_VENC_REC_CHROMA_SET2>;
50 mediatek,vpu = <&vpu>;
51 clocks = <&topckgen CLK_TOP_VENCPLL_D2>,
52 <&topckgen CLK_TOP_VENC_SEL>,
53 <&topckgen CLK_TOP_UNIVPLL1_D2>,
54 <&topckgen CLK_TOP_VENC_LT_SEL>;
55 clock-names = "venc_sel_src",
56 "venc_sel",
57 "venc_lt_sel_src",
58 "venc_lt_sel";
59 };
diff --git a/Documentation/devicetree/bindings/media/mediatek-vpu.txt b/Documentation/devicetree/bindings/media/mediatek-vpu.txt
new file mode 100644
index 000000000000..2a5bac37f9a2
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/mediatek-vpu.txt
@@ -0,0 +1,31 @@
1* Mediatek Video Processor Unit
2
3Video Processor Unit is a HW video controller. It controls HW Codec including
4H.264/VP8/VP9 Decode, H.264/VP8 Encode and Image Processor (scale/rotate/color convert).
5
6Required properties:
7 - compatible: "mediatek,mt8173-vpu"
8 - reg: Must contain an entry for each entry in reg-names.
9 - reg-names: Must include the following entries:
10 "tcm": tcm base
11 "cfg_reg": Main configuration registers base
12 - interrupts: interrupt number to the cpu.
13 - clocks : clock name from clock manager
14 - clock-names: must be main. It is the main clock of VPU
15
16Optional properties:
17 - memory-region: phandle to a node describing memory (see
18 Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt)
19 to be used for VPU extended memory; if not present, VPU may be located
20 anywhere in the memory
21
22Example:
23 vpu: vpu@10020000 {
24 compatible = "mediatek,mt8173-vpu";
25 reg = <0 0x10020000 0 0x30000>,
26 <0 0x10050000 0 0x100>;
27 reg-names = "tcm", "cfg_reg";
28 interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>;
29 clocks = <&topckgen TOP_SCP_SEL>;
30 clock-names = "main";
31 };
diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.txt b/Documentation/devicetree/bindings/media/renesas,fcp.txt
new file mode 100644
index 000000000000..6a12960609d8
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/renesas,fcp.txt
@@ -0,0 +1,32 @@
1Renesas R-Car Frame Compression Processor (FCP)
2-----------------------------------------------
3
4The FCP is a companion module of video processing modules in the Renesas R-Car
5Gen3 SoCs. It provides data compression and decompression, data caching, and
6conversion of AXI transactions in order to reduce the memory bandwidth.
7
8There are three types of FCP: FCP for Codec (FCPC), FCP for VSP (FCPV) and FCP
9for FDP (FCPF). Their configuration and behaviour depend on the module they
10are paired with. These DT bindings currently support the FCPV only.
11
12 - compatible: Must be one or more of the following
13
14 - "renesas,r8a7795-fcpv" for R8A7795 (R-Car H3) compatible 'FCP for VSP'
15 - "renesas,fcpv" for generic compatible 'FCP for VSP'
16
17 When compatible with the generic version, nodes must list the
18 SoC-specific version corresponding to the platform first, followed by the
19 family-specific and/or generic versions.
20
21 - reg: the register base and size for the device registers
22 - clocks: Reference to the functional clock
23
24
25Device node example
26-------------------
27
28 fcpvd1: fcp@fea2f000 {
29 compatible = "renesas,r8a7795-fcpv", "renesas,fcpv";
30 reg = <0 0xfea2f000 0 0x200>;
31 clocks = <&cpg CPG_MOD 602>;
32 };
diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.txt b/Documentation/devicetree/bindings/media/renesas,vsp1.txt
index 627405abd144..9b695bcbf219 100644
--- a/Documentation/devicetree/bindings/media/renesas,vsp1.txt
+++ b/Documentation/devicetree/bindings/media/renesas,vsp1.txt
@@ -14,6 +14,11 @@ Required properties:
14 - interrupts: VSP interrupt specifier. 14 - interrupts: VSP interrupt specifier.
15 - clocks: A phandle + clock-specifier pair for the VSP functional clock. 15 - clocks: A phandle + clock-specifier pair for the VSP functional clock.
16 16
17Optional properties:
18
19 - renesas,fcp: A phandle referencing the FCP that handles memory accesses
20 for the VSP. Not needed on Gen2, mandatory on Gen3.
21
17 22
18Example: R8A7790 (R-Car H2) VSP1-S node 23Example: R8A7790 (R-Car H2) VSP1-S node
19 24
diff --git a/Documentation/devicetree/bindings/media/s5p-cec.txt b/Documentation/devicetree/bindings/media/s5p-cec.txt
new file mode 100644
index 000000000000..925ab4d72eaa
--- /dev/null
+++ b/Documentation/devicetree/bindings/media/s5p-cec.txt
@@ -0,0 +1,31 @@
1* Samsung HDMI CEC driver
2
3The HDMI CEC module is present is Samsung SoCs and its purpose is to
4handle communication between HDMI connected devices over the CEC bus.
5
6Required properties:
7 - compatible : value should be following
8 "samsung,s5p-cec"
9
10 - reg : Physical base address of the IP registers and length of memory
11 mapped region.
12
13 - interrupts : HDMI CEC interrupt number to the CPU.
14 - clocks : from common clock binding: handle to HDMI CEC clock.
15 - clock-names : from common clock binding: must contain "hdmicec",
16 corresponding to entry in the clocks property.
17 - samsung,syscon-phandle - phandle to the PMU system controller
18
19Example:
20
21hdmicec: cec@100B0000 {
22 compatible = "samsung,s5p-cec";
23 reg = <0x100B0000 0x200>;
24 interrupts = <0 114 0>;
25 clocks = <&clock CLK_HDMI_CEC>;
26 clock-names = "hdmicec";
27 samsung,syscon-phandle = <&pmu_system_controller>;
28 pinctrl-names = "default";
29 pinctrl-0 = <&hdmi_cec>;
30 status = "okay";
31};
diff --git a/Documentation/devicetree/bindings/media/s5p-mfc.txt b/Documentation/devicetree/bindings/media/s5p-mfc.txt
index 2d5787eac91a..92c94f5ecbf1 100644
--- a/Documentation/devicetree/bindings/media/s5p-mfc.txt
+++ b/Documentation/devicetree/bindings/media/s5p-mfc.txt
@@ -21,15 +21,18 @@ Required properties:
21 - clock-names : from common clock binding: must contain "mfc", 21 - clock-names : from common clock binding: must contain "mfc",
22 corresponding to entry in the clocks property. 22 corresponding to entry in the clocks property.
23 23
24 - samsung,mfc-r : Base address of the first memory bank used by MFC
25 for DMA contiguous memory allocation and its size.
26
27 - samsung,mfc-l : Base address of the second memory bank used by MFC
28 for DMA contiguous memory allocation and its size.
29
30Optional properties: 24Optional properties:
31 - power-domains : power-domain property defined with a phandle 25 - power-domains : power-domain property defined with a phandle
32 to respective power domain. 26 to respective power domain.
27 - memory-region : from reserved memory binding: phandles to two reserved
28 memory regions, first is for "left" mfc memory bus interfaces,
29 second if for the "right" mfc memory bus, used when no SYSMMU
30 support is available
31
32Obsolete properties:
33 - samsung,mfc-r, samsung,mfc-l : support removed, please use memory-region
34 property instead
35
33 36
34Example: 37Example:
35SoC specific DT entry: 38SoC specific DT entry:
@@ -43,9 +46,29 @@ mfc: codec@13400000 {
43 clock-names = "mfc"; 46 clock-names = "mfc";
44}; 47};
45 48
49Reserved memory specific DT entry for given board (see reserved memory binding
50for more information):
51
52reserved-memory {
53 #address-cells = <1>;
54 #size-cells = <1>;
55 ranges;
56
57 mfc_left: region@51000000 {
58 compatible = "shared-dma-pool";
59 no-map;
60 reg = <0x51000000 0x800000>;
61 };
62
63 mfc_right: region@43000000 {
64 compatible = "shared-dma-pool";
65 no-map;
66 reg = <0x43000000 0x800000>;
67 };
68};
69
46Board specific DT entry: 70Board specific DT entry:
47 71
48codec@13400000 { 72codec@13400000 {
49 samsung,mfc-r = <0x43000000 0x800000>; 73 memory-region = <&mfc_left>, <&mfc_right>;
50 samsung,mfc-l = <0x51000000 0x800000>;
51}; 74};
diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885
index 85a8fdcfcdaa..c9b4959fd04e 100644
--- a/Documentation/video4linux/CARDLIST.cx23885
+++ b/Documentation/video4linux/CARDLIST.cx23885
@@ -54,3 +54,4 @@
54 53 -> Hauppauge WinTV Starburst [0070:c12a] 54 53 -> Hauppauge WinTV Starburst [0070:c12a]
55 54 -> ViewCast 260e [1576:0260] 55 54 -> ViewCast 260e [1576:0260]
56 55 -> ViewCast 460e [1576:0460] 56 55 -> ViewCast 460e [1576:0460]
57 56 -> Hauppauge WinTV-quadHD (DVB) [0070:6a28,0070:6b28]
diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt
index 5e759cab4538..f930b80e9111 100644
--- a/Documentation/video4linux/v4l2-controls.txt
+++ b/Documentation/video4linux/v4l2-controls.txt
@@ -96,21 +96,6 @@ Basic usage for V4L2 and sub-device drivers
96 96
97 Where foo->sd is of type struct v4l2_subdev. 97 Where foo->sd is of type struct v4l2_subdev.
98 98
99 And set all core control ops in your struct v4l2_subdev_core_ops to these
100 helpers:
101
102 .queryctrl = v4l2_subdev_queryctrl,
103 .querymenu = v4l2_subdev_querymenu,
104 .g_ctrl = v4l2_subdev_g_ctrl,
105 .s_ctrl = v4l2_subdev_s_ctrl,
106 .g_ext_ctrls = v4l2_subdev_g_ext_ctrls,
107 .try_ext_ctrls = v4l2_subdev_try_ext_ctrls,
108 .s_ext_ctrls = v4l2_subdev_s_ext_ctrls,
109
110 Note: this is a temporary solution only. Once all V4L2 drivers that depend
111 on subdev drivers are converted to the control framework these helpers will
112 no longer be needed.
113
1141.4) Clean up the handler at the end: 991.4) Clean up the handler at the end:
115 100
116 v4l2_ctrl_handler_free(&foo->ctrl_handler); 101 v4l2_ctrl_handler_free(&foo->ctrl_handler);
diff --git a/Documentation/video4linux/vivid.txt b/Documentation/video4linux/vivid.txt
index 8da5d2a576bc..1b26519c6ddc 100644
--- a/Documentation/video4linux/vivid.txt
+++ b/Documentation/video4linux/vivid.txt
@@ -74,7 +74,8 @@ Section 11: Cropping, Composing, Scaling
74Section 12: Formats 74Section 12: Formats
75Section 13: Capture Overlay 75Section 13: Capture Overlay
76Section 14: Output Overlay 76Section 14: Output Overlay
77Section 15: Some Future Improvements 77Section 15: CEC (Consumer Electronics Control)
78Section 16: Some Future Improvements
78 79
79 80
80Section 1: Configuring the driver 81Section 1: Configuring the driver
@@ -364,7 +365,11 @@ For HDMI inputs it is possible to set the EDID. By default a simple EDID
364is provided. You can only set the EDID for HDMI inputs. Internally, however, 365is provided. You can only set the EDID for HDMI inputs. Internally, however,
365the EDID is shared between all HDMI inputs. 366the EDID is shared between all HDMI inputs.
366 367
367No interpretation is done of the EDID data. 368No interpretation is done of the EDID data with the exception of the
369physical address. See the CEC section for more details.
370
371There is a maximum of 15 HDMI inputs (if there are more, then they will be
372reduced to 15) since that's the limitation of the EDID physical address.
368 373
369 374
370Section 3: Video Output 375Section 3: Video Output
@@ -409,6 +414,9 @@ standard, and for all others a 1:1 pixel aspect ratio is returned.
409 414
410An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID. 415An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID.
411 416
417There is a maximum of 15 HDMI outputs (if there are more, then they will be
418reduced to 15) since that's the limitation of the EDID physical address. See
419also the CEC section for more details.
412 420
413Section 4: VBI Capture 421Section 4: VBI Capture
414---------------------- 422----------------------
@@ -1108,7 +1116,26 @@ capabilities will slow down the video loop considerably as a lot of checks have
1108to be done per pixel. 1116to be done per pixel.
1109 1117
1110 1118
1111Section 15: Some Future Improvements 1119Section 15: CEC (Consumer Electronics Control)
1120----------------------------------------------
1121
1122If there are HDMI inputs then a CEC adapter will be created that has
1123the same number of input ports. This is the equivalent of e.g. a TV that
1124has that number of inputs. Each HDMI output will also create a
1125CEC adapter that is hooked up to the corresponding input port, or (if there
1126are more outputs than inputs) is not hooked up at all. In other words,
1127this is the equivalent of hooking up each output device to an input port of
1128the TV. Any remaining output devices remain unconnected.
1129
1130The EDID that each output reads reports a unique CEC physical address that is
1131based on the physical address of the EDID of the input. So if the EDID of the
1132receiver has physical address A.B.0.0, then each output will see an EDID
1133containing physical address A.B.C.0 where C is 1 to the number of inputs. If
1134there are more outputs than inputs then the remaining outputs have a CEC adapter
1135that is disabled and reports an invalid physical address.
1136
1137
1138Section 16: Some Future Improvements
1112------------------------------------ 1139------------------------------------
1113 1140
1114Just as a reminder and in no particular order: 1141Just as a reminder and in no particular order:
@@ -1121,8 +1148,6 @@ Just as a reminder and in no particular order:
1121- Fix sequence/field numbering when looping of video with alternate fields 1148- Fix sequence/field numbering when looping of video with alternate fields
1122- Add support for V4L2_CID_BG_COLOR for video outputs 1149- Add support for V4L2_CID_BG_COLOR for video outputs
1123- Add ARGB888 overlay support: better testing of the alpha channel 1150- Add ARGB888 overlay support: better testing of the alpha channel
1124- Add custom DV timings support
1125- Add support for V4L2_DV_FL_REDUCED_FPS
1126- Improve pixel aspect support in the tpg code by passing a real v4l2_fract 1151- Improve pixel aspect support in the tpg code by passing a real v4l2_fract
1127- Use per-queue locks and/or per-device locks to improve throughput 1152- Use per-queue locks and/or per-device locks to improve throughput
1128- Add support to loop from a specific output to a specific input across 1153- Add support to loop from a specific output to a specific input across
@@ -1133,3 +1158,4 @@ Just as a reminder and in no particular order:
1133- Make a thread for the RDS generation, that would help in particular for the 1158- Make a thread for the RDS generation, that would help in particular for the
1134 "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated 1159 "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated
1135 in real-time. 1160 in real-time.
1161- Changing the EDID should cause hotplug detect emulation to happen.
generated by cgit v1.2.2 (git 2.25.0) at 2025-09-06 10:29:55 -0400