Lines Matching +full:rx +full:- +full:queues +full:- +full:to +full:- +full:use
1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
14 CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
34 Pointer to struct cec_msg.
39 To receive a CEC message the application has to fill in the
40 ``timeout`` field of struct :c:type:`cec_msg` and pass it to
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``
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).
55 To 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>`.
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
63 idea to fully fill up the transmit queue.
65 If the file descriptor is in non-blocking mode then the transmit will
71 checked against the received messages to find the corresponding transmit
75 address is invalid (due to e.g. a disconnect) will return ``ENONET``.
77 However, the CEC specification allows sending messages from 'Unregistered' to
79 pin of the HDMI connector low when they go into standby, or when switching to
84 In order to detect/wake up the device it is allowed to send poll and 'Image/Text
85 View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
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
117 for a message to be received before timing out. If it is set to 0,
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
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
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
150 possible to send a message and wait up to ``timeout`` milliseconds for a
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
167 reply to a transmitted message. In that case both ``rx_status``
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
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
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
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
214 flag is set, then the reply is also sent to all followers, if any. If the
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.
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
256 * .. _`CEC-TX-STATUS-NACK`:
258 - ``CEC_TX_STATUS_NACK``
259 - 0x04
260 - Message was not acknowledged. Note that some hardware cannot tell apart
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
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
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>`.
286 Other bits can still be set to explain which failures were seen.
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
326 was the reply to an earlier transmitted message.
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
342 :ref:`Generic Error Codes <gen-errors>` chapter.
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).
371 to destination 0 ('TV'). In that case the transmit will proceed as usual.
382 The wait for a successful transmit was interrupted (e.g. by Ctrl-C).