summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/media/v4l/cec-ioc-receive.xml
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/media/v4l/cec-ioc-receive.xml')
-rw-r--r--Documentation/DocBook/media/v4l/cec-ioc-receive.xml274
1 files changed, 0 insertions, 274 deletions
diff --git a/Documentation/DocBook/media/v4l/cec-ioc-receive.xml b/Documentation/DocBook/media/v4l/cec-ioc-receive.xml
deleted file mode 100644
index fde9f8678e67..000000000000
--- a/Documentation/DocBook/media/v4l/cec-ioc-receive.xml
+++ /dev/null
@@ -1,274 +0,0 @@
-<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>