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