tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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_TRANSMIT:
11.. _CEC_RECEIVE:
12
13***********************************
14ioctls CEC_RECEIVE and CEC_TRANSMIT
15***********************************
16
17Name
18====
19
20CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
21
22
23Synopsis
24========
25
26.. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg \*argp )
27 :name: CEC_RECEIVE
28
29.. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg \*argp )
30 :name: CEC_TRANSMIT
31
32Arguments
33=========
34
35``fd``
36 File descriptor returned by :c:func:`open() <cec-open>`.
37
38``argp``
39 Pointer to struct cec_msg.
40
41Description
42===========
43
44To receive a CEC message the application has to fill in the
45``timeout`` field of struct :c:type:`cec_msg` and pass it to
46:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
47If the file descriptor is in non-blocking mode and there are no received
48messages pending, then it will return -1 and set errno to the ``EAGAIN``
49error code. If the file descriptor is in blocking mode and ``timeout``
50is non-zero and no message arrived within ``timeout`` milliseconds, then
51it will return -1 and set errno to the ``ETIMEDOUT`` error code.
52
53A received message can be:
54
551. a message received from another CEC device (the ``sequence`` field will
56 be 0).
572. the result of an earlier non-blocking transmit (the ``sequence`` field will
58 be non-zero).
59
60To send a CEC message the application has to fill in the struct
61:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
62The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if
63``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
64queue, then it will return -1 and set errno to the ``EBUSY`` error code.
65The transmit queue has enough room for 18 messages (about 1 second worth
66of 2-byte messages). Note that the CEC kernel framework will also reply
67to core messages (see :ref:`cec-core-processing`), so it is not a good
68idea to fully fill up the transmit queue.
69
70If the file descriptor is in non-blocking mode then the transmit will
71return 0 and the result of the transmit will be available via
72:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished
73(including waiting for a reply, if requested).
74
75The ``sequence`` field is filled in for every transmit and this can be
76checked against the received messages to find the corresponding transmit
77result.
78
79Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical
80address is invalid (due to e.g. a disconnect) will return ``ENONET``.
81
82However, the CEC specification allows sending messages from 'Unregistered' to
83'TV' when the physical address is invalid since some TVs pull the hotplug detect
84pin of the HDMI connector low when they go into standby, or when switching to
85another input.
86
87When the hotplug detect pin goes low the EDID disappears, and thus the
88physical address, but the cable is still connected and CEC still works.
89In order to detect/wake up the device it is allowed to send poll and 'Image/Text
90View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
91
92.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}|
93
94.. c:type:: cec_msg
95
96.. cssclass:: longtable
97
98.. flat-table:: struct cec_msg
99 :header-rows: 0
100 :stub-columns: 0
101 :widths: 1 1 16
102
103 * - __u64
104 - ``tx_ts``
105 - Timestamp in ns of when the last byte of the message was transmitted.
106 The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
107 the same clock from userspace use :c:func:`clock_gettime`.
108 * - __u64
109 - ``rx_ts``
110 - Timestamp in ns of when the last byte of the message was received.
111 The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
112 the same clock from userspace use :c:func:`clock_gettime`.
113 * - __u32
114 - ``len``
115 - The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
116 by the application. The driver will fill this in for
117 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be
118 filled in by the driver with the length of the reply message if ``reply`` was set.
119 * - __u32
120 - ``timeout``
121 - The timeout in milliseconds. This is the time the device will wait
122 for a message to be received before timing out. If it is set to 0,
123 then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
124 If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
125 then it will be replaced by 1000 if the ``reply`` is non-zero or
126 ignored if ``reply`` is 0.
127 * - __u32
128 - ``sequence``
129 - A non-zero sequence number is automatically assigned by the CEC framework
130 for all transmitted messages. It is used by the CEC framework when it queues
131 the transmit result (when transmit was called in non-blocking mode). This
132 allows the application to associate the received message with the original
133 transmit.
134 * - __u32
135 - ``flags``
136 - Flags. See :ref:`cec-msg-flags` for a list of available flags.
137 * - __u8
138 - ``tx_status``
139 - The status bits of the transmitted message. See
140 :ref:`cec-tx-status` for the possible status values. It is 0 if
141 this message was received, not transmitted.
142 * - __u8
143 - ``msg[16]``
144 - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
145 application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
146 For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
147 the payload of the reply message if ``timeout`` was set.
148 * - __u8
149 - ``reply``
150 - Wait until this message is replied. If ``reply`` is 0 and the
151 ``timeout`` is 0, then don't wait for a reply but return after
152 transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
153 The case where ``reply`` is 0 (this is the opcode for the Feature Abort
154 message) and ``timeout`` is non-zero is specifically allowed to make it
155 possible to send a message and wait up to ``timeout`` milliseconds for a
156 Feature Abort reply. In this case ``rx_status`` will either be set
157 to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
158 :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
159
160 If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply``
161 values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED``
162 are processed differently: either value will match both possible replies.
163 The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC
164 message that has two possible replies other than Feature Abort. The
165 ``reply`` field will be updated with the actual reply so that it is
166 synchronized with the contents of the received message.
167 * - __u8
168 - ``rx_status``
169 - The status bits of the received message. See
170 :ref:`cec-rx-status` for the possible status values. It is 0 if
171 this message was transmitted, not received, unless this is the
172 reply to a transmitted message. In that case both ``rx_status``
173 and ``tx_status`` are set.
174 * - __u8
175 - ``tx_status``
176 - The status bits of the transmitted message. See
177 :ref:`cec-tx-status` for the possible status values. It is 0 if
178 this message was received, not transmitted.
179 * - __u8
180 - ``tx_arb_lost_cnt``
181 - A counter of the number of transmit attempts that resulted in the
182 Arbitration Lost error. This is only set if the hardware supports
183 this, otherwise it is always 0. This counter is only valid if the
184 :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
185 * - __u8
186 - ``tx_nack_cnt``
187 - A counter of the number of transmit attempts that resulted in the
188 Not Acknowledged error. This is only set if the hardware supports
189 this, otherwise it is always 0. This counter is only valid if the
190 :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
191 * - __u8
192 - ``tx_low_drive_cnt``
193 - A counter of the number of transmit attempts that resulted in the
194 Arbitration Lost error. This is only set if the hardware supports
195 this, otherwise it is always 0. This counter is only valid if the
196 :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
197 * - __u8
198 - ``tx_error_cnt``
199 - A counter of the number of transmit errors other than Arbitration
200 Lost or Not Acknowledged. This is only set if the hardware
201 supports this, otherwise it is always 0. This counter is only
202 valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
203
204
205.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}|
206
207.. _cec-msg-flags:
208
209.. flat-table:: Flags for struct cec_msg
210 :header-rows: 0
211 :stub-columns: 0
212 :widths: 3 1 4
213
214 * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
215
216 - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``
217 - 1
218 - If a CEC transmit expects a reply, then by default that reply is only sent to
219 the filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If this
220 flag is set, then the reply is also sent to all followers, if any. If the
221 filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is also a
222 follower, then that filehandle will receive the reply twice: once as the
223 result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via
224 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
225
226 * .. _`CEC-MSG-FL-RAW`:
227
228 - ``CEC_MSG_FL_RAW``
229 - 2
230 - Normally CEC messages are validated before transmitting them. If this
231 flag is set when :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is called,
232 then no validation takes place and the message is transmitted as-is.
233 This is useful when debugging CEC issues.
234 This flag is only allowed if the process has the ``CAP_SYS_RAWIO``
235 capability. If that is not set, then the ``EPERM`` error code is
236 returned.
237
238
239.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
240
241.. _cec-tx-status:
242
243.. flat-table:: CEC Transmit Status
244 :header-rows: 0
245 :stub-columns: 0
246 :widths: 3 1 16
247
248 * .. _`CEC-TX-STATUS-OK`:
249
250 - ``CEC_TX_STATUS_OK``
251 - 0x01
252 - The message was transmitted successfully. This is mutually
253 exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`.
254 Other bits can still be set if earlier attempts met with failure before
255 the transmit was eventually successful.
256 * .. _`CEC-TX-STATUS-ARB-LOST`:
257
258 - ``CEC_TX_STATUS_ARB_LOST``
259 - 0x02
260 - CEC line arbitration was lost, i.e. another transmit started at the
261 same time with a higher priority. Optional status, not all hardware
262 can detect this error condition.
263 * .. _`CEC-TX-STATUS-NACK`:
264
265 - ``CEC_TX_STATUS_NACK``
266 - 0x04
267 - Message was not acknowledged. Note that some hardware cannot tell apart
268 a 'Not Acknowledged' status from other error conditions, i.e. the result
269 of a transmit is just OK or FAIL. In that case this status will be
270 returned when the transmit failed.
271 * .. _`CEC-TX-STATUS-LOW-DRIVE`:
272
273 - ``CEC_TX_STATUS_LOW_DRIVE``
274 - 0x08
275 - Low drive was detected on the CEC bus. This indicates that a
276 follower detected an error on the bus and requests a
277 retransmission. Optional status, not all hardware can detect this
278 error condition.
279 * .. _`CEC-TX-STATUS-ERROR`:
280
281 - ``CEC_TX_STATUS_ERROR``
282 - 0x10
283 - Some error occurred. This is used for any errors that do not fit
284 ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because
285 the hardware could not tell which error occurred, or because the hardware
286 tested for other conditions besides those two. Optional status.
287 * .. _`CEC-TX-STATUS-MAX-RETRIES`:
288
289 - ``CEC_TX_STATUS_MAX_RETRIES``
290 - 0x20
291 - The transmit failed after one or more retries. This status bit is
292 mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`.
293 Other bits can still be set to explain which failures were seen.
294 * .. _`CEC-TX-STATUS-ABORTED`:
295
296 - ``CEC_TX_STATUS_ABORTED``
297 - 0x40
298 - The transmit was aborted due to an HDMI disconnect, or the adapter
299 was unconfigured, or a transmit was interrupted, or the driver
300 returned an error when attempting to start a transmit.
301 * .. _`CEC-TX-STATUS-TIMEOUT`:
302
303 - ``CEC_TX_STATUS_TIMEOUT``
304 - 0x80
305 - The transmit timed out. This should not normally happen and this
306 indicates a driver problem.
307
308
309.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
310
311.. _cec-rx-status:
312
313.. flat-table:: CEC Receive Status
314 :header-rows: 0
315 :stub-columns: 0
316 :widths: 3 1 16
317
318 * .. _`CEC-RX-STATUS-OK`:
319
320 - ``CEC_RX_STATUS_OK``
321 - 0x01
322 - The message was received successfully.
323 * .. _`CEC-RX-STATUS-TIMEOUT`:
324
325 - ``CEC_RX_STATUS_TIMEOUT``
326 - 0x02
327 - The reply to an earlier transmitted message timed out.
328 * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
329
330 - ``CEC_RX_STATUS_FEATURE_ABORT``
331 - 0x04
332 - The message was received successfully but the reply was
333 ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
334 was the reply to an earlier transmitted message.
335 * .. _`CEC-RX-STATUS-ABORTED`:
336
337 - ``CEC_RX_STATUS_ABORTED``
338 - 0x08
339 - The wait for a reply to an earlier transmitted message was aborted
340 because the HDMI cable was disconnected, the adapter was unconfigured
341 or the :ref:`CEC_TRANSMIT <CEC_RECEIVE>` that waited for a
342 reply was interrupted.
343
344
345
346Return Value
347============
348
349On success 0 is returned, on error -1 and the ``errno`` variable is set
350appropriately. The generic error codes are described at the
351:ref:`Generic Error Codes <gen-errors>` chapter.
352
353The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can return the following
354error codes:
355
356EAGAIN
357 No messages are in the receive queue, and the filehandle is in non-blocking mode.
358
359ETIMEDOUT
360 The ``timeout`` was reached while waiting for a message.
361
362ERESTARTSYS
363 The wait for a message was interrupted (e.g. by Ctrl-C).
364
365The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` can return the following
366error codes:
367
368ENOTTY
369 The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported.
370
371EPERM
372 The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
373 has never been called, or ``CEC_MSG_FL_RAW`` was used from a process that
374 did not have the ``CAP_SYS_RAWIO`` capability.
375
376ENONET
377 The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
378 was called, but the physical address is invalid so no logical address was claimed.
379 An exception is made in this case for transmits from initiator 0xf ('Unregistered')
380 to destination 0 ('TV'). In that case the transmit will proceed as usual.
381
382EBUSY
383 Another filehandle is in exclusive follower or initiator mode, or the filehandle
384 is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit
385 queue is full.
386
387EINVAL
388 The contents of struct :c:type:`cec_msg` is invalid.
389
390ERESTARTSYS
391 The wait for a successful transmit was interrupted (e.g. by Ctrl-C).