Documentation/media/uapi/cec/cec-ioc-dqevent.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _CEC_DQEVENT:
   4
   5 *****************
   6 ioctl CEC_DQEVENT
   7 *****************
   8
   9 Name
  10 ====
  11
  12 CEC_DQEVENT - Dequeue a CEC event
  13
  14
  15 Synopsis
  16 ========
  17
  18 .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )
  19
  20 Arguments
  21 =========
  22
  23 ``fd``
  24     File descriptor returned by :ref:`open() <cec-func-open>`.
  25
  26 ``request``
  27     CEC_DQEVENT
  28
  29 ``argp``
  30
  31
  32 Description
  33 ===========
  34
  35 .. note::
  36
  37    This documents the proposed CEC API. This API is not yet finalized
  38    and is currently only available as a staging kernel module.
  39
  40 CEC devices can send asynchronous events. These can be retrieved by
  41 calling :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>`. If the file descriptor is in
  42 non-blocking mode and no event is pending, then it will return -1 and
  43 set errno to the ``EAGAIN`` error code.
  44
  45 The internal event queues are per-filehandle and per-event type. If
  46 there is no more room in a queue then the last event is overwritten with
  47 the new one. This means that intermediate results can be thrown away but
  48 that the latest event is always available. This also means that is it
  49 possible to read two successive events that have the same value (e.g.
  50 two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with
  51 the same state). In that case the intermediate state changes were lost but
  52 it is guaranteed that the state did change in between the two events.
  53
  54 .. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|
  55
  56 .. _cec-event-state-change_s:
  57
  58 .. flat-table:: struct cec_event_state_change
  59     :header-rows:  0
  60     :stub-columns: 0
  61     :widths:       1 1 8
  62
  63
  64     -  .. row 1
  65
  66        -  __u16
  67
  68        -  ``phys_addr``
  69
  70        -  The current physical address.
  71
  72     -  .. row 2
  73
  74        -  __u16
  75
  76        -  ``log_addr_mask``
  77
  78        -  The current set of claimed logical addresses.
  79
  80
  81 .. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}|
  82
  83 .. _cec-event-lost-msgs_s:
  84
  85 .. flat-table:: struct cec_event_lost_msgs
  86     :header-rows:  0
  87     :stub-columns: 0
  88     :widths:       1 1 16
  89
  90
  91     -  .. row 1
  92
  93        -  __u32
  94
  95        -  ``lost_msgs``
  96
  97        -  Set to the number of lost messages since the filehandle was opened
  98           or since the last time this event was dequeued for this
  99           filehandle. The messages lost are the oldest messages. So when a
 100           new message arrives and there is no more room, then the oldest
 101           message is discarded to make room for the new one. The internal
 102           size of the message queue guarantees that all messages received in
 103           the last two seconds will be stored. Since messages should be
 104           replied to within a second according to the CEC specification,
 105           this is more than enough.
 106
 107
 108 .. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{2.5cm}|p{8.8cm}|
 109
 110 .. _cec-event:
 111
 112 .. flat-table:: struct cec_event
 113     :header-rows:  0
 114     :stub-columns: 0
 115     :widths:       1 1 1 8
 116
 117
 118     -  .. row 1
 119
 120        -  __u64
 121
 122        -  ``ts``
 123
 124        -  :cspan:`1` Timestamp of the event in ns.
 125
 126           The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
 127           the same clock from userspace use :c:func:`clock_gettime(2)`.
 128
 129     -  .. row 2
 130
 131        -  __u32
 132
 133        -  ``event``
 134
 135        -  :cspan:`1` The CEC event type, see :ref:`cec-events`.
 136
 137     -  .. row 3
 138
 139        -  __u32
 140
 141        -  ``flags``
 142
 143        -  :cspan:`1` Event flags, see :ref:`cec-event-flags`.
 144
 145     -  .. row 4
 146
 147        -  union
 148
 149        -  (anonymous)
 150
 151        -
 152        -
 153
 154     -  .. row 5
 155
 156        -
 157        -  struct cec_event_state_change
 158
 159        -  ``state_change``
 160
 161        -  The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>`
 162           event.
 163
 164     -  .. row 6
 165
 166        -
 167        -  struct cec_event_lost_msgs
 168
 169        -  ``lost_msgs``
 170
 171        -  The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>`
 172           event.
 173
 174
 175 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 176
 177 .. _cec-events:
 178
 179 .. flat-table:: CEC Events Types
 180     :header-rows:  0
 181     :stub-columns: 0
 182     :widths:       3 1 16
 183
 184
 185     -  .. _`CEC-EVENT-STATE-CHANGE`:
 186
 187        -  ``CEC_EVENT_STATE_CHANGE``
 188
 189        -  1
 190
 191        -  Generated when the CEC Adapter's state changes. When open() is
 192           called an initial event will be generated for that filehandle with
 193           the CEC Adapter's state at that time.
 194
 195     -  .. _`CEC-EVENT-LOST-MSGS`:
 196
 197        -  ``CEC_EVENT_LOST_MSGS``
 198
 199        -  2
 200
 201        -  Generated if one or more CEC messages were lost because the
 202           application didn't dequeue CEC messages fast enough.
 203
 204
 205 .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}|
 206
 207 .. _cec-event-flags:
 208
 209 .. flat-table:: CEC Event Flags
 210     :header-rows:  0
 211     :stub-columns: 0
 212     :widths:       3 1 8
 213
 214
 215     -  .. _`CEC-EVENT-FL-INITIAL-VALUE`:
 216
 217        -  ``CEC_EVENT_FL_INITIAL_VALUE``
 218
 219        -  1
 220
 221        -  Set for the initial events that are generated when the device is
 222           opened. See the table above for which events do this. This allows
 223           applications to learn the initial state of the CEC adapter at
 224           open() time.
 225
 226
 227
 228 Return Value
 229 ============
 230
 231 On success 0 is returned, on error -1 and the ``errno`` variable is set
 232 appropriately. The generic error codes are described at the
 233 :ref:`Generic Error Codes <gen-errors>` chapter.