tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. -*- coding: utf-8; mode: rst -*-
2
3.. _CEC_DQEVENT:
4
5*****************
6ioctl CEC_DQEVENT
7*****************
8
9Name
10====
11
12CEC_DQEVENT - Dequeue a CEC event
13
14
15Synopsis
16========
17
18.. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )
19
20Arguments
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
32Description
33===========
34
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.
37
38CEC devices can send asynchronous events. These can be retrieved by
39calling :ref:`ioctl CEC_DQEVENT <CEC_DQEVENT>`. If the file descriptor is in
40non-blocking mode and no event is pending, then it will return -1 and
41set errno to the ``EAGAIN`` error code.
42
43The internal event queues are per-filehandle and per-event type. If
44there is no more room in a queue then the last event is overwritten with
45the new one. This means that intermediate results can be thrown away but
46that the latest event is always available. This also means that is it
47possible to read two successive events that have the same value (e.g.
48two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with
49the same state). In that case the intermediate state changes were lost but
50it is guaranteed that the state did change in between the two events.
51
52
53.. _cec-event-state-change_s:
54
55.. flat-table:: struct cec_event_state_change
56 :header-rows: 0
57 :stub-columns: 0
58 :widths: 1 1 8
59
60
61 - .. row 1
62
63 - __u16
64
65 - ``phys_addr``
66
67 - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no
68 valid physical address is set.
69
70 - .. row 2
71
72 - __u16
73
74 - ``log_addr_mask``
75
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.
80
81
82
83.. _cec-event-lost-msgs_s:
84
85.. flat-table:: struct cec_event_lost_msgs
86 :header-rows: 0
87 :stub-columns: 0
88 :widths: 1 1 16
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
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.
106
107
108
109.. _cec-event:
110
111.. flat-table:: struct cec_event
112 :header-rows: 0
113 :stub-columns: 0
114 :widths: 1 1 1 8
115
116
117 - .. row 1
118
119 - __u64
120
121 - ``ts``
122
123 - Timestamp of the event in ns.
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)`.
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
165 - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>`
166 event.
167
168 - .. row 6
169
170 -
171 - struct cec_event_lost_msgs
172
173 - ``lost_msgs``
174
175 - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>`
176 event.
177
178
179
180.. _cec-events:
181
182.. flat-table:: CEC Events Types
183 :header-rows: 0
184 :stub-columns: 0
185 :widths: 3 1 16
186
187
188 - .. _`CEC-EVENT-STATE-CHANGE`:
189
190 - ``CEC_EVENT_STATE_CHANGE``
191
192 - 1
193
194 - Generated when the CEC Adapter's state changes. When open() is
195 called an initial event will be generated for that filehandle with
196 the CEC Adapter's state at that time.
197
198 - .. _`CEC-EVENT-LOST-MSGS`:
199
200 - ``CEC_EVENT_LOST_MSGS``
201
202 - 2
203
204 - Generated if one or more CEC messages were lost because the
205 application didn't dequeue CEC messages fast enough.
206
207
208
209.. _cec-event-flags:
210
211.. flat-table:: CEC Event Flags
212 :header-rows: 0
213 :stub-columns: 0
214 :widths: 3 1 8
215
216
217 - .. _`CEC-EVENT-FL-INITIAL-VALUE`:
218
219 - ``CEC_EVENT_FL_INITIAL_VALUE``
220
221 - 1
222
223 - Set for the initial events that are generated when the device is
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.
227
228
229
230Return Value
231============
232
233On success 0 is returned, on error -1 and the ``errno`` variable is set
234appropriately. The generic error codes are described at the
235:ref:`Generic Error Codes <gen-errors>` chapter.