media/cec/cec-ioc-receive.rst

1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
14 CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
42 If the file descriptor is in non-blocking mode and there are no received
43 messages pending, then it will return -1 and set errno to the ``EAGAIN``
44 error code. If the file descriptor is in blocking mode and ``timeout``
45 is non-zero and no message arrived within ``timeout`` milliseconds, then
46 it will return -1 and set errno to the ``ETIMEDOUT`` error code.
51    be 0, ``tx_status`` will be 0 and ``rx_status`` will be non-zero).
52 2. the transmit result of an earlier non-blocking transmit (the ``sequence``
53    field will be non-zero, ``tx_status`` will be non-zero and ``rx_status``
55 3. the reply to an earlier non-blocking transmit (the ``sequence`` field will
56    be non-zero, ``tx_status`` will be 0 and ``rx_status`` will be non-zero).
62 queue, then it will return -1 and set errno to the ``EBUSY`` error code.
64 of 2-byte messages). Note that the CEC kernel framework will also reply
65 to core messages (see :ref:`cec-core-processing`), so it is not a good
68 If the file descriptor is in non-blocking mode then the transmit will
71 If a non-blocking transmit also specified waiting for a reply, then
80 'TV' when the physical address is invalid since some TVs pull the hotplug detect
84 When the hotplug detect pin goes low the EDID disappears, and thus the
86 In order to detect/wake up the device it is allowed to send poll and 'Image/Text
95 .. flat-table:: struct cec_msg
96     :header-rows:  0
97     :stub-columns: 0
100     * - __u64
101       - ``tx_ts``
102       - Timestamp in ns of when the last byte of the message was transmitted.
103 	The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
104 	the same clock from userspace use :c:func:`clock_gettime`.
105     * - __u64
106       - ``rx_ts``
107       - Timestamp in ns of when the last byte of the message was received.
108 	The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
109 	the same clock from userspace use :c:func:`clock_gettime`.
110     * - __u32
111       - ``len``
112       - The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
116     * - __u32
117       - ``timeout``
118       - The timeout in milliseconds. This is the time the device will wait
122 	then it will be replaced by 1000 if the ``reply`` is non-zero or
124     * - __u32
125       - ``sequence``
126       - A non-zero sequence number is automatically assigned by the CEC framework
128 	the transmit result for a non-blocking transmit. This allows the application
131 	In addition, if a non-blocking transmit will wait for a reply (ii.e. ``timeout``
135     * - __u32
136       - ``flags``
137       - Flags. See :ref:`cec-msg-flags` for a list of available flags.
138     * - __u8
139       - ``msg[16]``
140       - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
144     * - __u8
145       - ``reply``
146       - Wait until this message is replied. If ``reply`` is 0 and the
150 	message) and ``timeout`` is non-zero is specifically allowed to make it
153 	to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
154 	:ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
163     * - __u8
164       - ``rx_status``
165       - The status bits of the received message. See
166 	:ref:`cec-rx-status` for the possible status values.
167     * - __u8
168       - ``tx_status``
169       - The status bits of the transmitted message. See
170 	:ref:`cec-tx-status` for the possible status values.
171 	When calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` in non-blocking mode,
172 	this field will be 0 if the transmit started, or non-0 if the transmit
175 	:ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` without ever actually
177     * - __u8
178       - ``tx_arb_lost_cnt``
179       - A counter of the number of transmit attempts that resulted in the
180 	Arbitration Lost error. This is only set if the hardware supports
182 	:ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
183     * - __u8
184       - ``tx_nack_cnt``
185       - A counter of the number of transmit attempts that resulted in the
186 	Not Acknowledged error. This is only set if the hardware supports
188 	:ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
189     * - __u8
190       - ``tx_low_drive_cnt``
191       - A counter of the number of transmit attempts that resulted in the
192 	Arbitration Lost error. This is only set if the hardware supports
194 	:ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
195     * - __u8
196       - ``tx_error_cnt``
197       - A counter of the number of transmit errors other than Arbitration
200 	valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
204 .. _cec-msg-flags:
206 .. flat-table:: Flags for struct cec_msg
207     :header-rows:  0
208     :stub-columns: 0
211     * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
213       - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``
214       - 1
215       - If a CEC transmit expects a reply, then by default that reply is only sent to
223     * .. _`CEC-MSG-FL-RAW`:
225       - ``CEC_MSG_FL_RAW``
226       - 2
227       - Normally CEC messages are validated before transmitting them. If this
229 	then no validation takes place and the message is transmitted as-is.
232 	capability. If that is not set, then the ``EPERM`` error code is
237 .. _cec-tx-status:
239 .. flat-table:: CEC Transmit Status
240     :header-rows:  0
241     :stub-columns: 0
244     * .. _`CEC-TX-STATUS-OK`:
246       - ``CEC_TX_STATUS_OK``
247       - 0x01
248       - The message was transmitted successfully. This is mutually
249 	exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`.
252     * .. _`CEC-TX-STATUS-ARB-LOST`:
254       - ``CEC_TX_STATUS_ARB_LOST``
255       - 0x02
256       - CEC line arbitration was lost, i.e. another transmit started at the
258 	can detect this error condition.
259     * .. _`CEC-TX-STATUS-NACK`:
261       - ``CEC_TX_STATUS_NACK``
262       - 0x04
263       - Message was not acknowledged. Note that some hardware cannot tell apart
264         a 'Not Acknowledged' status from other error conditions, i.e. the result
267     * .. _`CEC-TX-STATUS-LOW-DRIVE`:
269       - ``CEC_TX_STATUS_LOW_DRIVE``
270       - 0x08
271       - Low drive was detected on the CEC bus. This indicates that a
272 	follower detected an error on the bus and requests a
273 	retransmission. Optional status, not all hardware can detect this
274 	error condition.
275     * .. _`CEC-TX-STATUS-ERROR`:
277       - ``CEC_TX_STATUS_ERROR``
278       - 0x10
279       - Some error occurred. This is used for any errors that do not fit
281 	the hardware could not tell which error occurred, or because the hardware
283     * .. _`CEC-TX-STATUS-MAX-RETRIES`:
285       - ``CEC_TX_STATUS_MAX_RETRIES``
286       - 0x20
287       - The transmit failed after one or more retries. This status bit is
288 	mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`.
290     * .. _`CEC-TX-STATUS-ABORTED`:
292       - ``CEC_TX_STATUS_ABORTED``
293       - 0x40
294       - The transmit was aborted due to an HDMI disconnect, or the adapter
296 	returned an error when attempting to start a transmit.
297     * .. _`CEC-TX-STATUS-TIMEOUT`:
299       - ``CEC_TX_STATUS_TIMEOUT``
300       - 0x80
301       - The transmit timed out. This should not normally happen and this
306 .. _cec-rx-status:
308 .. flat-table:: CEC Receive Status
309     :header-rows:  0
310     :stub-columns: 0
313     * .. _`CEC-RX-STATUS-OK`:
315       - ``CEC_RX_STATUS_OK``
316       - 0x01
317       - The message was received successfully.
318     * .. _`CEC-RX-STATUS-TIMEOUT`:
320       - ``CEC_RX_STATUS_TIMEOUT``
321       - 0x02
322       - The reply to an earlier transmitted message timed out.
323     * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
325       - ``CEC_RX_STATUS_FEATURE_ABORT``
326       - 0x04
327       - The message was received successfully but the reply was
330     * .. _`CEC-RX-STATUS-ABORTED`:
332       - ``CEC_RX_STATUS_ABORTED``
333       - 0x08
334       - The wait for a reply to an earlier transmitted message was aborted
343 On success 0 is returned, on error -1 and the ``errno`` variable is set
344 appropriately. The generic error codes are described at the
345 :ref:`Generic Error Codes <gen-errors>` chapter.
348 error codes:
351     No messages are in the receive queue, and the filehandle is in non-blocking mode.
357     The wait for a message was interrupted (e.g. by Ctrl-C).
360 error codes:
385     The wait for a successful transmit was interrupted (e.g. by Ctrl-C).