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