1 .. SPDX-License-Identifier: GFDL-1.1-no-invari
2 .. c:namespace:: CEC
3
4 .. _CEC_TRANSMIT:
5 .. _CEC_RECEIVE:
6
7 ***********************************
8 ioctls CEC_RECEIVE and CEC_TRANSMIT
9 ***********************************
10
11 Name
12 ====
13
14 CEC_RECEIVE, CEC_TRANSMIT - Receive or transmi
15
16 Synopsis
17 ========
18
19 .. c:macro:: CEC_RECEIVE
20
21 ``int ioctl(int fd, CEC_RECEIVE, struct cec_ms
22
23 .. c:macro:: CEC_TRANSMIT
24
25 ``int ioctl(int fd, CEC_TRANSMIT, struct cec_m
26
27 Arguments
28 =========
29
30 ``fd``
31 File descriptor returned by :c:func:`open(
32
33 ``argp``
34 Pointer to struct cec_msg.
35
36 Description
37 ===========
38
39 To receive a CEC message the application has t
40 ``timeout`` field of struct :c:type:`cec_msg`
41 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
42 If the file descriptor is in non-blocking mode
43 messages pending, then it will return -1 and s
44 error code. If the file descriptor is in block
45 is non-zero and no message arrived within ``ti
46 it will return -1 and set errno to the ``ETIME
47
48 A received message can be:
49
50 1. a message received from another CEC device
51 be 0, ``tx_status`` will be 0 and ``rx_stat
52 2. the transmit result of an earlier non-block
53 field will be non-zero, ``tx_status`` will
54 will be 0).
55 3. the reply to an earlier non-blocking transm
56 be non-zero, ``tx_status`` will be 0 and ``
57
58 To send a CEC message the application has to f
59 :c:type:`cec_msg` and pass it to :ref:`ioctl C
60 The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` i
61 ``CEC_CAP_TRANSMIT`` is set. If there is no mo
62 queue, then it will return -1 and set errno to
63 The transmit queue has enough room for 18 mess
64 of 2-byte messages). Note that the CEC kernel
65 to core messages (see :ref:`cec-core-processin
66 idea to fully fill up the transmit queue.
67
68 If the file descriptor is in non-blocking mode
69 return 0 and the result of the transmit will b
70 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once th
71 If a non-blocking transmit also specified wait
72 the reply will arrive in a later message. The
73 be used to associate both transmit results and
74 transmit.
75
76 Normally calling :ref:`ioctl CEC_TRANSMIT <CEC
77 address is invalid (due to e.g. a disconnect)
78
79 However, the CEC specification allows sending
80 'TV' when the physical address is invalid sinc
81 pin of the HDMI connector low when they go int
82 another input.
83
84 When the hotplug detect pin goes low the EDID
85 physical address, but the cable is still conne
86 In order to detect/wake up the device it is al
87 View On' messages from initiator 0xf ('Unregis
88
89 .. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{12.8c
90
91 .. c:type:: cec_msg
92
93 .. cssclass:: longtable
94
95 .. flat-table:: struct cec_msg
96 :header-rows: 0
97 :stub-columns: 0
98 :widths: 1 1 16
99
100 * - __u64
101 - ``tx_ts``
102 - Timestamp in ns of when the last byte
103 The timestamp has been taken from the
104 the same clock from userspace use :c:f
105 * - __u64
106 - ``rx_ts``
107 - Timestamp in ns of when the last byte
108 The timestamp has been taken from the
109 the same clock from userspace use :c:f
110 * - __u32
111 - ``len``
112 - The length of the message. For :ref:`i
113 by the application. The driver will fi
114 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`
115 filled in by the driver with the lengt
116 * - __u32
117 - ``timeout``
118 - The timeout in milliseconds. This is t
119 for a message to be received before ti
120 then it will wait indefinitely when it
121 If it is 0 and it is called by :ref:`i
122 then it will be replaced by 1000 if th
123 ignored if ``reply`` is 0.
124 * - __u32
125 - ``sequence``
126 - A non-zero sequence number is automati
127 for all transmitted messages. It is us
128 the transmit result for a non-blocking
129 to associate the received message with
130
131 In addition, if a non-blocking transmi
132 was not 0), then the ``sequence`` fiel
133 value of the original transmit. This a
134 received message with the original tra
135 * - __u32
136 - ``flags``
137 - Flags. See :ref:`cec-msg-flags` for a
138 * - __u8
139 - ``msg[16]``
140 - The message payload. For :ref:`ioctl C
141 application. The driver will fill this
142 For :ref:`ioctl CEC_TRANSMIT <CEC_TRAN
143 the payload of the reply message if ``
144 * - __u8
145 - ``reply``
146 - Wait until this message is replied. If
147 ``timeout`` is 0, then don't wait for
148 transmitting the message. Ignored by :
149 The case where ``reply`` is 0 (this is
150 message) and ``timeout`` is non-zero i
151 possible to send a message and wait up
152 Feature Abort reply. In this case ``rx
153 to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX
154 :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC
155
156 If the transmitter message is ``CEC_MS
157 values ``CEC_MSG_REPORT_ARC_INITIATED`
158 are processed differently: either valu
159 The reason is that the ``CEC_MSG_INITI
160 message that has two possible replies
161 ``reply`` field will be updated with t
162 synchronized with the contents of the
163 * - __u8
164 - ``rx_status``
165 - The status bits of the received messag
166 :ref:`cec-rx-status` for the possible
167 * - __u8
168 - ``tx_status``
169 - The status bits of the transmitted mes
170 :ref:`cec-tx-status` for the possible
171 When calling :ref:`ioctl CEC_TRANSMIT
172 this field will be 0 if the transmit s
173 result is known immediately. The latte
174 to transmit a Poll message to yourself
175 :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATU
176 transmitting the Poll message.
177 * - __u8
178 - ``tx_arb_lost_cnt``
179 - A counter of the number of transmit at
180 Arbitration Lost error. This is only s
181 this, otherwise it is always 0. This c
182 :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-S
183 * - __u8
184 - ``tx_nack_cnt``
185 - A counter of the number of transmit at
186 Not Acknowledged error. This is only s
187 this, otherwise it is always 0. This c
188 :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATU
189 * - __u8
190 - ``tx_low_drive_cnt``
191 - A counter of the number of transmit at
192 Arbitration Lost error. This is only s
193 this, otherwise it is always 0. This c
194 :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-
195 * - __u8
196 - ``tx_error_cnt``
197 - A counter of the number of transmit er
198 Lost or Not Acknowledged. This is only
199 supports this, otherwise it is always
200 valid if the :ref:`CEC_TX_STATUS_ERROR
201
202 .. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.1c
203
204 .. _cec-msg-flags:
205
206 .. flat-table:: Flags for struct cec_msg
207 :header-rows: 0
208 :stub-columns: 0
209 :widths: 3 1 4
210
211 * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
212
213 - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``
214 - 1
215 - If a CEC transmit expects a reply, the
216 the filehandle that called :ref:`ioctl
217 flag is set, then the reply is also se
218 filehandle that called :ref:`ioctl CEC
219 follower, then that filehandle will re
220 result of the :ref:`ioctl CEC_TRANSMIT
221 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`
222
223 * .. _`CEC-MSG-FL-RAW`:
224
225 - ``CEC_MSG_FL_RAW``
226 - 2
227 - Normally CEC messages are validated be
228 flag is set when :ref:`ioctl CEC_TRANS
229 then no validation takes place and the
230 This is useful when debugging CEC issu
231 This flag is only allowed if the proce
232 capability. If that is not set, then t
233 returned.
234
235 * .. _`CEC-MSG-FL-REPLY-VENDOR-ID`:
236
237 - ``CEC_MSG_FL_REPLY_VENDOR_ID``
238 - 4
239 - This flag is only available if the ``C
240 is set. If this flag is set, then the
241 the ``CEC_MSG_VENDOR_COMMAND_WITH_ID``
242 (in bytes 1-4 of the message), followe
243 ``reply`` field.
244
245 Note that this assumes that the byte a
246 vendor-specific opcode.
247
248 This flag makes it easier to wait for
249
250 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8c
251
252 .. _cec-tx-status:
253
254 .. flat-table:: CEC Transmit Status
255 :header-rows: 0
256 :stub-columns: 0
257 :widths: 3 1 16
258
259 * .. _`CEC-TX-STATUS-OK`:
260
261 - ``CEC_TX_STATUS_OK``
262 - 0x01
263 - The message was transmitted successful
264 exclusive with :ref:`CEC_TX_STATUS_MAX
265 Other bits can still be set if earlier
266 the transmit was eventually successful
267 * .. _`CEC-TX-STATUS-ARB-LOST`:
268
269 - ``CEC_TX_STATUS_ARB_LOST``
270 - 0x02
271 - CEC line arbitration was lost, i.e. an
272 same time with a higher priority. Opti
273 can detect this error condition.
274 * .. _`CEC-TX-STATUS-NACK`:
275
276 - ``CEC_TX_STATUS_NACK``
277 - 0x04
278 - Message was not acknowledged. Note tha
279 a 'Not Acknowledged' status from other
280 of a transmit is just OK or FAIL. In t
281 returned when the transmit failed.
282 * .. _`CEC-TX-STATUS-LOW-DRIVE`:
283
284 - ``CEC_TX_STATUS_LOW_DRIVE``
285 - 0x08
286 - Low drive was detected on the CEC bus.
287 follower detected an error on the bus
288 retransmission. Optional status, not a
289 error condition.
290 * .. _`CEC-TX-STATUS-ERROR`:
291
292 - ``CEC_TX_STATUS_ERROR``
293 - 0x10
294 - Some error occurred. This is used for
295 ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX
296 the hardware could not tell which erro
297 tested for other conditions besides th
298 * .. _`CEC-TX-STATUS-MAX-RETRIES`:
299
300 - ``CEC_TX_STATUS_MAX_RETRIES``
301 - 0x20
302 - The transmit failed after one or more
303 mutually exclusive with :ref:`CEC_TX_S
304 Other bits can still be set to explain
305 * .. _`CEC-TX-STATUS-ABORTED`:
306
307 - ``CEC_TX_STATUS_ABORTED``
308 - 0x40
309 - The transmit was aborted due to an HDM
310 was unconfigured, or a transmit was in
311 returned an error when attempting to s
312 * .. _`CEC-TX-STATUS-TIMEOUT`:
313
314 - ``CEC_TX_STATUS_TIMEOUT``
315 - 0x80
316 - The transmit timed out. This should no
317 indicates a driver problem.
318
319 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8c
320
321 .. _cec-rx-status:
322
323 .. flat-table:: CEC Receive Status
324 :header-rows: 0
325 :stub-columns: 0
326 :widths: 3 1 16
327
328 * .. _`CEC-RX-STATUS-OK`:
329
330 - ``CEC_RX_STATUS_OK``
331 - 0x01
332 - The message was received successfully.
333 * .. _`CEC-RX-STATUS-TIMEOUT`:
334
335 - ``CEC_RX_STATUS_TIMEOUT``
336 - 0x02
337 - The reply to an earlier transmitted me
338 * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
339
340 - ``CEC_RX_STATUS_FEATURE_ABORT``
341 - 0x04
342 - The message was received successfully
343 ``CEC_MSG_FEATURE_ABORT``. This status
344 was the reply to an earlier transmitte
345 * .. _`CEC-RX-STATUS-ABORTED`:
346
347 - ``CEC_RX_STATUS_ABORTED``
348 - 0x08
349 - The wait for a reply to an earlier tra
350 because the HDMI cable was disconnecte
351 or the :ref:`CEC_TRANSMIT <CEC_RECEIVE
352 reply was interrupted.
353
354
355 Return Value
356 ============
357
358 On success 0 is returned, on error -1 and the
359 appropriately. The generic error codes are des
360 :ref:`Generic Error Codes <gen-errors>` chapte
361
362 The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can
363 error codes:
364
365 EAGAIN
366 No messages are in the receive queue, and
367
368 ETIMEDOUT
369 The ``timeout`` was reached while waiting
370
371 ERESTARTSYS
372 The wait for a message was interrupted (e.
373
374 The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` c
375 error codes:
376
377 ENOTTY
378 The ``CEC_CAP_TRANSMIT`` capability wasn't
379
380 EPERM
381 The CEC adapter is not configured, i.e. :r
382 has never been called, or ``CEC_MSG_FL_RAW
383 did not have the ``CAP_SYS_RAWIO`` capabil
384
385 ENONET
386 The CEC adapter is not configured, i.e. :r
387 was called, but the physical address is in
388 An exception is made in this case for tran
389 to destination 0 ('TV'). In that case the
390
391 EBUSY
392 Another filehandle is in exclusive followe
393 is in mode ``CEC_MODE_NO_INITIATOR``. This
394 queue is full.
395
396 EINVAL
397 The contents of struct :c:type:`cec_msg` i
398
399 ERESTARTSYS
400 The wait for a successful transmit was int
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.