Commit | Line | Data |
---|---|---|
82559ac0 MCC |
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. | |
7 | .. | |
8 | .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections | |
9 | ||
21c62694 | 10 | .. _CEC_DQEVENT: |
e2460b1d MH |
11 | |
12 | ***************** | |
13 | ioctl CEC_DQEVENT | |
14 | ***************** | |
15 | ||
21c62694 MH |
16 | Name |
17 | ==== | |
e2460b1d | 18 | |
21c62694 | 19 | CEC_DQEVENT - Dequeue a CEC event |
e2460b1d MH |
20 | |
21 | ||
22 | Synopsis | |
23 | ======== | |
24 | ||
99547836 MCC |
25 | .. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp ) |
26 | :name: CEC_DQEVENT | |
e2460b1d MH |
27 | |
28 | Arguments | |
29 | ========= | |
30 | ||
31 | ``fd`` | |
cfaf384b | 32 | File descriptor returned by :c:func:`open() <cec-open>`. |
e2460b1d | 33 | |
e2460b1d MH |
34 | ``argp`` |
35 | ||
36 | ||
37 | Description | |
38 | =========== | |
39 | ||
e2460b1d | 40 | CEC devices can send asynchronous events. These can be retrieved by |
9cd3476c | 41 | calling :c:func:`CEC_DQEVENT`. If the file descriptor is in |
e2460b1d | 42 | non-blocking mode and no event is pending, then it will return -1 and |
e5208ed2 | 43 | set errno to the ``EAGAIN`` error code. |
e2460b1d MH |
44 | |
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. | |
cc0fe5cd MCC |
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. | |
e2460b1d | 53 | |
fa92b04d | 54 | .. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| |
e2460b1d | 55 | |
94d71e58 | 56 | .. c:type:: cec_event_state_change |
e2460b1d MH |
57 | |
58 | .. flat-table:: struct cec_event_state_change | |
59 | :header-rows: 0 | |
60 | :stub-columns: 0 | |
b2a58436 | 61 | :widths: 1 1 8 |
e2460b1d | 62 | |
77edf603 HV |
63 | * - __u16 |
64 | - ``phys_addr`` | |
65 | - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no | |
b94dffd6 | 66 | valid physical address is set. |
77edf603 HV |
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. | |
98f29073 DM |
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. | |
e2460b1d MH |
81 | |
82 | ||
94d71e58 | 83 | .. c:type:: cec_event_lost_msgs |
e2460b1d | 84 | |
9fce0c22 | 85 | .. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| |
e2460b1d MH |
86 | |
87 | .. flat-table:: struct cec_event_lost_msgs | |
88 | :header-rows: 0 | |
89 | :stub-columns: 0 | |
b2a58436 | 90 | :widths: 1 1 16 |
e2460b1d | 91 | |
77edf603 HV |
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. | |
e2460b1d MH |
103 | |
104 | ||
f9894207 | 105 | .. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.6cm}| |
e2460b1d | 106 | |
e8be7e97 | 107 | .. c:type:: cec_event |
e2460b1d MH |
108 | |
109 | .. flat-table:: struct cec_event | |
110 | :header-rows: 0 | |
111 | :stub-columns: 0 | |
218fc9f2 | 112 | :widths: 1 1 8 |
e2460b1d | 113 | |
77edf603 HV |
114 | * - __u64 |
115 | - ``ts`` | |
218fc9f2 | 116 | - Timestamp of the event in ns. |
77edf603 | 117 | |
f9894207 MCC |
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`. | |
77edf603 HV |
121 | * - __u32 |
122 | - ``event`` | |
218fc9f2 | 123 | - The CEC event type, see :ref:`cec-events`. |
77edf603 HV |
124 | * - __u32 |
125 | - ``flags`` | |
218fc9f2 HV |
126 | - Event flags, see :ref:`cec-event-flags`. |
127 | * - union { | |
77edf603 | 128 | - (anonymous) |
218fc9f2 | 129 | * - struct cec_event_state_change |
77edf603 HV |
130 | - ``state_change`` |
131 | - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` | |
132 | event. | |
218fc9f2 | 133 | * - struct cec_event_lost_msgs |
77edf603 HV |
134 | - ``lost_msgs`` |
135 | - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>` | |
136 | event. | |
218fc9f2 HV |
137 | * - } |
138 | - | |
e2460b1d MH |
139 | |
140 | ||
fa92b04d | 141 | .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| |
e2460b1d MH |
142 | |
143 | .. _cec-events: | |
144 | ||
145 | .. flat-table:: CEC Events Types | |
146 | :header-rows: 0 | |
147 | :stub-columns: 0 | |
b2a58436 | 148 | :widths: 3 1 16 |
e2460b1d | 149 | |
77edf603 | 150 | * .. _`CEC-EVENT-STATE-CHANGE`: |
e2460b1d | 151 | |
77edf603 HV |
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`: | |
e2460b1d | 158 | |
77edf603 HV |
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. | |
9a6b2a87 | 163 | * .. _`CEC-EVENT-PIN-CEC-LOW`: |
fdb8c88e | 164 | |
9a6b2a87 | 165 | - ``CEC_EVENT_PIN_CEC_LOW`` |
fdb8c88e HV |
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. | |
9a6b2a87 | 170 | * .. _`CEC-EVENT-PIN-CEC-HIGH`: |
fdb8c88e | 171 | |
9a6b2a87 | 172 | - ``CEC_EVENT_PIN_CEC_HIGH`` |
fdb8c88e HV |
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. | |
00f7adff HV |
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. | |
5105b484 HV |
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. | |
e2460b1d MH |
213 | |
214 | ||
fa92b04d | 215 | .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| |
e2460b1d MH |
216 | |
217 | .. _cec-event-flags: | |
218 | ||
219 | .. flat-table:: CEC Event Flags | |
220 | :header-rows: 0 | |
221 | :stub-columns: 0 | |
b2a58436 | 222 | :widths: 3 1 8 |
e2460b1d | 223 | |
9a59d936 | 224 | * .. _`CEC-EVENT-FL-INITIAL-STATE`: |
e2460b1d | 225 | |
9a59d936 | 226 | - ``CEC_EVENT_FL_INITIAL_STATE`` |
77edf603 HV |
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. | |
fdb8c88e HV |
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. | |
e2460b1d MH |
238 | |
239 | ||
240 | ||
241 | Return Value | |
242 | ============ | |
243 | ||
244 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
245 | appropriately. The generic error codes are described at the | |
246 | :ref:`Generic Error Codes <gen-errors>` chapter. | |
491314b8 HV |
247 | |
248 | The :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>` can return the following | |
249 | error codes: | |
250 | ||
251 | EAGAIN | |
252 | This is returned when the filehandle is in non-blocking mode and there | |
253 | are no pending events. | |
254 | ||
255 | ERESTARTSYS | |
256 | An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for | |
257 | events to arrive. |