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