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/media/uapi/fdl-appendix.rst.
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
19 CEC_DQEVENT - Dequeue a CEC event
25 .. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp )
32 File descriptor returned by :c:func:`open() <cec-open>`.
40 CEC devices can send asynchronous events. These can be retrieved by
41 calling :c:func:`CEC_DQEVENT`. If the file descriptor is in
42 non-blocking mode and no event is pending, then it will return -1 and
43 set errno to the ``EAGAIN`` error code.
45 The internal event queues are per-filehandle and per-event type. If
46 there is no more room in a queue then the last event is overwritten with
47 the new one. This means that intermediate results can be thrown away but
48 that the latest event is always available. This also means that is it
49 possible to read two successive events that have the same value (e.g.
50 two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with
51 the same state). In that case the intermediate state changes were lost but
52 it is guaranteed that the state did change in between the two events.
54 .. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|
56 .. c:type:: cec_event_state_change
58 .. flat-table:: struct cec_event_state_change
65 - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no
66 valid physical address is set.
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.
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
83 .. c:type:: cec_event_lost_msgs
85 .. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}|
87 .. flat-table:: struct cec_event_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.
105 .. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}|
107 .. c:type:: cec_event
109 .. flat-table:: struct cec_event
116 - :cspan:`1`\ Timestamp of the event in ns.
118 The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock.
120 To access the same clock from userspace use :c:func:`clock_gettime`.
123 - :cspan:`1` The CEC event type, see :ref:`cec-events`.
126 - :cspan:`1` Event flags, see :ref:`cec-event-flags`.
132 - struct cec_event_state_change
134 - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>`
137 - struct cec_event_lost_msgs
139 - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>`
143 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
147 .. flat-table:: CEC Events Types
152 * .. _`CEC-EVENT-STATE-CHANGE`:
154 - ``CEC_EVENT_STATE_CHANGE``
156 - Generated when the CEC Adapter's state changes. When open() is
157 called an initial event will be generated for that filehandle with
158 the CEC Adapter's state at that time.
159 * .. _`CEC-EVENT-LOST-MSGS`:
161 - ``CEC_EVENT_LOST_MSGS``
163 - Generated if one or more CEC messages were lost because the
164 application didn't dequeue CEC messages fast enough.
165 * .. _`CEC-EVENT-PIN-CEC-LOW`:
167 - ``CEC_EVENT_PIN_CEC_LOW``
169 - Generated if the CEC pin goes from a high voltage to a low voltage.
170 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
172 * .. _`CEC-EVENT-PIN-CEC-HIGH`:
174 - ``CEC_EVENT_PIN_CEC_HIGH``
176 - Generated if the CEC pin goes from a low voltage to a high voltage.
177 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
179 * .. _`CEC-EVENT-PIN-HPD-LOW`:
181 - ``CEC_EVENT_PIN_HPD_LOW``
183 - Generated if the HPD pin goes from a high voltage to a low 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 low, then an initial event will be generated for that
188 * .. _`CEC-EVENT-PIN-HPD-HIGH`:
190 - ``CEC_EVENT_PIN_HPD_HIGH``
192 - Generated if the HPD pin goes from a low voltage to a high voltage.
193 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
194 capability set. When open() is called, the HPD pin can be read and
195 if the HPD is high, then an initial event will be generated for that
197 * .. _`CEC-EVENT-PIN-5V-LOW`:
199 - ``CEC_EVENT_PIN_5V_LOW``
201 - Generated if the 5V pin goes from a high voltage to a low 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 low, then an initial event will be generated for that
206 * .. _`CEC-EVENT-PIN-5V-HIGH`:
208 - ``CEC_EVENT_PIN_5V_HIGH``
210 - Generated if the 5V pin goes from a low voltage to a high voltage.
211 Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
212 capability set. When open() is called, the 5V pin can be read and
213 if the 5V is high, then an initial event will be generated for that
217 .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}|
221 .. flat-table:: CEC Event Flags
226 * .. _`CEC-EVENT-FL-INITIAL-STATE`:
228 - ``CEC_EVENT_FL_INITIAL_STATE``
230 - Set for the initial events that are generated when the device is
231 opened. See the table above for which events do this. This allows
232 applications to learn the initial state of the CEC adapter at
234 * .. _`CEC-EVENT-FL-DROPPED-EVENTS`:
236 - ``CEC_EVENT_FL_DROPPED_EVENTS``
238 - Set if one or more events of the given event type have been dropped.
239 This is an indication that the application cannot keep up.
246 On success 0 is returned, on error -1 and the ``errno`` variable is set
247 appropriately. The generic error codes are described at the
248 :ref:`Generic Error Codes <gen-errors>` chapter.
250 The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following
254 This is returned when the filehandle is in non-blocking mode and there
255 are no pending events.
258 An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for