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
235     * .. _`CEC-MSG-FL-REPLY-VENDOR-ID`:
237       - ``CEC_MSG_FL_REPLY_VENDOR_ID``
238       - 4
239       - This flag is only available if the ``CEC_CAP_REPLY_VENDOR_ID`` capability
242 	(in bytes 1-4 of the message), followed by the ``struct cec_msg``
246 	vendor-specific opcode.
252 .. _cec-tx-status:
254 .. flat-table:: CEC Transmit Status
255     :header-rows:  0
256     :stub-columns: 0
259     * .. _`CEC-TX-STATUS-OK`:
261       - ``CEC_TX_STATUS_OK``
262       - 0x01
263       - The message was transmitted successfully. This is mutually
264 	exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`.
267     * .. _`CEC-TX-STATUS-ARB-LOST`:
269       - ``CEC_TX_STATUS_ARB_LOST``
270       - 0x02
271       - CEC line arbitration was lost, i.e. another transmit started at the
273 	can detect this error condition.
274     * .. _`CEC-TX-STATUS-NACK`:
276       - ``CEC_TX_STATUS_NACK``
277       - 0x04
278       - Message was not acknowledged. Note that some hardware cannot tell apart
279         a 'Not Acknowledged' status from other error conditions, i.e. the result
282     * .. _`CEC-TX-STATUS-LOW-DRIVE`:
284       - ``CEC_TX_STATUS_LOW_DRIVE``
285       - 0x08
286       - Low drive was detected on the CEC bus. This indicates that a
287 	follower detected an error on the bus and requests a
288 	retransmission. Optional status, not all hardware can detect this
289 	error condition.
290     * .. _`CEC-TX-STATUS-ERROR`:
292       - ``CEC_TX_STATUS_ERROR``
293       - 0x10
294       - Some error occurred. This is used for any errors that do not fit
296 	the hardware could not tell which error occurred, or because the hardware
298     * .. _`CEC-TX-STATUS-MAX-RETRIES`:
300       - ``CEC_TX_STATUS_MAX_RETRIES``
301       - 0x20
302       - The transmit failed after one or more retries. This status bit is
303 	mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`.
305     * .. _`CEC-TX-STATUS-ABORTED`:
307       - ``CEC_TX_STATUS_ABORTED``
308       - 0x40
309       - The transmit was aborted due to an HDMI disconnect, or the adapter
311 	returned an error when attempting to start a transmit.
312     * .. _`CEC-TX-STATUS-TIMEOUT`:
314       - ``CEC_TX_STATUS_TIMEOUT``
315       - 0x80
316       - The transmit timed out. This should not normally happen and this
321 .. _cec-rx-status:
323 .. flat-table:: CEC Receive Status
324     :header-rows:  0
325     :stub-columns: 0
328     * .. _`CEC-RX-STATUS-OK`:
330       - ``CEC_RX_STATUS_OK``
331       - 0x01
332       - The message was received successfully.
333     * .. _`CEC-RX-STATUS-TIMEOUT`:
335       - ``CEC_RX_STATUS_TIMEOUT``
336       - 0x02
337       - The reply to an earlier transmitted message timed out.
338     * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
340       - ``CEC_RX_STATUS_FEATURE_ABORT``
341       - 0x04
342       - The message was received successfully but the reply was
345     * .. _`CEC-RX-STATUS-ABORTED`:
347       - ``CEC_RX_STATUS_ABORTED``
348       - 0x08
349       - The wait for a reply to an earlier transmitted message was aborted
358 On success 0 is returned, on error -1 and the ``errno`` variable is set
359 appropriately. The generic error codes are described at the
360 :ref:`Generic Error Codes <gen-errors>` chapter.
363 error codes:
366     No messages are in the receive queue, and the filehandle is in non-blocking mode.
372     The wait for a message was interrupted (e.g. by Ctrl-C).
375 error codes:
400     The wait for a successful transmit was interrupted (e.g. by Ctrl-C).