Commit | Line | Data |
---|---|---|
e2460b1d MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
21c62694 | 3 | .. _CEC_DQEVENT: |
e2460b1d MH |
4 | |
5 | ***************** | |
6 | ioctl CEC_DQEVENT | |
7 | ***************** | |
8 | ||
21c62694 MH |
9 | Name |
10 | ==== | |
e2460b1d | 11 | |
21c62694 | 12 | CEC_DQEVENT - Dequeue a CEC event |
e2460b1d MH |
13 | |
14 | ||
15 | Synopsis | |
16 | ======== | |
17 | ||
21c62694 | 18 | .. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp ) |
e2460b1d MH |
19 | |
20 | Arguments | |
21 | ========= | |
22 | ||
23 | ``fd`` | |
24 | File descriptor returned by :ref:`open() <cec-func-open>`. | |
25 | ||
26 | ``request`` | |
27 | CEC_DQEVENT | |
28 | ||
29 | ``argp`` | |
30 | ||
31 | ||
32 | Description | |
33 | =========== | |
34 | ||
706f8a99 MCC |
35 | .. note:: This documents the proposed CEC API. This API is not yet finalized |
36 | and is currently only available as a staging kernel module. | |
e2460b1d MH |
37 | |
38 | CEC devices can send asynchronous events. These can be retrieved by | |
1267c60a | 39 | calling :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>`. If the file descriptor is in |
e2460b1d | 40 | non-blocking mode and no event is pending, then it will return -1 and |
e5208ed2 | 41 | set errno to the ``EAGAIN`` error code. |
e2460b1d MH |
42 | |
43 | The internal event queues are per-filehandle and per-event type. If | |
44 | there is no more room in a queue then the last event is overwritten with | |
45 | the new one. This means that intermediate results can be thrown away but | |
46 | that the latest event is always available. This also means that is it | |
47 | possible to read two successive events that have the same value (e.g. | |
cc0fe5cd MCC |
48 | two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with |
49 | the same state). In that case the intermediate state changes were lost but | |
50 | it is guaranteed that the state did change in between the two events. | |
e2460b1d MH |
51 | |
52 | ||
96f69e0e | 53 | .. _cec-event-state-change_s: |
e2460b1d MH |
54 | |
55 | .. flat-table:: struct cec_event_state_change | |
56 | :header-rows: 0 | |
57 | :stub-columns: 0 | |
b2a58436 | 58 | :widths: 1 1 8 |
e2460b1d MH |
59 | |
60 | ||
61 | - .. row 1 | |
62 | ||
63 | - __u16 | |
64 | ||
65 | - ``phys_addr`` | |
66 | ||
277f963c HV |
67 | - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no |
68 | valid physical address is set. | |
e2460b1d MH |
69 | |
70 | - .. row 2 | |
71 | ||
72 | - __u16 | |
73 | ||
74 | - ``log_addr_mask`` | |
75 | ||
277f963c HV |
76 | - The current set of claimed logical addresses. This is 0 if no logical |
77 | addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``. | |
78 | If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device | |
79 | has the unregistered logical address. In that case all other bits are 0. | |
e2460b1d MH |
80 | |
81 | ||
82 | ||
96f69e0e | 83 | .. _cec-event-lost-msgs_s: |
e2460b1d MH |
84 | |
85 | .. flat-table:: struct cec_event_lost_msgs | |
86 | :header-rows: 0 | |
87 | :stub-columns: 0 | |
b2a58436 | 88 | :widths: 1 1 16 |
e2460b1d MH |
89 | |
90 | ||
91 | - .. row 1 | |
92 | ||
93 | - __u32 | |
94 | ||
95 | - ``lost_msgs`` | |
96 | ||
97 | - Set to the number of lost messages since the filehandle was opened | |
706f8a99 MCC |
98 | or since the last time this event was dequeued for this |
99 | filehandle. The messages lost are the oldest messages. So when a | |
100 | new message arrives and there is no more room, then the oldest | |
101 | message is discarded to make room for the new one. The internal | |
102 | size of the message queue guarantees that all messages received in | |
103 | the last two seconds will be stored. Since messages should be | |
104 | replied to within a second according to the CEC specification, | |
105 | this is more than enough. | |
e2460b1d MH |
106 | |
107 | ||
108 | ||
109 | .. _cec-event: | |
110 | ||
111 | .. flat-table:: struct cec_event | |
112 | :header-rows: 0 | |
113 | :stub-columns: 0 | |
b2a58436 | 114 | :widths: 1 1 1 8 |
e2460b1d MH |
115 | |
116 | ||
117 | - .. row 1 | |
118 | ||
119 | - __u64 | |
120 | ||
121 | - ``ts`` | |
122 | ||
123 | - Timestamp of the event in ns. | |
e5208ed2 HV |
124 | The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access |
125 | the same clock from userspace use :c:func:`clock_gettime(2)`. | |
e2460b1d MH |
126 | |
127 | - | |
128 | ||
129 | - .. row 2 | |
130 | ||
131 | - __u32 | |
132 | ||
133 | - ``event`` | |
134 | ||
135 | - The CEC event type, see :ref:`cec-events`. | |
136 | ||
137 | - | |
138 | ||
139 | - .. row 3 | |
140 | ||
141 | - __u32 | |
142 | ||
143 | - ``flags`` | |
144 | ||
145 | - Event flags, see :ref:`cec-event-flags`. | |
146 | ||
147 | - | |
148 | ||
149 | - .. row 4 | |
150 | ||
151 | - union | |
152 | ||
153 | - (anonymous) | |
154 | ||
155 | - | |
156 | - | |
157 | ||
158 | - .. row 5 | |
159 | ||
160 | - | |
161 | - struct cec_event_state_change | |
162 | ||
163 | - ``state_change`` | |
164 | ||
96f69e0e | 165 | - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` |
706f8a99 | 166 | event. |
e2460b1d MH |
167 | |
168 | - .. row 6 | |
169 | ||
170 | - | |
171 | - struct cec_event_lost_msgs | |
172 | ||
173 | - ``lost_msgs`` | |
174 | ||
96f69e0e | 175 | - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>` |
706f8a99 | 176 | event. |
e2460b1d MH |
177 | |
178 | ||
179 | ||
180 | .. _cec-events: | |
181 | ||
182 | .. flat-table:: CEC Events Types | |
183 | :header-rows: 0 | |
184 | :stub-columns: 0 | |
b2a58436 | 185 | :widths: 3 1 16 |
e2460b1d MH |
186 | |
187 | ||
96f69e0e | 188 | - .. _`CEC-EVENT-STATE-CHANGE`: |
e2460b1d MH |
189 | |
190 | - ``CEC_EVENT_STATE_CHANGE`` | |
191 | ||
192 | - 1 | |
193 | ||
194 | - Generated when the CEC Adapter's state changes. When open() is | |
706f8a99 MCC |
195 | called an initial event will be generated for that filehandle with |
196 | the CEC Adapter's state at that time. | |
e2460b1d | 197 | |
96f69e0e | 198 | - .. _`CEC-EVENT-LOST-MSGS`: |
e2460b1d MH |
199 | |
200 | - ``CEC_EVENT_LOST_MSGS`` | |
201 | ||
202 | - 2 | |
203 | ||
204 | - Generated if one or more CEC messages were lost because the | |
706f8a99 | 205 | application didn't dequeue CEC messages fast enough. |
e2460b1d MH |
206 | |
207 | ||
208 | ||
209 | .. _cec-event-flags: | |
210 | ||
211 | .. flat-table:: CEC Event Flags | |
212 | :header-rows: 0 | |
213 | :stub-columns: 0 | |
b2a58436 | 214 | :widths: 3 1 8 |
e2460b1d MH |
215 | |
216 | ||
96f69e0e | 217 | - .. _`CEC-EVENT-FL-INITIAL-VALUE`: |
e2460b1d MH |
218 | |
219 | - ``CEC_EVENT_FL_INITIAL_VALUE`` | |
220 | ||
221 | - 1 | |
222 | ||
223 | - Set for the initial events that are generated when the device is | |
706f8a99 MCC |
224 | opened. See the table above for which events do this. This allows |
225 | applications to learn the initial state of the CEC adapter at | |
226 | open() time. | |
e2460b1d MH |
227 | |
228 | ||
229 | ||
230 | Return Value | |
231 | ============ | |
232 | ||
233 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
234 | appropriately. The generic error codes are described at the | |
235 | :ref:`Generic Error Codes <gen-errors>` chapter. |