| <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> |