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