forked from torvalds/linux
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[media] DocBook/media: add CEC documentation
Add DocBook documentation for the CEC API. Signed-off-by: Hans Verkuil <[email protected]> [[email protected]: add documentation for passthrough mode] [[email protected]: minor fixes and change of reserved field sizes] Signed-off-by: Kamil Debski <[email protected]> Signed-off-by: Hans Verkuil <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
- Loading branch information
Showing
15 changed files
with
1,732 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| <partinfo> | ||
| <authorgroup> | ||
| <author> | ||
| <firstname>Hans</firstname> | ||
| <surname>Verkuil</surname> | ||
| <affiliation><address><email>[email protected]</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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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> |
Oops, something went wrong.