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