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