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.
52 2. the result of an earlier non-blocking transmit (the ``sequence`` field will
53    be non-zero).
59 queue, then it will return -1 and set errno to the ``EBUSY`` error code.
61 of 2-byte messages). Note that the CEC kernel framework will also reply
62 to core messages (see :ref:`cec-core-processing`), so it is not a good
65 If the file descriptor is in non-blocking mode then the transmit will
78 'TV' when the physical address is invalid since some TVs pull the hotplug detect
82 When the hotplug detect pin goes low the EDID disappears, and thus the
84 In order to detect/wake up the device it is allowed to send poll and 'Image/Text
93 .. flat-table:: struct cec_msg
94     :header-rows:  0
95     :stub-columns: 0
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
114     * - __u32
115       - ``timeout``
116       - The timeout in milliseconds. This is the time the device will wait
120 	then it will be replaced by 1000 if the ``reply`` is non-zero or
122     * - __u32
123       - ``sequence``
124       - A non-zero sequence number is automatically assigned by the CEC framework
126 	the transmit result (when transmit was called in non-blocking mode). This
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
137     * - __u8
138       - ``msg[16]``
139       - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
143     * - __u8
144       - ``reply``
145       - Wait until this message is replied. If ``reply`` is 0 and the
149 	message) and ``timeout`` is non-zero is specifically allowed to make it
152 	to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
153 	:ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
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
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
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
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
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
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
197 	valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
201 .. _cec-msg-flags:
203 .. flat-table:: Flags for struct cec_msg
204     :header-rows:  0
205     :stub-columns: 0
208     * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
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
220     * .. _`CEC-MSG-FL-RAW`:
222       - ``CEC_MSG_FL_RAW``
223       - 2
224       - Normally CEC messages are validated before transmitting them. If this
226 	then no validation takes place and the message is transmitted as-is.
229 	capability. If that is not set, then the ``EPERM`` error code is
234 .. _cec-tx-status:
236 .. flat-table:: CEC Transmit Status
237     :header-rows:  0
238     :stub-columns: 0
241     * .. _`CEC-TX-STATUS-OK`:
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>`.
249     * .. _`CEC-TX-STATUS-ARB-LOST`:
251       - ``CEC_TX_STATUS_ARB_LOST``
252       - 0x02
253       - CEC line arbitration was lost, i.e. another transmit started at the
255 	can detect this error condition.
256     * .. _`CEC-TX-STATUS-NACK`:
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
264     * .. _`CEC-TX-STATUS-LOW-DRIVE`:
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`:
274       - ``CEC_TX_STATUS_ERROR``
275       - 0x10
276       - Some error occurred. This is used for any errors that do not fit
278 	the hardware could not tell which error occurred, or because the hardware
280     * .. _`CEC-TX-STATUS-MAX-RETRIES`:
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>`.
287     * .. _`CEC-TX-STATUS-ABORTED`:
289       - ``CEC_TX_STATUS_ABORTED``
290       - 0x40
291       - The transmit was aborted due to an HDMI disconnect, or the adapter
293 	returned an error when attempting to start a transmit.
294     * .. _`CEC-TX-STATUS-TIMEOUT`:
296       - ``CEC_TX_STATUS_TIMEOUT``
297       - 0x80
298       - The transmit timed out. This should not normally happen and this
303 .. _cec-rx-status:
305 .. flat-table:: CEC Receive Status
306     :header-rows:  0
307     :stub-columns: 0
310     * .. _`CEC-RX-STATUS-OK`:
312       - ``CEC_RX_STATUS_OK``
313       - 0x01
314       - The message was received successfully.
315     * .. _`CEC-RX-STATUS-TIMEOUT`:
317       - ``CEC_RX_STATUS_TIMEOUT``
318       - 0x02
319       - The reply to an earlier transmitted message timed out.
320     * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
322       - ``CEC_RX_STATUS_FEATURE_ABORT``
323       - 0x04
324       - The message was received successfully but the reply was
327     * .. _`CEC-RX-STATUS-ABORTED`:
329       - ``CEC_RX_STATUS_ABORTED``
330       - 0x08
331       - The wait for a reply to an earlier transmitted message was aborted
340 On success 0 is returned, on error -1 and the ``errno`` variable is set
341 appropriately. The generic error codes are described at the
342 :ref:`Generic Error Codes <gen-errors>` chapter.
345 error codes:
348     No messages are in the receive queue, and the filehandle is in non-blocking mode.
354     The wait for a message was interrupted (e.g. by Ctrl-C).
357 error codes:
382     The wait for a successful transmit was interrupted (e.g. by Ctrl-C).