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