Documentation/userspace-api/media/cec/cec-ioc-dqevent.rst

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