Documentation/DocBook/media/v4l/cec-ioc-dqevent.xml

   1 <refentry id="cec-ioc-g-event">
   2   <refmeta>
   3     <refentrytitle>ioctl CEC_DQEVENT</refentrytitle>
   4     &manvol;
   5   </refmeta>
   6
   7   <refnamediv>
   8     <refname>CEC_DQEVENT</refname>
   9     <refpurpose>Dequeue a CEC event</refpurpose>
  10   </refnamediv>
  11
  12   <refsynopsisdiv>
  13     <funcsynopsis>
  14       <funcprototype>
  15         <funcdef>int <function>ioctl</function></funcdef>
  16         <paramdef>int <parameter>fd</parameter></paramdef>
  17         <paramdef>int <parameter>request</parameter></paramdef>
  18         <paramdef>struct cec_event *<parameter>argp</parameter></paramdef>
  19       </funcprototype>
  20     </funcsynopsis>
  21   </refsynopsisdiv>
  22
  23   <refsect1>
  24     <title>Arguments</title>
  25
  26     <variablelist>
  27       <varlistentry>
  28         <term><parameter>fd</parameter></term>
  29         <listitem>
  30           <para>File descriptor returned by
  31           <link linkend='cec-func-open'><function>open()</function></link>.</para>
  32         </listitem>
  33       </varlistentry>
  34       <varlistentry>
  35         <term><parameter>request</parameter></term>
  36         <listitem>
  37           <para>CEC_DQEVENT</para>
  38         </listitem>
  39       </varlistentry>
  40       <varlistentry>
  41         <term><parameter>argp</parameter></term>
  42         <listitem>
  43           <para></para>
  44         </listitem>
  45       </varlistentry>
  46     </variablelist>
  47   </refsect1>
  48
  49   <refsect1>
  50     <title>Description</title>
  51
  52     <para>
  53       Note: this documents the proposed CEC API. This API is not yet finalized and
  54       is currently only available as a staging kernel module.
  55     </para>
  56
  57     <para>CEC devices can send asynchronous events. These can be retrieved by calling
  58     the <constant>CEC_DQEVENT</constant> ioctl. If the file descriptor is in non-blocking
  59     mode and no event is pending, then it will return -1 and set errno to the &EAGAIN;.</para>
  60
  61     <para>The internal event queues are per-filehandle and per-event type. If there is
  62     no more room in a queue then the last event is overwritten with the new one. This
  63     means that intermediate results can be thrown away but that the latest event is always
  64     available. This also means that is it possible to read two successive events that have
  65     the same value (e.g. two CEC_EVENT_STATE_CHANGE events with the same state). In that
  66     case the intermediate state changes were lost but it is guaranteed that the state
  67     did change in between the two events.</para>
  68
  69     <table pgwide="1" frame="none" id="cec-event-state-change">
  70       <title>struct <structname>cec_event_state_change</structname></title>
  71       <tgroup cols="3">
  72         &cs-str;
  73         <tbody valign="top">
  74           <row>
  75             <entry>__u16</entry>
  76             <entry><structfield>phys_addr</structfield></entry>
  77             <entry>The current physical address.</entry>
  78           </row>
  79           <row>
  80             <entry>__u16</entry>
  81             <entry><structfield>log_addr_mask</structfield></entry>
  82             <entry>The current set of claimed logical addresses.</entry>
  83           </row>
  84         </tbody>
  85       </tgroup>
  86     </table>
  87
  88     <table pgwide="1" frame="none" id="cec-event-lost-msgs">
  89       <title>struct <structname>cec_event_lost_msgs</structname></title>
  90       <tgroup cols="3">
  91         &cs-str;
  92         <tbody valign="top">
  93           <row>
  94             <entry>__u32</entry>
  95             <entry><structfield>lost_msgs</structfield></entry>
  96             <entry>Set to the number of lost messages since the filehandle
  97             was opened or since the last time this event was dequeued for
  98             this filehandle. The messages lost are the oldest messages. So
  99             when a new message arrives and there is no more room, then the
 100             oldest message is discarded to make room for the new one. The
 101             internal size of the message queue guarantees that all messages
 102             received in the last two seconds will be stored. Since messages
 103             should be replied to within a second according to the CEC
 104             specification, this is more than enough.
 105             </entry>
 106           </row>
 107         </tbody>
 108       </tgroup>
 109     </table>
 110
 111     <table pgwide="1" frame="none" id="cec-event">
 112       <title>struct <structname>cec_event</structname></title>
 113       <tgroup cols="4">
 114         &cs-str;
 115         <tbody valign="top">
 116           <row>
 117             <entry>__u64</entry>
 118             <entry><structfield>ts</structfield></entry>
 119             <entry>Timestamp of the event in ns.</entry>
 120             <entry></entry>
 121           </row>
 122           <row>
 123             <entry>__u32</entry>
 124             <entry><structfield>event</structfield></entry>
 125             <entry>The CEC event type, see <xref linkend="cec-events" />.</entry>
 126             <entry></entry>
 127           </row>
 128           <row>
 129             <entry>__u32</entry>
 130             <entry><structfield>flags</structfield></entry>
 131             <entry>Event flags, see <xref linkend="cec-event-flags" />.</entry>
 132             <entry></entry>
 133           </row>
 134           <row>
 135             <entry>union</entry>
 136             <entry>(anonymous)</entry>
 137             <entry></entry>
 138             <entry></entry>
 139           </row>
 140           <row>
 141             <entry></entry>
 142             <entry>struct cec_event_state_change</entry>
 143             <entry><structfield>state_change</structfield></entry>
 144             <entry>The new adapter state as sent by the <constant>CEC_EVENT_STATE_CHANGE</constant>
 145             event.</entry>
 146           </row>
 147           <row>
 148             <entry></entry>
 149             <entry>struct cec_event_lost_msgs</entry>
 150             <entry><structfield>lost_msgs</structfield></entry>
 151             <entry>The number of lost messages as sent by the <constant>CEC_EVENT_LOST_MSGS</constant>
 152             event.</entry>
 153           </row>
 154         </tbody>
 155       </tgroup>
 156     </table>
 157
 158     <table pgwide="1" frame="none" id="cec-events">
 159       <title>CEC Events Types</title>
 160       <tgroup cols="3">
 161         &cs-def;
 162         <tbody valign="top">
 163           <row>
 164             <entry><constant>CEC_EVENT_STATE_CHANGE</constant></entry>
 165             <entry>1</entry>
 166             <entry>Generated when the CEC Adapter's state changes. When open() is
 167             called an initial event will be generated for that filehandle with the
 168             CEC Adapter's state at that time.
 169             </entry>
 170           </row>
 171           <row>
 172             <entry><constant>CEC_EVENT_LOST_MSGS</constant></entry>
 173             <entry>2</entry>
 174             <entry>Generated if one or more CEC messages were lost because the
 175             application didn't dequeue CEC messages fast enough.</entry>
 176           </row>
 177         </tbody>
 178       </tgroup>
 179     </table>
 180
 181     <table pgwide="1" frame="none" id="cec-event-flags">
 182       <title>CEC Event Flags</title>
 183       <tgroup cols="3">
 184         &cs-def;
 185         <tbody valign="top">
 186           <row>
 187             <entry><constant>CEC_EVENT_FL_INITIAL_VALUE</constant></entry>
 188             <entry>1</entry>
 189             <entry>Set for the initial events that are generated when the device is
 190             opened. See the table above for which events do this. This allows
 191             applications to learn the initial state of the CEC adapter at open()
 192             time.</entry>
 193           </row>
 194         </tbody>
 195       </tgroup>
 196     </table>
 197   </refsect1>
 198
 199   <refsect1>
 200     &return-value;
 201   </refsect1>
 202 </refentry>