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