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 | ||
99547836 MCC |
18 | .. c:function:: int ioctl( int fd, CEC_DQEVENT, struct cec_event *argp ) |
19 | :name: CEC_DQEVENT | |
e2460b1d MH |
20 | |
21 | Arguments | |
22 | ========= | |
23 | ||
24 | ``fd`` | |
25 | File descriptor returned by :ref:`open() <cec-func-open>`. | |
26 | ||
e2460b1d MH |
27 | ``argp`` |
28 | ||
29 | ||
30 | Description | |
31 | =========== | |
32 | ||
b6b6e678 MCC |
33 | .. note:: |
34 | ||
35 | This documents the proposed CEC API. This API is not yet finalized | |
706f8a99 | 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 | |
9cd3476c | 39 | calling :c:func:`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 | 51 | |
fa92b04d | 52 | .. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}| |
e2460b1d | 53 | |
94d71e58 | 54 | .. c:type:: cec_event_state_change |
e2460b1d MH |
55 | |
56 | .. flat-table:: struct cec_event_state_change | |
57 | :header-rows: 0 | |
58 | :stub-columns: 0 | |
b2a58436 | 59 | :widths: 1 1 8 |
e2460b1d MH |
60 | |
61 | ||
62 | - .. row 1 | |
63 | ||
64 | - __u16 | |
65 | ||
66 | - ``phys_addr`` | |
67 | ||
277f963c HV |
68 | - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no |
69 | valid physical address is set. | |
e2460b1d MH |
70 | |
71 | - .. row 2 | |
72 | ||
73 | - __u16 | |
74 | ||
75 | - ``log_addr_mask`` | |
76 | ||
277f963c HV |
77 | - The current set of claimed logical addresses. This is 0 if no logical |
78 | addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``. | |
79 | If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device | |
80 | has the unregistered logical address. In that case all other bits are 0. | |
e2460b1d MH |
81 | |
82 | ||
fa92b04d | 83 | .. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.5cm}| |
e2460b1d | 84 | |
94d71e58 | 85 | .. c:type:: cec_event_lost_msgs |
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 MH |
91 | |
92 | ||
93 | - .. row 1 | |
94 | ||
95 | - __u32 | |
96 | ||
97 | - ``lost_msgs`` | |
98 | ||
99 | - Set to the number of lost messages since the filehandle was opened | |
706f8a99 MCC |
100 | or since the last time this event was dequeued for this |
101 | filehandle. The messages lost are the oldest messages. So when a | |
102 | new message arrives and there is no more room, then the oldest | |
103 | message is discarded to make room for the new one. The internal | |
104 | size of the message queue guarantees that all messages received in | |
105 | the last two seconds will be stored. Since messages should be | |
106 | replied to within a second according to the CEC specification, | |
107 | this is more than enough. | |
e2460b1d MH |
108 | |
109 | ||
fa92b04d | 110 | .. tabularcolumns:: |p{1.0cm}|p{4.2cm}|p{2.5cm}|p{8.8cm}| |
e2460b1d | 111 | |
e8be7e97 | 112 | .. c:type:: cec_event |
e2460b1d MH |
113 | |
114 | .. flat-table:: struct cec_event | |
115 | :header-rows: 0 | |
116 | :stub-columns: 0 | |
b2a58436 | 117 | :widths: 1 1 1 8 |
e2460b1d MH |
118 | |
119 | ||
120 | - .. row 1 | |
121 | ||
122 | - __u64 | |
123 | ||
124 | - ``ts`` | |
125 | ||
0d6821ec | 126 | - :cspan:`1` Timestamp of the event in ns. |
e2460b1d | 127 | |
e5208ed2 | 128 | The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access |
39b6b900 | 129 | the same clock from userspace use :c:func:`clock_gettime`. |
e2460b1d MH |
130 | |
131 | - .. row 2 | |
132 | ||
133 | - __u32 | |
134 | ||
135 | - ``event`` | |
136 | ||
0d6821ec | 137 | - :cspan:`1` The CEC event type, see :ref:`cec-events`. |
e2460b1d MH |
138 | |
139 | - .. row 3 | |
140 | ||
141 | - __u32 | |
142 | ||
143 | - ``flags`` | |
144 | ||
0d6821ec | 145 | - :cspan:`1` Event flags, see :ref:`cec-event-flags`. |
e2460b1d MH |
146 | |
147 | - .. row 4 | |
148 | ||
149 | - union | |
150 | ||
151 | - (anonymous) | |
152 | ||
153 | - | |
154 | - | |
155 | ||
156 | - .. row 5 | |
157 | ||
158 | - | |
159 | - struct cec_event_state_change | |
160 | ||
161 | - ``state_change`` | |
162 | ||
96f69e0e | 163 | - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` |
706f8a99 | 164 | event. |
e2460b1d MH |
165 | |
166 | - .. row 6 | |
167 | ||
168 | - | |
169 | - struct cec_event_lost_msgs | |
170 | ||
171 | - ``lost_msgs`` | |
172 | ||
96f69e0e | 173 | - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>` |
706f8a99 | 174 | event. |
e2460b1d MH |
175 | |
176 | ||
fa92b04d | 177 | .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| |
e2460b1d MH |
178 | |
179 | .. _cec-events: | |
180 | ||
181 | .. flat-table:: CEC Events Types | |
182 | :header-rows: 0 | |
183 | :stub-columns: 0 | |
b2a58436 | 184 | :widths: 3 1 16 |
e2460b1d MH |
185 | |
186 | ||
96f69e0e | 187 | - .. _`CEC-EVENT-STATE-CHANGE`: |
e2460b1d MH |
188 | |
189 | - ``CEC_EVENT_STATE_CHANGE`` | |
190 | ||
191 | - 1 | |
192 | ||
193 | - Generated when the CEC Adapter's state changes. When open() is | |
706f8a99 MCC |
194 | called an initial event will be generated for that filehandle with |
195 | the CEC Adapter's state at that time. | |
e2460b1d | 196 | |
96f69e0e | 197 | - .. _`CEC-EVENT-LOST-MSGS`: |
e2460b1d MH |
198 | |
199 | - ``CEC_EVENT_LOST_MSGS`` | |
200 | ||
201 | - 2 | |
202 | ||
203 | - Generated if one or more CEC messages were lost because the | |
706f8a99 | 204 | application didn't dequeue CEC messages fast enough. |
e2460b1d MH |
205 | |
206 | ||
fa92b04d | 207 | .. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.9cm}| |
e2460b1d MH |
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. |