diff options
| author | Linus Torvalds <torvalds@linux-foundation.org> | 2016-07-26 18:59:59 -0700 |
|---|---|---|
| committer | Linus Torvalds <torvalds@linux-foundation.org> | 2016-07-26 18:59:59 -0700 |
| commit | 9c1958fc326a0a0a533ec8e86ea6fa30977207de (patch) | |
| tree | 9d76e6a146c2622fad0eefbb8ff0503caefe33cc /Documentation | |
| parent | 1b3fc0bef8859268d542230172f80e85553fdab4 (diff) | |
| parent | 009a620848218d521f008141c62f56bf19294dd9 (diff) | |
| download | op-kernel-dev-9c1958fc326a0a0a533ec8e86ea6fa30977207de.zip op-kernel-dev-9c1958fc326a0a0a533ec8e86ea6fa30977207de.tar.gz | |
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')
30 files changed, 2289 insertions, 34 deletions
diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index 8c68768..58af32b 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -300,6 +300,9 @@ X!Isound/sound_firmware.c !Iinclude/media/media-devnode.h !Iinclude/media/media-entity.h </sect1> + <sect1><title>Consumer Electronics Control devices</title> +!Iinclude/media/cec-edid.h + </sect1> </chapter> diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 2840ff4..fdc1386 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -64,6 +64,7 @@ IOCTLS = \ $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/net.h) \ $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/video.h) \ $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/cec.h) \ $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ DEFINES = \ @@ -100,6 +101,7 @@ STRUCTS = \ $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/ && !/_old/)' $(srctree)/include/uapi/linux/dvb/net.h) \ $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/cec.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 9beb30f..87f1d24 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> <subtitle>Specification Version 1.4a</subtitle> </biblioentry> + <biblioentry id="hdmi2"> + <abbrev>HDMI2</abbrev> + <authorgroup> + <corpauthor>HDMI Licensing LLC +(<ulink url="http://www.hdmi.org">http://www.hdmi.org</ulink>)</corpauthor> + </authorgroup> + <title>High-Definition Multimedia Interface</title> + <subtitle>Specification Version 2.0</subtitle> + </biblioentry> + <biblioentry id="dp"> <abbrev>DP</abbrev> <authorgroup> diff --git a/Documentation/DocBook/media/v4l/cec-api.xml b/Documentation/DocBook/media/v4l/cec-api.xml new file mode 100644 index 0000000..7062c1f --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-api.xml @@ -0,0 +1,75 @@ +<partinfo> + <authorgroup> + <author> + <firstname>Hans</firstname> + <surname>Verkuil</surname> + <affiliation><address><email>hans.verkuil@cisco.com</email></address></affiliation> + <contrib>Initial version.</contrib> + </author> + </authorgroup> + <copyright> + <year>2016</year> + <holder>Hans Verkuil</holder> + </copyright> + + <revhistory> + <!-- Put document revisions here, newest first. --> + <revision> + <revnumber>1.0.0</revnumber> + <date>2016-03-17</date> + <authorinitials>hv</authorinitials> + <revremark>Initial revision</revremark> + </revision> + </revhistory> +</partinfo> + +<title>CEC API</title> + +<chapter id="cec-api"> + <title>CEC: Consumer Electronics Control</title> + + <section id="cec-intro"> + <title>Introduction</title> + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + <para>HDMI connectors provide a single pin for use by the Consumer Electronics + Control protocol. This protocol allows different devices connected by an HDMI cable + to communicate. The protocol for CEC version 1.4 is defined in supplements 1 (CEC) + and 2 (HEAC or HDMI Ethernet and Audio Return Channel) of the HDMI 1.4a + (<xref linkend="hdmi" />) specification and the extensions added to CEC version 2.0 + are defined in chapter 11 of the HDMI 2.0 (<xref linkend="hdmi2" />) specification. + </para> + + <para>The bitrate is very slow (effectively no more than 36 bytes per second) and + is based on the ancient AV.link protocol used in old SCART connectors. The protocol + closely resembles a crazy Rube Goldberg contraption and is an unholy mix of low and + high level messages. Some messages, especially those part of the HEAC protocol layered + on top of CEC, need to be handled by the kernel, others can be handled either by the + kernel or by userspace.</para> + + <para>In addition, CEC can be implemented in HDMI receivers, transmitters and in USB + devices that have an HDMI input and an HDMI output and that control just the CEC pin.</para> + + <para>Drivers that support CEC will create a CEC device node (/dev/cecX) + to give userspace access to the CEC adapter. The &CEC-ADAP-G-CAPS; ioctl will tell userspace + what it is allowed to do.</para> + </section> +</chapter> + +<appendix id="cec-user-func"> + <title>Function Reference</title> + <!-- Keep this alphabetically sorted. --> + &sub-cec-func-open; + &sub-cec-func-close; + &sub-cec-func-ioctl; + &sub-cec-func-poll; + <!-- All ioctls go here. --> + &sub-cec-ioc-adap-g-caps; + &sub-cec-ioc-adap-g-log-addrs; + &sub-cec-ioc-adap-g-phys-addr; + &sub-cec-ioc-dqevent; + &sub-cec-ioc-g-mode; + &sub-cec-ioc-receive; +</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 0000000..0812c8c --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-close.xml @@ -0,0 +1,64 @@ +<refentry id="cec-func-close"> + <refmeta> + <refentrytitle>cec close()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>cec-close</refname> + <refpurpose>Close a cec device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <unistd.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>close</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>Closes the cec device. Resources associated with the file descriptor + are freed. The device configuration remain unchanged.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para><function>close</function> returns 0 on success. On error, -1 is + returned, and <varname>errno</varname> is set appropriately. Possible error + codes are:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para><parameter>fd</parameter> is not a valid open file descriptor. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</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 0000000..f92817a --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-ioctl.xml @@ -0,0 +1,78 @@ +<refentry id="cec-func-ioctl"> + <refmeta> + <refentrytitle>cec ioctl()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>cec-ioctl</refname> + <refpurpose>Control a cec device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <sys/ioctl.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>void *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC ioctl request code as defined in the cec.h header file, + for example CEC_ADAP_G_CAPS.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para>Pointer to a request-specific structure.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>The <function>ioctl()</function> function manipulates cec device + parameters. The argument <parameter>fd</parameter> must be an open file + descriptor.</para> + <para>The ioctl <parameter>request</parameter> code specifies the cec + function to be called. It has encoded in it whether the argument is an + input, output or read/write parameter, and the size of the argument + <parameter>argp</parameter> in bytes.</para> + <para>Macros and structures definitions specifying cec ioctl requests and + their parameters are located in the cec.h header file. All cec ioctl + requests, their respective function and parameters are specified in + <xref linkend="cec-user-func" />.</para> + </refsect1> + + <refsect1> + &return-value; + + <para>Request-specific error codes are listed in the + individual requests descriptions.</para> + <para>When an ioctl that takes an output or read/write parameter fails, + the parameter remains unmodified.</para> + </refsect1> +</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 0000000..2edc555 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-open.xml @@ -0,0 +1,104 @@ +<refentry id="cec-func-open"> + <refmeta> + <refentrytitle>cec open()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>cec-open</refname> + <refpurpose>Open a cec device</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <fcntl.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>open</function></funcdef> + <paramdef>const char *<parameter>device_name</parameter></paramdef> + <paramdef>int <parameter>flags</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>device_name</parameter></term> + <listitem> + <para>Device to be opened.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter></term> + <listitem> + <para>Open flags. Access mode must be <constant>O_RDWR</constant>. + </para> + <para>When the <constant>O_NONBLOCK</constant> flag is +given, the &CEC-RECEIVE; ioctl will return &EAGAIN; when no message is +available, and the &CEC-TRANSMIT;, &CEC-ADAP-S-PHYS-ADDR; and +&CEC-ADAP-S-LOG-ADDRS; ioctls all act in non-blocking mode.</para> + <para>Other flags have no effect.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>Description</title> + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>To open a cec device applications call <function>open()</function> + with the desired device name. The function has no side effects; the device + configuration remain unchanged.</para> + <para>When the device is opened in read-only mode, attempts to modify its + configuration will result in an error, and <varname>errno</varname> will be + set to <errorcode>EBADF</errorcode>.</para> + </refsect1> + <refsect1> + <title>Return Value</title> + + <para><function>open</function> returns the new file descriptor on success. + On error, -1 is returned, and <varname>errno</varname> is set appropriately. + Possible error codes include:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EACCES</errorcode></term> + <listitem> + <para>The requested access to the file is not allowed.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EMFILE</errorcode></term> + <listitem> + <para>The process already has the maximum number of files open. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENFILE</errorcode></term> + <listitem> + <para>The system limit on the total number of open files has been + reached.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENOMEM</errorcode></term> + <listitem> + <para>Insufficient kernel memory was available.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>ENXIO</errorcode></term> + <listitem> + <para>No device corresponding to this device special file exists. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</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 0000000..1bddbde --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-func-poll.xml @@ -0,0 +1,94 @@ +<refentry id="cec-func-poll"> + <refmeta> + <refentrytitle>cec poll()</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>cec-poll</refname> + <refpurpose>Wait for some event on a file descriptor</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcsynopsisinfo>#include <sys/poll.h></funcsynopsisinfo> + <funcprototype> + <funcdef>int <function>poll</function></funcdef> + <paramdef>struct pollfd *<parameter>ufds</parameter></paramdef> + <paramdef>unsigned int <parameter>nfds</parameter></paramdef> + <paramdef>int <parameter>timeout</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>With the <function>poll()</function> function applications +can wait for CEC events.</para> + + <para>On success <function>poll()</function> returns the number of +file descriptors that have been selected (that is, file descriptors +for which the <structfield>revents</structfield> field of the +respective <structname>pollfd</structname> structure is non-zero). +CEC devices set the <constant>POLLIN</constant> and +<constant>POLLRDNORM</constant> flags in the +<structfield>revents</structfield> field if there are messages in the +receive queue. If the transmit queue has room for new messages, the +<constant>POLLOUT</constant> and <constant>POLLWRNORM</constant> +flags are set. If there are events in the event queue, then the +<constant>POLLPRI</constant> flag is set. +When the function timed out it returns a value of zero, on +failure it returns <returnvalue>-1</returnvalue> and the +<varname>errno</varname> variable is set appropriately. +</para> + + <para>For more details see the +<function>poll()</function> manual page.</para> + </refsect1> + + <refsect1> + <title>Return Value</title> + + <para>On success, <function>poll()</function> returns the number +structures which have non-zero <structfield>revents</structfield> +fields, or zero if the call timed out. On error +<returnvalue>-1</returnvalue> is returned, and the +<varname>errno</varname> variable is set appropriately:</para> + + <variablelist> + <varlistentry> + <term><errorcode>EBADF</errorcode></term> + <listitem> + <para>One or more of the <parameter>ufds</parameter> members +specify an invalid file descriptor.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EFAULT</errorcode></term> + <listitem> + <para><parameter>ufds</parameter> references an inaccessible +memory area.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINTR</errorcode></term> + <listitem> + <para>The call was interrupted by a signal.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>EINVAL</errorcode></term> + <listitem> + <para>The <parameter>nfds</parameter> argument is greater +than <constant>OPEN_MAX</constant>.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</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 0000000..3523ef2 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-caps.xml @@ -0,0 +1,151 @@ +<refentry id="cec-ioc-adap-g-caps"> + <refmeta> + <refentrytitle>ioctl CEC_ADAP_G_CAPS</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_ADAP_G_CAPS</refname> + <refpurpose>Query device capabilities</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct cec_caps *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_ADAP_G_CAPS</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>All cec devices must support the <constant>CEC_ADAP_G_CAPS</constant> + ioctl. To query device information, applications call the ioctl with a + pointer to a &cec-caps;. The driver fills the structure and returns + the information to the application. + The ioctl never fails.</para> + + <table pgwide="1" frame="none" id="cec-caps"> + <title>struct <structname>cec_caps</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>char</entry> + <entry><structfield>driver[32]</structfield></entry> + <entry>The name of the cec adapter driver.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>name[32]</structfield></entry> + <entry>The name of this CEC adapter. The combination <structfield>driver</structfield> + and <structfield>name</structfield> must be unique.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>capabilities</structfield></entry> + <entry>The capabilities of the CEC adapter, see <xref + linkend="cec-capabilities" />.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>version</structfield></entry> + <entry>CEC Framework API version, formatted with the + <constant>KERNEL_VERSION()</constant> macro.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-capabilities"> + <title>CEC Capabilities Flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_CAP_PHYS_ADDR</constant></entry> + <entry>0x00000001</entry> + <entry>Userspace has to configure the physical address by + calling &CEC-ADAP-S-PHYS-ADDR;. If this capability isn't set, + then setting the physical address is handled by the kernel + whenever the EDID is set (for an HDMI receiver) or read (for + an HDMI transmitter).</entry> + </row> + <row> + <entry><constant>CEC_CAP_LOG_ADDRS</constant></entry> + <entry>0x00000002</entry> + <entry>Userspace has to configure the logical addresses by + calling &CEC-ADAP-S-LOG-ADDRS;. If this capability isn't set, + then the kernel will have configured this.</entry> + </row> + <row> + <entry><constant>CEC_CAP_TRANSMIT</constant></entry> + <entry>0x00000004</entry> + <entry>Userspace can transmit CEC messages by calling &CEC-TRANSMIT;. This + implies that userspace can be a follower as well, since being able to + transmit messages is a prerequisite of becoming a follower. If this + capability isn't set, then the kernel will handle all CEC transmits + and process all CEC messages it receives. + </entry> + </row> + <row> + <entry><constant>CEC_CAP_PASSTHROUGH</constant></entry> + <entry>0x00000008</entry> + <entry>Userspace can use the passthrough mode by + calling &CEC-S-MODE;.</entry> + </row> + <row> + <entry><constant>CEC_CAP_RC</constant></entry> + <entry>0x00000010</entry> + <entry>This adapter supports the remote control protocol.</entry> + </row> + <row> + <entry><constant>CEC_CAP_MONITOR_ALL</constant></entry> + <entry>0x00000020</entry> + <entry>The CEC hardware can monitor all messages, not just directed and + broadcast messages.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</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 0000000..302b829 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml @@ -0,0 +1,329 @@ +<refentry id="cec-ioc-adap-g-log-addrs"> + <refmeta> + <refentrytitle>ioctl CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_ADAP_G_LOG_ADDRS</refname> + <refname>CEC_ADAP_S_LOG_ADDRS</refname> + <refpurpose>Get or set the logical addresses</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct cec_log_addrs *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>To query the current CEC logical addresses, applications call the +<constant>CEC_ADAP_G_LOG_ADDRS</constant> ioctl with a pointer to a +<structname>cec_log_addrs</structname> structure where the drivers stores the +logical addresses.</para> + + <para>To set new logical addresses, applications fill in struct <structname>cec_log_addrs</structname> +and call the <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl with a pointer to this struct. +The <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl is only available if +<constant>CEC_CAP_LOG_ADDRS</constant> is set (&ENOTTY; is returned otherwise). This ioctl will block until all +requested logical addresses have been claimed. <constant>CEC_ADAP_S_LOG_ADDRS</constant> +can only be called by a file handle in initiator mode (see &CEC-S-MODE;).</para> + + <table pgwide="1" frame="none" id="cec-log-addrs"> + <title>struct <structname>cec_log_addrs</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u8</entry> + <entry><structfield>log_addr</structfield>[CEC_MAX_LOG_ADDRS]</entry> + <entry>The actual logical addresses that were claimed. This is set by the + driver. If no logical address could be claimed, then it is set to + <constant>CEC_LOG_ADDR_INVALID</constant>. If this adapter is Unregistered, + then <structfield>log_addr[0]</structfield> is set to 0xf and all others to + <constant>CEC_LOG_ADDR_INVALID</constant>.</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>log_addr_mask</structfield></entry> + <entry>The bitmask of all logical addresses this adapter has claimed. + If this adapter is Unregistered then <structfield>log_addr_mask</structfield> + sets bit 15 and clears all other bits. If this adapter is not configured at all, then + <structfield>log_addr_mask</structfield> is set to 0. Set by the driver.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>cec_version</structfield></entry> + <entry>The CEC version that this adapter shall use. See + <xref linkend="cec-versions" />. + Used to implement the <constant>CEC_MSG_CEC_VERSION</constant> and + <constant>CEC_MSG_REPORT_FEATURES</constant> messages. Note that + <constant>CEC_OP_CEC_VERSION_1_3A</constant> is not allowed + by the CEC framework. + </entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>num_log_addrs</structfield></entry> + <entry>Number of logical addresses to set up. Must be ≤ + <structfield>available_log_addrs</structfield> as returned by + &CEC-ADAP-G-CAPS;. All arrays in this structure are only filled up to + index <structfield>available_log_addrs</structfield>-1. The remaining + array elements will be ignored. Note that the CEC 2.0 standard allows + for a maximum of 2 logical addresses, although some hardware has support + for more. <constant>CEC_MAX_LOG_ADDRS</constant> is 4. The driver will + return the actual number of logical addresses it could claim, which may + be less than what was requested. If this field is set to 0, then the + CEC adapter shall clear all claimed logical addresses and all other + fields will be ignored.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>vendor_id</structfield></entry> + <entry>The vendor ID is a 24-bit number that identifies the specific + vendor or entity. Based on this ID vendor specific commands may be + defined. If you do not want a vendor ID then set it to + <constant>CEC_VENDOR_ID_NONE</constant>.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Flags. No flags are defined yet, so set this to 0.</entry> + </row> + <row> + <entry>char</entry> + <entry><structfield>osd_name</structfield>[15]</entry> + <entry>The On-Screen Display name as is returned by the + <constant>CEC_MSG_SET_OSD_NAME</constant> message.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>primary_device_type</structfield>[CEC_MAX_LOG_ADDRS]</entry> + <entry>Primary device type for each logical address. See + <xref linkend="cec-prim-dev-types" /> for possible types.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>log_addr_type</structfield>[CEC_MAX_LOG_ADDRS]</entry> + <entry>Logical address types. See <xref linkend="cec-log-addr-types" /> for + possible types. The driver will update this with the actual logical address + type that it claimed (e.g. it may have to fallback to + <constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant>).</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>all_device_types</structfield>[CEC_MAX_LOG_ADDRS]</entry> + <entry>CEC 2.0 specific: all device types. See <xref linkend="cec-all-dev-types-flags" />. + Used to implement the <constant>CEC_MSG_REPORT_FEATURES</constant> message. + This field is ignored if <structfield>cec_version</structfield> < + <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>features</structfield>[CEC_MAX_LOG_ADDRS][12]</entry> + <entry>Features for each logical address. Used to implement the + <constant>CEC_MSG_REPORT_FEATURES</constant> message. The 12 bytes include + both the RC Profile and the Device Features. + This field is ignored if <structfield>cec_version</structfield> < + <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-versions"> + <title>CEC Versions</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_OP_CEC_VERSION_1_3A</constant></entry> + <entry>4</entry> + <entry>CEC version according to the HDMI 1.3a standard.</entry> + </row> + <row> + <entry><constant>CEC_OP_CEC_VERSION_1_4B</constant></entry> + <entry>5</entry> + <entry>CEC version according to the HDMI 1.4b standard.</entry> + </row> + <row> + <entry><constant>CEC_OP_CEC_VERSION_2_0</constant></entry> + <entry>6</entry> + <entry>CEC version according to the HDMI 2.0 standard.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-prim-dev-types"> + <title>CEC Primary Device Types</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_TV</constant></entry> + <entry>0</entry> + <entry>Use for a TV.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_RECORD</constant></entry> + <entry>1</entry> + <entry>Use for a recording device.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_TUNER</constant></entry> + <entry>3</entry> + <entry>Use for a device with a tuner.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_PLAYBACK</constant></entry> + <entry>4</entry> + <entry>Use for a playback device.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM</constant></entry> + <entry>5</entry> + <entry>Use for an audio system (e.g. an audio/video receiver).</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_SWITCH</constant></entry> + <entry>6</entry> + <entry>Use for a CEC switch.</entry> + </row> + <row> + <entry><constant>CEC_OP_PRIM_DEVTYPE_VIDEOPROC</constant></entry> + <entry>7</entry> + <entry>Use for a video processor device.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-log-addr-types"> + <title>CEC Logical Address Types</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_TV</constant></entry> + <entry>0</entry> + <entry>Use for a TV.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_RECORD</constant></entry> + <entry>1</entry> + <entry>Use for a recording device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_TUNER</constant></entry> + <entry>2</entry> + <entry>Use for a tuner device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_PLAYBACK</constant></entry> + <entry>3</entry> + <entry>Use for a playback device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_AUDIOSYSTEM</constant></entry> + <entry>4</entry> + <entry>Use for an audio system device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_SPECIFIC</constant></entry> + <entry>5</entry> + <entry>Use for a second TV or for a video processor device.</entry> + </row> + <row> + <entry><constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant></entry> + <entry>6</entry> + <entry>Use this if you just want to remain unregistered. + Used for pure CEC switches or CDC-only devices (CDC: + Capability Discovery and Control).</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-all-dev-types-flags"> + <title>CEC All Device Types Flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_TV</constant></entry> + <entry>0x80</entry> + <entry>This supports the TV type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_RECORD</constant></entry> + <entry>0x40</entry> + <entry>This supports the Recording type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_TUNER</constant></entry> + <entry>0x20</entry> + <entry>This supports the Tuner type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_PLAYBACK</constant></entry> + <entry>0x10</entry> + <entry>This supports the Playback type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM</constant></entry> + <entry>0x08</entry> + <entry>This supports the Audio System type.</entry> + </row> + <row> + <entry><constant>CEC_OP_ALL_DEVTYPE_SWITCH</constant></entry> + <entry>0x04</entry> + <entry>This supports the CEC Switch or Video Processing type.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</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 0000000..d95f178 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-adap-g-phys-addr.xml @@ -0,0 +1,86 @@ +<refentry id="cec-ioc-adap-g-phys-addr"> + <refmeta> + <refentrytitle>ioctl CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_ADAP_G_PHYS_ADDR</refname> + <refname>CEC_ADAP_S_PHYS_ADDR</refname> + <refpurpose>Get or set the physical address</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>__u16 *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>To query the current physical address applications call the +<constant>CEC_ADAP_G_PHYS_ADDR</constant> ioctl with a pointer to an __u16 +where the driver stores the physical address.</para> + + <para>To set a new physical address applications store the physical address in +an __u16 and call the <constant>CEC_ADAP_S_PHYS_ADDR</constant> ioctl with a +pointer to this integer. <constant>CEC_ADAP_S_PHYS_ADDR</constant> is only +available if <constant>CEC_CAP_PHYS_ADDR</constant> is set (&ENOTTY; will be returned +otherwise). <constant>CEC_ADAP_S_PHYS_ADDR</constant> +can only be called by a file handle in initiator mode (see &CEC-S-MODE;), if not +&EBUSY; will be returned.</para> + + <para>The physical address is a 16-bit number where each group of 4 bits +represent a digit of the physical address a.b.c.d where the most significant +4 bits represent 'a'. The CEC root device (usually the TV) has address 0.0.0.0. +Every device that is hooked up to an input of the TV has address a.0.0.0 (where +'a' is ≥ 1), devices hooked up to those in turn have addresses a.b.0.0, etc. +So a topology of up to 5 devices deep is supported. The physical address a +device shall use is stored in the EDID of the sink.</para> + +<para>For example, the EDID for each HDMI input of the TV will have a different +physical address of the form a.0.0.0 that the sources will read out and use as +their physical address.</para> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</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 0000000..697dde5 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml @@ -0,0 +1,202 @@ +<refentry id="cec-ioc-g-event"> + <refmeta> + <refentrytitle>ioctl CEC_DQEVENT</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_DQEVENT</refname> + <refpurpose>Dequeue a CEC event</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct cec_event *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_DQEVENT</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>CEC devices can send asynchronous events. These can be retrieved by calling + the <constant>CEC_DQEVENT</constant> ioctl. If the file descriptor is in non-blocking + mode and no event is pending, then it will return -1 and set errno to the &EAGAIN;.</para> + + <para>The internal event queues are per-filehandle and per-event type. If there is + no more room in a queue then the last event is overwritten with the new one. This + means that intermediate results can be thrown away but that the latest event is always + available. This also means that is it possible to read two successive events that have + the same value (e.g. two CEC_EVENT_STATE_CHANGE events with the same state). In that + case the intermediate state changes were lost but it is guaranteed that the state + did change in between the two events.</para> + + <table pgwide="1" frame="none" id="cec-event-state-change"> + <title>struct <structname>cec_event_state_change</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u16</entry> + <entry><structfield>phys_addr</structfield></entry> + <entry>The current physical address.</entry> + </row> + <row> + <entry>__u16</entry> + <entry><structfield>log_addr_mask</structfield></entry> + <entry>The current set of claimed logical addresses.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-event-lost-msgs"> + <title>struct <structname>cec_event_lost_msgs</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>lost_msgs</structfield></entry> + <entry>Set to the number of lost messages since the filehandle + was opened or since the last time this event was dequeued for + this filehandle. The messages lost are the oldest messages. So + when a new message arrives and there is no more room, then the + oldest message is discarded to make room for the new one. The + internal size of the message queue guarantees that all messages + received in the last two seconds will be stored. Since messages + should be replied to within a second according to the CEC + specification, this is more than enough. + </entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-event"> + <title>struct <structname>cec_event</structname></title> + <tgroup cols="4"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u64</entry> + <entry><structfield>ts</structfield></entry> + <entry>Timestamp of the event in ns.</entry> + <entry></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>event</structfield></entry> + <entry>The CEC event type, see <xref linkend="cec-events" />.</entry> + <entry></entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Event flags, see <xref linkend="cec-event-flags" />.</entry> + <entry></entry> + </row> + <row> + <entry>union</entry> + <entry>(anonymous)</entry> + <entry></entry> + <entry></entry> + </row> + <row> + <entry></entry> + <entry>struct cec_event_state_change</entry> + <entry><structfield>state_change</structfield></entry> + <entry>The new adapter state as sent by the <constant>CEC_EVENT_STATE_CHANGE</constant> + event.</entry> + </row> + <row> + <entry></entry> + <entry>struct cec_event_lost_msgs</entry> + <entry><structfield>lost_msgs</structfield></entry> + <entry>The number of lost messages as sent by the <constant>CEC_EVENT_LOST_MSGS</constant> + event.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-events"> + <title>CEC Events Types</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_EVENT_STATE_CHANGE</constant></entry> + <entry>1</entry> + <entry>Generated when the CEC Adapter's state changes. When open() is + called an initial event will be generated for that filehandle with the + CEC Adapter's state at that time. + </entry> + </row> + <row> + <entry><constant>CEC_EVENT_LOST_MSGS</constant></entry> + <entry>2</entry> + <entry>Generated if one or more CEC messages were lost because the + application didn't dequeue CEC messages fast enough.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-event-flags"> + <title>CEC Event Flags</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_EVENT_FL_INITIAL_VALUE</constant></entry> + <entry>1</entry> + <entry>Set for the initial events that are generated when the device is + opened. See the table above for which events do this. This allows + applications to learn the initial state of the CEC adapter at open() + time.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</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 0000000..26b4282 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-g-mode.xml @@ -0,0 +1,255 @@ +<refentry id="cec-ioc-g-mode"> + <refmeta> + <refentrytitle>ioctl CEC_G_MODE, CEC_S_MODE</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_G_MODE</refname> + <refname>CEC_S_MODE</refname> + <refpurpose>Get or set exclusive use of the CEC adapter</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>__u32 *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_G_MODE, CEC_S_MODE</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>By default any filehandle can use &CEC-TRANSMIT; and &CEC-RECEIVE;, but +in order to prevent applications from stepping on each others toes it must be possible +to obtain exclusive access to the CEC adapter. This ioctl sets the filehandle +to initiator and/or follower mode which can be exclusive depending on the chosen +mode. The initiator is the filehandle that is used +to initiate messages, i.e. it commands other CEC devices. The follower is the filehandle +that receives messages sent to the CEC adapter and processes them. The same filehandle +can be both initiator and follower, or this role can be taken by two different +filehandles.</para> + + <para>When a CEC message is received, then the CEC framework will decide how +it will be processed. If the message is a reply to an earlier transmitted message, +then the reply is sent back to the filehandle that is waiting for it. In addition +the CEC framework will process it.</para> + + <para>If the message is not a reply, then the CEC framework will process it +first. If there is no follower, then the message is just discarded and a feature +abort is sent back to the initiator if the framework couldn't process it. If there +is a follower, then the message is passed on to the follower who will use +&CEC-RECEIVE; to dequeue the new message. The framework expects the follower to +make the right decisions.</para> + + <para>The CEC framework will process core messages unless requested otherwise +by the follower. The follower can enable the passthrough mode. In that case, the +CEC framework will pass on most core messages without processing them and +the follower will have to implement those messages. There are some messages +that the core will always process, regardless of the passthrough mode. See +<xref linkend="cec-core-processing" /> for details.</para> + + <para>If there is no initiator, then any CEC filehandle can use &CEC-TRANSMIT;. +If there is an exclusive initiator then only that initiator can call &CEC-TRANSMIT;. +The follower can of course always call &CEC-TRANSMIT;.</para> + + <para>Available initiator modes are:</para> + + <table pgwide="1" frame="none" id="cec-mode-initiator"> + <title>Initiator Modes</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_MODE_NO_INITIATOR</constant></entry> + <entry>0x0</entry> + <entry>This is not an initiator, i.e. it cannot transmit CEC messages + or make any other changes to the CEC adapter.</entry> + </row> + <row> + <entry><constant>CEC_MODE_INITIATOR</constant></entry> + <entry>0x1</entry> + <entry>This is an initiator (the default when the device is opened) and it + can transmit CEC messages and make changes to the CEC adapter, unless there + is an exclusive initiator.</entry> + </row> + <row> + <entry><constant>CEC_MODE_EXCL_INITIATOR</constant></entry> + <entry>0x2</entry> + <entry>This is an exclusive initiator and this file descriptor is the only one + that can transmit CEC messages and make changes to the CEC adapter. If someone + else is already the exclusive initiator then an attempt to become one will return + the &EBUSY; error.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Available follower modes are:</para> + + <table pgwide="1" frame="none" id="cec-mode-follower"> + <title>Follower Modes</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_MODE_NO_FOLLOWER</constant></entry> + <entry>0x00</entry> + <entry>This is not a follower (the default when the device is opened).</entry> + </row> + <row> + <entry><constant>CEC_MODE_FOLLOWER</constant></entry> + <entry>0x10</entry> + <entry>This is a follower and it will receive CEC messages unless there is + an exclusive follower. You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant> + is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified, + &EINVAL; is returned in that case.</entry> + </row> + <row> + <entry><constant>CEC_MODE_EXCL_FOLLOWER</constant></entry> + <entry>0x20</entry> + <entry>This is an exclusive follower and only this file descriptor will receive + CEC messages for processing. If someone else is already the exclusive follower + then an attempt to become one will return the &EBUSY; error. You cannot become + a follower if <constant>CEC_CAP_TRANSMIT</constant> is not set or if + <constant>CEC_MODE_NO_INITIATOR</constant> was specified, &EINVAL; is returned + in that case.</entry> + </row> + <row> + <entry><constant>CEC_MODE_EXCL_FOLLOWER_PASSTHRU</constant></entry> + <entry>0x30</entry> + <entry>This is an exclusive follower and only this file descriptor will receive + CEC messages for processing. In addition it will put the CEC device into + passthrough mode, allowing the exclusive follower to handle most core messages + instead of relying on the CEC framework for that. If someone else is already the + exclusive follower then an attempt to become one will return the &EBUSY; error. + You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant> + is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified, + &EINVAL; is returned in that case.</entry> + </row> + <row> + <entry><constant>CEC_MODE_MONITOR</constant></entry> + <entry>0xe0</entry> + <entry>Put the file descriptor into monitor mode. Can only be used in combination + with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be + returned. In monitor mode all messages this CEC device transmits and all messages + it receives (both broadcast messages and directed messages for one its logical + addresses) will be reported. This is very useful for debugging. This is only + allowed if the process has the <constant>CAP_NET_ADMIN</constant> + capability. If that is not set, then &EPERM; is returned.</entry> + </row> + <row> + <entry><constant>CEC_MODE_MONITOR_ALL</constant></entry> + <entry>0xf0</entry> + <entry>Put the file descriptor into 'monitor all' mode. Can only be used in combination + with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be + returned. In 'monitor all' mode all messages this CEC device transmits and all messages + it receives, including directed messages for other CEC devices will be reported. This + is very useful for debugging, but not all devices support this. This mode requires that + the <constant>CEC_CAP_MONITOR_ALL</constant> capability is set, otherwise &EINVAL; is + returned. This is only allowed if the process has the <constant>CAP_NET_ADMIN</constant> + capability. If that is not set, then &EPERM; is returned.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Core message processing details:</para> + + <table pgwide="1" frame="none" id="cec-core-processing"> + <title>Core Message Processing</title> + <tgroup cols="2"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_MSG_GET_CEC_VERSION</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will return the CEC version that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry> + </row> + <row> + <entry><constant>CEC_MSG_GIVE_DEVICE_VENDOR_ID</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will return the vendor ID that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry> + </row> + <row> + <entry><constant>CEC_MSG_ABORT</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will return a feature refused message as per the specification.</entry> + </row> + <row> + <entry><constant>CEC_MSG_GIVE_PHYSICAL_ADDR</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will report the current physical address.</entry> + </row> + <row> + <entry><constant>CEC_MSG_GIVE_OSD_NAME</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will report the current OSD name as was set with + &CEC-ADAP-S-LOG-ADDRS;.</entry> + </row> + <row> + <entry><constant>CEC_MSG_GIVE_FEATURES</constant></entry> + <entry>When in passthrough mode this message has to be handled by userspace, + otherwise the core will report the current features as was set with + &CEC-ADAP-S-LOG-ADDRS; or the message is ignore if the CEC version was + older than 2.0.</entry> + </row> + <row> + <entry><constant>CEC_MSG_USER_CONTROL_PRESSED</constant></entry> + <entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control + key press. This message is always passed on to userspace.</entry> + </row> + <row> + <entry><constant>CEC_MSG_USER_CONTROL_RELEASED</constant></entry> + <entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control + key release. This message is always passed on to userspace.</entry> + </row> + <row> + <entry><constant>CEC_MSG_REPORT_PHYSICAL_ADDR</constant></entry> + <entry>The CEC framework will make note of the reported physical address + and then just pass the message on to userspace.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</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 0000000..fde9f86 --- /dev/null +++ b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml @@ -0,0 +1,274 @@ +<refentry id="cec-ioc-receive"> + <refmeta> + <refentrytitle>ioctl CEC_RECEIVE, CEC_TRANSMIT</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>CEC_RECEIVE</refname> + <refname>CEC_TRANSMIT</refname> + <refpurpose>Receive or transmit a CEC message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct cec_msg *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>File descriptor returned by + <link linkend='cec-func-open'><function>open()</function></link>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>CEC_RECEIVE, CEC_TRANSMIT</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Note: this documents the proposed CEC API. This API is not yet finalized and + is currently only available as a staging kernel module. + </para> + + <para>To receive a CEC message the application has to fill in the + <structname>cec_msg</structname> structure and pass it to the + <constant>CEC_RECEIVE</constant> ioctl. <constant>CEC_RECEIVE</constant> is + only available if <constant>CEC_CAP_RECEIVE</constant> is set. If the + file descriptor is in non-blocking mode and there are no received + messages pending, then it will return -1 and set errno to the &EAGAIN;. + If the file descriptor is in blocking mode and <structfield>timeout</structfield> + is non-zero and no message arrived within <structfield>timeout</structfield> + milliseconds, then it will return -1 and set errno to the &ETIMEDOUT;.</para> + + <para>To send a CEC message the application has to fill in the + <structname>cec_msg</structname> structure and pass it to the + <constant>CEC_TRANSMIT</constant> ioctl. <constant>CEC_TRANSMIT</constant> is + only available if <constant>CEC_CAP_TRANSMIT</constant> is set. + If there is no more room in the transmit queue, then it will return + -1 and set errno to the &EBUSY;.</para> + + <table pgwide="1" frame="none" id="cec-msg"> + <title>struct <structname>cec_msg</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u64</entry> + <entry><structfield>ts</structfield></entry> + <entry>Timestamp of when the message was transmitted in ns in the case + of <constant>CEC_TRANSMIT</constant> with <structfield>reply</structfield> + set to 0, or the timestamp of the received message in all other cases.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>len</structfield></entry> + <entry>The length of the message. For <constant>CEC_TRANSMIT</constant> this + is filled in by the application. The driver will fill this in for + <constant>CEC_RECEIVE</constant> and for <constant>CEC_TRANSMIT</constant> + it will be filled in with the length of the reply message if + <structfield>reply</structfield> was set.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>timeout</structfield></entry> + <entry>The timeout in milliseconds. This is the time the device will wait for a message to + be received before timing out. If it is set to 0, then it will wait indefinitely when it + is called by <constant>CEC_RECEIVE</constant>. If it is 0 and it is called by + <constant>CEC_TRANSMIT</constant>, then it will be replaced by 1000 if the + <structfield>reply</structfield> is non-zero or ignored if <structfield>reply</structfield> + is 0.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>sequence</structfield></entry> + <entry>The sequence number is automatically assigned by the CEC + framework for all transmitted messages. It can be later used by the + framework to generate an event if a reply for a message was + requested and the message was transmitted in a non-blocking mode. + </entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>flags</structfield></entry> + <entry>Flags. No flags are defined yet, so set this to 0.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>rx_status</structfield></entry> + <entry>The status bits of the received message. See <xref linkend="cec-rx-status" /> + for the possible status values. It is 0 if this message was transmitted, not + received, unless this is the reply to a transmitted message. In that case both + <structfield>rx_status</structfield> and <structfield>tx_status</structfield> + are set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_status</structfield></entry> + <entry>The status bits of the transmitted message. See <xref linkend="cec-tx-status" /> + for the possible status values. It is 0 if this messages was received, not + transmitted.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>msg</structfield>[16]</entry> + <entry>The message payload. For <constant>CEC_TRANSMIT</constant> this + is filled in by the application. The driver will fill this in for + <constant>CEC_RECEIVE</constant> and for <constant>CEC_TRANSMIT</constant> + it will be filled in with the payload of the reply message if + <structfield>reply</structfield> was set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>reply</structfield></entry> + <entry>Wait until this message is replied. If <structfield>reply</structfield> + is 0 and the <structfield>timeout</structfield> is 0, then don't wait for a reply but + return after transmitting the message. If there was an error as indicated by a non-zero + <structfield>tx_status</structfield> field, then <structfield>reply</structfield> and + <structfield>timeout</structfield> are both set to 0 by the driver. Ignored by + <constant>CEC_RECEIVE</constant>. The case where <structfield>reply</structfield> is 0 + (this is the opcode for the Feature Abort message) and <structfield>timeout</structfield> + is non-zero is specifically allowed to send a message and wait up to <structfield>timeout</structfield> + milliseconds for a Feature Abort reply. In this case <structfield>rx_status</structfield> + will either be set to <constant>CEC_RX_STATUS_TIMEOUT</constant> or + <constant>CEC_RX_STATUS_FEATURE_ABORT</constant>.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_arb_lost_cnt</structfield></entry> + <entry>A counter of the number of transmit attempts that resulted in the + Arbitration Lost error. This is only set if the hardware supports this, otherwise + it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_ARB_LOST</constant> + status bit is set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_nack_cnt</structfield></entry> + <entry>A counter of the number of transmit attempts that resulted in the + Not Acknowledged error. This is only set if the hardware supports this, otherwise + it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_NACK</constant> + status bit is set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_low_drive_cnt</structfield></entry> + <entry>A counter of the number of transmit attempts that resulted in the + Arbitration Lost error. This is only set if the hardware supports this, otherwise + it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_LOW_DRIVE</constant> + status bit is set.</entry> + </row> + <row> + <entry>__u8</entry> + <entry><structfield>tx_error_cnt</structfield></entry> + <entry>A counter of the number of transmit errors other than Arbitration Lost + or Not Acknowledged. This is only set if the hardware supports this, otherwise + it is always 0. This counter is only valid if the <constant>CEC_TX_STATUS_ERROR</constant> + status bit is set.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-tx-status"> + <title>CEC Transmit Status</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_TX_STATUS_OK</constant></entry> + <entry>0x01</entry> + <entry>The message was transmitted successfully. This is mutually exclusive with + <constant>CEC_TX_STATUS_MAX_RETRIES</constant>. Other bits can still be set if + earlier attempts met with failure before the transmit was eventually successful.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_ARB_LOST</constant></entry> + <entry>0x02</entry> + <entry>CEC line arbitration was lost.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_NACK</constant></entry> + <entry>0x04</entry> + <entry>Message was not acknowledged.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_LOW_DRIVE</constant></entry> + <entry>0x08</entry> + <entry>Low drive was detected on the CEC bus. This indicates that a follower + detected an error on the bus and requests a retransmission.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_ERROR</constant></entry> + <entry>0x10</entry> + <entry>Some error occurred. This is used for any errors that do not + fit the previous two, either because the hardware could not tell + which error occurred, or because the hardware tested for other conditions + besides those two.</entry> + </row> + <row> + <entry><constant>CEC_TX_STATUS_MAX_RETRIES</constant></entry> + <entry>0x20</entry> + <entry>The transmit failed after one or more retries. This status bit is mutually + exclusive with <constant>CEC_TX_STATUS_OK</constant>. Other bits can still be set + to explain which failures were seen.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="cec-rx-status"> + <title>CEC Receive Status</title> + <tgroup cols="3"> + &cs-def; + <tbody valign="top"> + <row> + <entry><constant>CEC_RX_STATUS_OK</constant></entry> + <entry>0x01</entry> + <entry>The message was received successfully.</entry> + </row> + <row> + <entry><constant>CEC_RX_STATUS_TIMEOUT</constant></entry> + <entry>0x02</entry> + <entry>The reply to an earlier transmitted message timed out.</entry> + </row> + <row> + <entry><constant>CEC_RX_STATUS_FEATURE_ABORT</constant></entry> + <entry>0x04</entry> + <entry>The message was received successfully but the reply was + <constant>CEC_MSG_FEATURE_ABORT</constant>. This status is only + set if this message was the reply to an earlier transmitted + message.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index e09025d..21a3dde 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -88,7 +88,7 @@ function.<footnote> <structfield>capabilities</structfield> field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl is set. There are two streaming methods, to determine if the memory mapping flavor is -supported applications must call the &VIDIOC-REQBUFS; ioctl.</para> +supported applications must call the &VIDIOC-REQBUFS; ioctl with the memory type set to <constant>V4L2_MEMORY_MMAP</constant>.</para> <para>Streaming is an I/O method where only pointers to buffers are exchanged between application and driver, the data itself is not @@ -369,7 +369,7 @@ rest should be evident.</para> <structfield>capabilities</structfield> field of &v4l2-capability; returned by the &VIDIOC-QUERYCAP; ioctl is set. If the particular user pointer method (not only memory mapping) is supported must be -determined by calling the &VIDIOC-REQBUFS; ioctl.</para> +determined by calling the &VIDIOC-REQBUFS; ioctl with the memory type set to <constant>V4L2_MEMORY_USERPTR</constant>.</para> <para>This I/O method combines advantages of the read/write and memory 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 34cada2..71f9dbb 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> <varlistentry> <term>LIRC_SET_{SEND,REC}_CARRIER</term> <listitem> - <para>Set send/receive carrier (in Hz).</para> + <para>Set send/receive carrier (in Hz). Return 0 on success.</para> </listitem> </varlistentry> <varlistentry> diff --git a/Documentation/DocBook/media/v4l/media-types.xml b/Documentation/DocBook/media/v4l/media-types.xml index 5e3f20f..95aa1f9 100644 --- a/Documentation/DocBook/media/v4l/media-types.xml +++ b/Documentation/DocBook/media/v4l/media-types.xml @@ -121,6 +121,70 @@ <entry><constant>MEDIA_ENT_F_AUDIO_MIXER</constant></entry> <entry>Audio Mixer Function Entity.</entry> </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_COMPOSER</constant></entry> + <entry>Video composer (blender). An entity capable of video + composing must have at least two sink pads and one source + pad, and composes input video frames onto output video + frames. Composition can be performed using alpha blending, + color keying, raster operations (ROP), stitching or any other + means. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_PIXEL_FORMATTER</constant></entry> + <entry>Video pixel formatter. An entity capable of pixel formatting + must have at least one sink pad and one source pad. Read + pixel formatters read pixels from memory and perform a subset + of unpacking, cropping, color keying, alpha multiplication + and pixel encoding conversion. Write pixel formatters perform + a subset of dithering, pixel encoding conversion and packing + and write pixels to memory. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_PIXEL_ENC_CONV</constant></entry> + <entry>Video pixel encoding converter. An entity capable of pixel + enconding conversion must have at least one sink pad and one + source pad, and convert the encoding of pixels received on + its sink pad(s) to a different encoding output on its source + pad(s). Pixel encoding conversion includes but isn't limited + to RGB to/from HSV, RGB to/from YUV and CFA (Bayer) to RGB + conversions. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_LUT</constant></entry> + <entry>Video look-up table. An entity capable of video lookup table + processing must have one sink pad and one source pad. It uses + the values of the pixels received on its sink pad to look up + entries in internal tables and output them on its source pad. + The lookup processing can be performed on all components + separately or combine them for multi-dimensional table + lookups. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_SCALER</constant></entry> + <entry>Video scaler. An entity capable of video scaling must have + at least one sink pad and one source pad, and scale the + video frame(s) received on its sink pad(s) to a different + resolution output on its source pad(s). The range of + supported scaling ratios is entity-specific and can differ + between the horizontal and vertical directions (in particular + scaling can be supported in one direction only). Binning and + skipping are considered as scaling. + </entry> + </row> + <row> + <entry><constant>MEDIA_ENT_F_PROC_VIDEO_STATISTICS</constant></entry> + <entry>Video statistics computation (histogram, 3A, ...). An entity + capable of statistics computation must have one sink pad and + one source pad. It computes statistics over the frames + received on its sink pad and outputs the statistics data on + its source pad. + </entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/pixfmt-z16.xml b/Documentation/DocBook/media/v4l/pixfmt-z16.xml index 3d87e4b..1d9cb16 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-z16.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-z16.xml @@ -5,7 +5,7 @@ </refmeta> <refnamediv> <refname><constant>V4L2_PIX_FMT_Z16</constant></refname> - <refpurpose>Interleaved grey-scale image, e.g. from a stereo-pair</refpurpose> + <refpurpose>16-bit depth data with distance values at each pixel</refpurpose> </refnamediv> <refsect1> <title>Description</title> diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml index 0f193fd..6f529e1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml @@ -6,7 +6,7 @@ <refnamediv> <refname>VIDIOC_REQBUFS</refname> - <refpurpose>Initiate Memory Mapping or User Pointer I/O</refpurpose> + <refpurpose>Initiate Memory Mapping, User Pointer or DMA Buffer I/O</refpurpose> </refnamediv> <refsynopsisdiv> diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl index 7b77e0f..a2765d8 100644 --- a/Documentation/DocBook/media_api.tmpl +++ b/Documentation/DocBook/media_api.tmpl @@ -75,7 +75,7 @@ </mediaobject> </figure> <para>The media infrastructure API was designed to control such - devices. It is divided into four parts.</para> + devices. It is divided into five parts.</para> <para>The first part covers radio, video capture and output, cameras, analog TV devices and codecs.</para> <para>The second part covers the @@ -87,6 +87,7 @@ <xref linkend="fe-delivery-system-t" />.</para> <para>The third part covers the Remote Controller API.</para> <para>The fourth part covers the Media Controller API.</para> + <para>The fifth part covers the CEC (Consumer Electronics Control) API.</para> <para>It should also be noted that a media device may also have audio components, like mixers, PCM capture, PCM playback, etc, which are controlled via ALSA API.</para> @@ -107,6 +108,9 @@ <part id="media_common"> &sub-media-controller; </part> +<part id="cec"> +&sub-cec-api; +</part> <chapter id="gen_errors"> &sub-gen-errors; diff --git a/Documentation/cec.txt b/Documentation/cec.txt new file mode 100644 index 0000000..75155fe --- /dev/null +++ b/Documentation/cec.txt @@ -0,0 +1,267 @@ +CEC Kernel Support +================== + +The CEC framework provides a unified kernel interface for use with HDMI CEC +hardware. It is designed to handle a multiple types of hardware (receivers, +transmitters, USB dongles). The framework also gives the option to decide +what to do in the kernel driver and what should be handled by userspace +applications. In addition it integrates the remote control passthrough +feature into the kernel's remote control framework. + + +The CEC Protocol +---------------- + +The CEC protocol enables consumer electronic devices to communicate with each +other through the HDMI connection. The protocol uses logical addresses in the +communication. The logical address is strictly connected with the functionality +provided by the device. The TV acting as the communication hub is always +assigned address 0. The physical address is determined by the physical +connection between devices. + +The CEC framework described here is up to date with the CEC 2.0 specification. +It is documented in the HDMI 1.4 specification with the new 2.0 bits documented +in the HDMI 2.0 specification. But for most of the features the freely available +HDMI 1.3a specification is sufficient: + +http://www.microprocessor.org/HDMISpecification13a.pdf + + +The Kernel Interface +==================== + +CEC Adapter +----------- + +The struct cec_adapter represents the CEC adapter hardware. It is created by +calling cec_allocate_adapter() and deleted by calling cec_delete_adapter(): + +struct cec_adapter *cec_allocate_adapter(const struct cec_adap_ops *ops, + void *priv, const char *name, u32 caps, u8 available_las, + struct device *parent); +void cec_delete_adapter(struct cec_adapter *adap); + +To create an adapter you need to pass the following information: + +ops: adapter operations which are called by the CEC framework and that you +have to implement. + +priv: will be stored in adap->priv and can be used by the adapter ops. + +name: the name of the CEC adapter. Note: this name will be copied. + +caps: capabilities of the CEC adapter. These capabilities determine the + capabilities of the hardware and which parts are to be handled + by userspace and which parts are handled by kernelspace. The + capabilities are returned by CEC_ADAP_G_CAPS. + +available_las: the number of simultaneous logical addresses that this + adapter can handle. Must be 1 <= available_las <= CEC_MAX_LOG_ADDRS. + +parent: the parent device. + + +To register the /dev/cecX device node and the remote control device (if +CEC_CAP_RC is set) you call: + +int cec_register_adapter(struct cec_adapter *adap); + +To unregister the devices call: + +void cec_unregister_adapter(struct cec_adapter *adap); + +Note: if cec_register_adapter() fails, then call cec_delete_adapter() to +clean up. But if cec_register_adapter() succeeded, then only call +cec_unregister_adapter() to clean up, never cec_delete_adapter(). The +unregister function will delete the adapter automatically once the last user +of that /dev/cecX device has closed its file handle. + + +Implementing the Low-Level CEC Adapter +-------------------------------------- + +The following low-level adapter operations have to be implemented in +your driver: + +struct cec_adap_ops { + /* Low-level callbacks */ + int (*adap_enable)(struct cec_adapter *adap, bool enable); + int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); + int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, + u32 signal_free_time, struct cec_msg *msg); + void (*adap_log_status)(struct cec_adapter *adap); + + /* High-level callbacks */ + ... +}; + +The three low-level ops deal with various aspects of controlling the CEC adapter +hardware: + + +To enable/disable the hardware: + + int (*adap_enable)(struct cec_adapter *adap, bool enable); + +This callback enables or disables the CEC hardware. Enabling the CEC hardware +means powering it up in a state where no logical addresses are claimed. This +op assumes that the physical address (adap->phys_addr) is valid when enable is +true and will not change while the CEC adapter remains enabled. The initial +state of the CEC adapter after calling cec_allocate_adapter() is disabled. + +Note that adap_enable must return 0 if enable is false. + + +To enable/disable the 'monitor all' mode: + + int (*adap_monitor_all_enable)(struct cec_adapter *adap, bool enable); + +If enabled, then the adapter should be put in a mode to also monitor messages +that not for us. Not all hardware supports this and this function is only +called if the CEC_CAP_MONITOR_ALL capability is set. This callback is optional +(some hardware may always be in 'monitor all' mode). + +Note that adap_monitor_all_enable must return 0 if enable is false. + + +To program a new logical address: + + int (*adap_log_addr)(struct cec_adapter *adap, u8 logical_addr); + +If logical_addr == CEC_LOG_ADDR_INVALID then all programmed logical addresses +are to be erased. Otherwise the given logical address should be programmed. +If the maximum number of available logical addresses is exceeded, then it +should return -ENXIO. Once a logical address is programmed the CEC hardware +can receive directed messages to that address. + +Note that adap_log_addr must return 0 if logical_addr is CEC_LOG_ADDR_INVALID. + + +To transmit a new message: + + int (*adap_transmit)(struct cec_adapter *adap, u8 attempts, + u32 signal_free_time, struct cec_msg *msg); + +This transmits a new message. The attempts argument is the suggested number of +attempts for the transmit. + +The signal_free_time is the number of data bit periods that the adapter should +wait when the line is free before attempting to send a message. This value +depends on whether this transmit is a retry, a message from a new initiator or +a new message for the same initiator. Most hardware will handle this +automatically, but in some cases this information is needed. + +The CEC_FREE_TIME_TO_USEC macro can be used to convert signal_free_time to +microseconds (one data bit period is 2.4 ms). + + +To log the current CEC hardware status: + + void (*adap_status)(struct cec_adapter *adap, struct seq_file *file); + +This optional callback can be used to show the status of the CEC hardware. +The status is available through debugfs: cat /sys/kernel/debug/cec/cecX/status + + +Your adapter driver will also have to react to events (typically interrupt +driven) by calling into the framework in the following situations: + +When a transmit finished (successfully or otherwise): + +void cec_transmit_done(struct cec_adapter *adap, u8 status, u8 arb_lost_cnt, + u8 nack_cnt, u8 low_drive_cnt, u8 error_cnt); + +The status can be one of: + +CEC_TX_STATUS_OK: the transmit was successful. +CEC_TX_STATUS_ARB_LOST: arbitration was lost: another CEC initiator +took control of the CEC line and you lost the arbitration. +CEC_TX_STATUS_NACK: the message was nacked (for a directed message) or +acked (for a broadcast message). A retransmission is needed. +CEC_TX_STATUS_LOW_DRIVE: low drive was detected on the CEC bus. This +indicates that a follower detected an error on the bus and requested a +retransmission. +CEC_TX_STATUS_ERROR: some unspecified error occurred: this can be one of +the previous two if the hardware cannot differentiate or something else +entirely. +CEC_TX_STATUS_MAX_RETRIES: could not transmit the message after +trying multiple times. Should only be set by the driver if it has hardware +support for retrying messages. If set, then the framework assumes that it +doesn't have to make another attempt to transmit the message since the +hardware did that already. + +The *_cnt arguments are the number of error conditions that were seen. +This may be 0 if no information is available. Drivers that do not support +hardware retry can just set the counter corresponding to the transmit error +to 1, if the hardware does support retry then either set these counters to +0 if the hardware provides no feedback of which errors occurred and how many +times, or fill in the correct values as reported by the hardware. + +When a CEC message was received: + +void cec_received_msg(struct cec_adapter *adap, struct cec_msg *msg); + +Speaks for itself. + +Implementing the High-Level CEC Adapter +--------------------------------------- + +The low-level operations drive the hardware, the high-level operations are +CEC protocol driven. The following high-level callbacks are available: + +struct cec_adap_ops { + /* Low-level callbacks */ + ... + + /* High-level CEC message callback */ + int (*received)(struct cec_adapter *adap, struct cec_msg *msg); +}; + +The received() callback allows the driver to optionally handle a newly +received CEC message + + int (*received)(struct cec_adapter *adap, struct cec_msg *msg); + +If the driver wants to process a CEC message, then it can implement this +callback. If it doesn't want to handle this message, then it should return +-ENOMSG, otherwise the CEC framework assumes it processed this message and +it will not no anything with it. + + +CEC framework functions +----------------------- + +CEC Adapter drivers can call the following CEC framework functions: + +int cec_transmit_msg(struct cec_adapter *adap, struct cec_msg *msg, + bool block); + +Transmit a CEC message. If block is true, then wait until the message has been +transmitted, otherwise just queue it and return. + +void cec_s_phys_addr(struct cec_adapter *adap, u16 phys_addr, bool block); + +Change the physical address. This function will set adap->phys_addr and +send an event if it has changed. If cec_s_log_addrs() has been called and +the physical address has become valid, then the CEC framework will start +claiming the logical addresses. If block is true, then this function won't +return until this process has finished. + +When the physical address is set to a valid value the CEC adapter will +be enabled (see the adap_enable op). When it is set to CEC_PHYS_ADDR_INVALID, +then the CEC adapter will be disabled. If you change a valid physical address +to another valid physical address, then this function will first set the +address to CEC_PHYS_ADDR_INVALID before enabling the new physical address. + +int cec_s_log_addrs(struct cec_adapter *adap, + struct cec_log_addrs *log_addrs, bool block); + +Claim the CEC logical addresses. Should never be called if CEC_CAP_LOG_ADDRS +is set. If block is true, then wait until the logical addresses have been +claimed, otherwise just queue it and return. To unconfigure all logical +addresses call this function with log_addrs set to NULL or with +log_addrs->num_log_addrs set to 0. The block argument is ignored when +unconfiguring. This function will just return if the physical address is +invalid. Once the physical address becomes valid, then the framework will +attempt 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 0000000..59a47a5 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek-vcodec.txt @@ -0,0 +1,59 @@ +Mediatek Video Codec + +Mediatek Video Codec is the video codec hw present in Mediatek SoCs which +supports high resolution encoding functionalities. + +Required properties: +- compatible : "mediatek,mt8173-vcodec-enc" for encoder +- reg : Physical base address of the video codec registers and length of + memory mapped region. +- interrupts : interrupt number to the cpu. +- mediatek,larb : must contain the local arbiters in the current Socs. +- clocks : list of clock specifiers, corresponding to entries in + the clock-names property. +- clock-names: encoder must contain "venc_sel_src", "venc_sel", +- "venc_lt_sel_src", "venc_lt_sel". +- iommus : should point to the respective IOMMU block with master port as + argument, see Documentation/devicetree/bindings/iommu/mediatek,iommu.txt + for details. +- mediatek,vpu : the node of video processor unit + +Example: +vcodec_enc: vcodec@0x18002000 { + compatible = "mediatek,mt8173-vcodec-enc"; + reg = <0 0x18002000 0 0x1000>, /*VENC_SYS*/ + <0 0x19002000 0 0x1000>; /*VENC_LT_SYS*/ + interrupts = <GIC_SPI 198 IRQ_TYPE_LEVEL_LOW>, + <GIC_SPI 202 IRQ_TYPE_LEVEL_LOW>; + mediatek,larb = <&larb3>, + <&larb5>; + iommus = <&iommu M4U_PORT_VENC_RCPU>, + <&iommu M4U_PORT_VENC_REC>, + <&iommu M4U_PORT_VENC_BSDMA>, + <&iommu M4U_PORT_VENC_SV_COMV>, + <&iommu M4U_PORT_VENC_RD_COMV>, + <&iommu M4U_PORT_VENC_CUR_LUMA>, + <&iommu M4U_PORT_VENC_CUR_CHROMA>, + <&iommu M4U_PORT_VENC_REF_LUMA>, + <&iommu M4U_PORT_VENC_REF_CHROMA>, + <&iommu M4U_PORT_VENC_NBM_RDMA>, + <&iommu M4U_PORT_VENC_NBM_WDMA>, + <&iommu M4U_PORT_VENC_RCPU_SET2>, + <&iommu M4U_PORT_VENC_REC_FRM_SET2>, + <&iommu M4U_PORT_VENC_BSDMA_SET2>, + <&iommu M4U_PORT_VENC_SV_COMA_SET2>, + <&iommu M4U_PORT_VENC_RD_COMA_SET2>, + <&iommu M4U_PORT_VENC_CUR_LUMA_SET2>, + <&iommu M4U_PORT_VENC_CUR_CHROMA_SET2>, + <&iommu M4U_PORT_VENC_REF_LUMA_SET2>, + <&iommu M4U_PORT_VENC_REC_CHROMA_SET2>; + mediatek,vpu = <&vpu>; + clocks = <&topckgen CLK_TOP_VENCPLL_D2>, + <&topckgen CLK_TOP_VENC_SEL>, + <&topckgen CLK_TOP_UNIVPLL1_D2>, + <&topckgen CLK_TOP_VENC_LT_SEL>; + clock-names = "venc_sel_src", + "venc_sel", + "venc_lt_sel_src", + "venc_lt_sel"; + }; diff --git a/Documentation/devicetree/bindings/media/mediatek-vpu.txt b/Documentation/devicetree/bindings/media/mediatek-vpu.txt new file mode 100644 index 0000000..2a5bac3 --- /dev/null +++ b/Documentation/devicetree/bindings/media/mediatek-vpu.txt @@ -0,0 +1,31 @@ +* Mediatek Video Processor Unit + +Video Processor Unit is a HW video controller. It controls HW Codec including +H.264/VP8/VP9 Decode, H.264/VP8 Encode and Image Processor (scale/rotate/color convert). + +Required properties: + - compatible: "mediatek,mt8173-vpu" + - reg: Must contain an entry for each entry in reg-names. + - reg-names: Must include the following entries: + "tcm": tcm base + "cfg_reg": Main configuration registers base + - interrupts: interrupt number to the cpu. + - clocks : clock name from clock manager + - clock-names: must be main. It is the main clock of VPU + +Optional properties: + - memory-region: phandle to a node describing memory (see + Documentation/devicetree/bindings/reserved-memory/reserved-memory.txt) + to be used for VPU extended memory; if not present, VPU may be located + anywhere in the memory + +Example: + vpu: vpu@10020000 { + compatible = "mediatek,mt8173-vpu"; + reg = <0 0x10020000 0 0x30000>, + <0 0x10050000 0 0x100>; + reg-names = "tcm", "cfg_reg"; + interrupts = <GIC_SPI 166 IRQ_TYPE_LEVEL_HIGH>; + clocks = <&topckgen TOP_SCP_SEL>; + clock-names = "main"; + }; diff --git a/Documentation/devicetree/bindings/media/renesas,fcp.txt b/Documentation/devicetree/bindings/media/renesas,fcp.txt new file mode 100644 index 0000000..6a12960 --- /dev/null +++ b/Documentation/devicetree/bindings/media/renesas,fcp.txt @@ -0,0 +1,32 @@ +Renesas R-Car Frame Compression Processor (FCP) +----------------------------------------------- + +The FCP is a companion module of video processing modules in the Renesas R-Car +Gen3 SoCs. It provides data compression and decompression, data caching, and +conversion of AXI transactions in order to reduce the memory bandwidth. + +There are three types of FCP: FCP for Codec (FCPC), FCP for VSP (FCPV) and FCP +for FDP (FCPF). Their configuration and behaviour depend on the module they +are paired with. These DT bindings currently support the FCPV only. + + - compatible: Must be one or more of the following + + - "renesas,r8a7795-fcpv" for R8A7795 (R-Car H3) compatible 'FCP for VSP' + - "renesas,fcpv" for generic compatible 'FCP for VSP' + + When compatible with the generic version, nodes must list the + SoC-specific version corresponding to the platform first, followed by the + family-specific and/or generic versions. + + - reg: the register base and size for the device registers + - clocks: Reference to the functional clock + + +Device node example +------------------- + + fcpvd1: fcp@fea2f000 { + compatible = "renesas,r8a7795-fcpv", "renesas,fcpv"; + reg = <0 0xfea2f000 0 0x200>; + clocks = <&cpg CPG_MOD 602>; + }; diff --git a/Documentation/devicetree/bindings/media/renesas,vsp1.txt b/Documentation/devicetree/bindings/media/renesas,vsp1.txt index 627405ab..9b695bc 100644 --- a/Documentation/devicetree/bindings/media/renesas,vsp1.txt +++ b/Documentation/devicetree/bindings/media/renesas,vsp1.txt @@ -14,6 +14,11 @@ Required properties: - interrupts: VSP interrupt specifier. - clocks: A phandle + clock-specifier pair for the VSP functional clock. +Optional properties: + + - renesas,fcp: A phandle referencing the FCP that handles memory accesses + for the VSP. Not needed on Gen2, mandatory on Gen3. + Example: R8A7790 (R-Car H2) VSP1-S node diff --git a/Documentation/devicetree/bindings/media/s5p-cec.txt b/Documentation/devicetree/bindings/media/s5p-cec.txt new file mode 100644 index 0000000..925ab4d --- /dev/null +++ b/Documentation/devicetree/bindings/media/s5p-cec.txt @@ -0,0 +1,31 @@ +* Samsung HDMI CEC driver + +The HDMI CEC module is present is Samsung SoCs and its purpose is to +handle communication between HDMI connected devices over the CEC bus. + +Required properties: + - compatible : value should be following + "samsung,s5p-cec" + + - reg : Physical base address of the IP registers and length of memory + mapped region. + + - interrupts : HDMI CEC interrupt number to the CPU. + - clocks : from common clock binding: handle to HDMI CEC clock. + - clock-names : from common clock binding: must contain "hdmicec", + corresponding to entry in the clocks property. + - samsung,syscon-phandle - phandle to the PMU system controller + +Example: + +hdmicec: cec@100B0000 { + compatible = "samsung,s5p-cec"; + reg = <0x100B0000 0x200>; + interrupts = <0 114 0>; + clocks = <&clock CLK_HDMI_CEC>; + clock-names = "hdmicec"; + samsung,syscon-phandle = <&pmu_system_controller>; + pinctrl-names = "default"; + pinctrl-0 = <&hdmi_cec>; + status = "okay"; +}; diff --git a/Documentation/devicetree/bindings/media/s5p-mfc.txt b/Documentation/devicetree/bindings/media/s5p-mfc.txt index 2d5787e..92c94f5 100644 --- a/Documentation/devicetree/bindings/media/s5p-mfc.txt +++ b/Documentation/devicetree/bindings/media/s5p-mfc.txt @@ -21,15 +21,18 @@ Required properties: - clock-names : from common clock binding: must contain "mfc", corresponding to entry in the clocks property. - - samsung,mfc-r : Base address of the first memory bank used by MFC - for DMA contiguous memory allocation and its size. - - - samsung,mfc-l : Base address of the second memory bank used by MFC - for DMA contiguous memory allocation and its size. - Optional properties: - power-domains : power-domain property defined with a phandle to respective power domain. + - memory-region : from reserved memory binding: phandles to two reserved + memory regions, first is for "left" mfc memory bus interfaces, + second if for the "right" mfc memory bus, used when no SYSMMU + support is available + +Obsolete properties: + - samsung,mfc-r, samsung,mfc-l : support removed, please use memory-region + property instead + Example: SoC specific DT entry: @@ -43,9 +46,29 @@ mfc: codec@13400000 { clock-names = "mfc"; }; +Reserved memory specific DT entry for given board (see reserved memory binding +for more information): + +reserved-memory { + #address-cells = <1>; + #size-cells = <1>; + ranges; + + mfc_left: region@51000000 { + compatible = "shared-dma-pool"; + no-map; + reg = <0x51000000 0x800000>; + }; + + mfc_right: region@43000000 { + compatible = "shared-dma-pool"; + no-map; + reg = <0x43000000 0x800000>; + }; +}; + Board specific DT entry: codec@13400000 { - samsung,mfc-r = <0x43000000 0x800000>; - samsung,mfc-l = <0x51000000 0x800000>; + memory-region = <&mfc_left>, <&mfc_right>; }; diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index 85a8fdc..c9b4959 100644 --- a/Documentation/video4linux/CARDLIST.cx23885 +++ b/Documentation/video4linux/CARDLIST.cx23885 @@ -54,3 +54,4 @@ 53 -> Hauppauge WinTV Starburst [0070:c12a] 54 -> ViewCast 260e [1576:0260] 55 -> ViewCast 460e [1576:0460] + 56 -> Hauppauge WinTV-quadHD (DVB) [0070:6a28,0070:6b28] diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt index 5e759ca..f930b80 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 Where foo->sd is of type struct v4l2_subdev. - And set all core control ops in your struct v4l2_subdev_core_ops to these - helpers: - - .queryctrl = v4l2_subdev_queryctrl, - .querymenu = v4l2_subdev_querymenu, - .g_ctrl = v4l2_subdev_g_ctrl, - .s_ctrl = v4l2_subdev_s_ctrl, - .g_ext_ctrls = v4l2_subdev_g_ext_ctrls, - .try_ext_ctrls = v4l2_subdev_try_ext_ctrls, - .s_ext_ctrls = v4l2_subdev_s_ext_ctrls, - - Note: this is a temporary solution only. Once all V4L2 drivers that depend - on subdev drivers are converted to the control framework these helpers will - no longer be needed. - 1.4) Clean up the handler at the end: v4l2_ctrl_handler_free(&foo->ctrl_handler); diff --git a/Documentation/video4linux/vivid.txt b/Documentation/video4linux/vivid.txt index 8da5d2a..1b26519 100644 --- a/Documentation/video4linux/vivid.txt +++ b/Documentation/video4linux/vivid.txt @@ -74,7 +74,8 @@ Section 11: Cropping, Composing, Scaling Section 12: Formats Section 13: Capture Overlay Section 14: Output Overlay -Section 15: Some Future Improvements +Section 15: CEC (Consumer Electronics Control) +Section 16: Some Future Improvements Section 1: Configuring the driver @@ -364,7 +365,11 @@ For HDMI inputs it is possible to set the EDID. By default a simple EDID is provided. You can only set the EDID for HDMI inputs. Internally, however, the EDID is shared between all HDMI inputs. -No interpretation is done of the EDID data. +No interpretation is done of the EDID data with the exception of the +physical address. See the CEC section for more details. + +There is a maximum of 15 HDMI inputs (if there are more, then they will be +reduced to 15) since that's the limitation of the EDID physical address. Section 3: Video Output @@ -409,6 +414,9 @@ standard, and for all others a 1:1 pixel aspect ratio is returned. An HDMI output has a valid EDID which can be obtained through VIDIOC_G_EDID. +There is a maximum of 15 HDMI outputs (if there are more, then they will be +reduced to 15) since that's the limitation of the EDID physical address. See +also the CEC section for more details. Section 4: VBI Capture ---------------------- @@ -1108,7 +1116,26 @@ capabilities will slow down the video loop considerably as a lot of checks have to be done per pixel. -Section 15: Some Future Improvements +Section 15: CEC (Consumer Electronics Control) +---------------------------------------------- + +If there are HDMI inputs then a CEC adapter will be created that has +the same number of input ports. This is the equivalent of e.g. a TV that +has that number of inputs. Each HDMI output will also create a +CEC adapter that is hooked up to the corresponding input port, or (if there +are more outputs than inputs) is not hooked up at all. In other words, +this is the equivalent of hooking up each output device to an input port of +the TV. Any remaining output devices remain unconnected. + +The EDID that each output reads reports a unique CEC physical address that is +based on the physical address of the EDID of the input. So if the EDID of the +receiver has physical address A.B.0.0, then each output will see an EDID +containing physical address A.B.C.0 where C is 1 to the number of inputs. If +there are more outputs than inputs then the remaining outputs have a CEC adapter +that is disabled and reports an invalid physical address. + + +Section 16: Some Future Improvements ------------------------------------ Just as a reminder and in no particular order: @@ -1121,8 +1148,6 @@ Just as a reminder and in no particular order: - Fix sequence/field numbering when looping of video with alternate fields - Add support for V4L2_CID_BG_COLOR for video outputs - Add ARGB888 overlay support: better testing of the alpha channel -- Add custom DV timings support -- Add support for V4L2_DV_FL_REDUCED_FPS - Improve pixel aspect support in the tpg code by passing a real v4l2_fract - Use per-queue locks and/or per-device locks to improve throughput - 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: - Make a thread for the RDS generation, that would help in particular for the "Controls" RDS Rx I/O Mode as the read-only RDS controls could be updated in real-time. +- Changing the EDID should cause hotplug detect emulation to happen. |
