Commit | Line | Data |
---|---|---|
e2460b1d MH |
1 | .. -*- coding: utf-8; mode: rst -*- |
2 | ||
21c62694 MH |
3 | .. _CEC_TRANSMIT: |
4 | .. _CEC_RECEIVE: | |
e2460b1d MH |
5 | |
6 | ******************************* | |
7 | ioctl CEC_RECEIVE, CEC_TRANSMIT | |
8 | ******************************* | |
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 | ||
21c62694 | 19 | .. cpp:function:: int ioctl( int fd, int request, struct cec_msg *argp ) |
e2460b1d MH |
20 | |
21 | Arguments | |
22 | ========= | |
23 | ||
24 | ``fd`` | |
25 | File descriptor returned by :ref:`open() <cec-func-open>`. | |
26 | ||
27 | ``request`` | |
28 | CEC_RECEIVE, CEC_TRANSMIT | |
29 | ||
30 | ``argp`` | |
31 | ||
32 | ||
33 | Description | |
34 | =========== | |
35 | ||
706f8a99 MCC |
36 | .. note:: This documents the proposed CEC API. This API is not yet finalized |
37 | and is currently only available as a staging kernel module. | |
e2460b1d MH |
38 | |
39 | To receive a CEC message the application has to fill in the | |
21c62694 MH |
40 | :c:type:`struct cec_msg` structure and pass it to the :ref:`CEC_RECEIVE` |
41 | ioctl. :ref:`CEC_RECEIVE` is only available if ``CEC_CAP_RECEIVE`` is set. | |
e2460b1d MH |
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. | |
47 | ||
48 | To send a CEC message the application has to fill in the | |
49 | :c:type:`struct cec_msg` structure and pass it to the | |
21c62694 | 50 | :ref:`CEC_TRANSMIT` ioctl. :ref:`CEC_TRANSMIT` is only available if |
e2460b1d MH |
51 | ``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit |
52 | queue, then it will return -1 and set errno to the EBUSY error code. | |
53 | ||
54 | ||
55 | .. _cec-msg: | |
56 | ||
57 | .. flat-table:: struct cec_msg | |
58 | :header-rows: 0 | |
59 | :stub-columns: 0 | |
b2a58436 | 60 | :widths: 1 1 16 |
e2460b1d MH |
61 | |
62 | ||
63 | - .. row 1 | |
64 | ||
65 | - __u64 | |
66 | ||
67 | - ``ts`` | |
68 | ||
69 | - Timestamp of when the message was transmitted in ns in the case of | |
706f8a99 MCC |
70 | :ref:`CEC_TRANSMIT` with ``reply`` set to 0, or the timestamp of the |
71 | received message in all other cases. | |
e2460b1d MH |
72 | |
73 | - .. row 2 | |
74 | ||
75 | - __u32 | |
76 | ||
77 | - ``len`` | |
78 | ||
21c62694 | 79 | - The length of the message. For :ref:`CEC_TRANSMIT` this is filled in |
706f8a99 MCC |
80 | by the application. The driver will fill this in for |
81 | :ref:`CEC_RECEIVE` and for :ref:`CEC_TRANSMIT` it will be filled in with | |
82 | the length of the reply message if ``reply`` was set. | |
e2460b1d MH |
83 | |
84 | - .. row 3 | |
85 | ||
86 | - __u32 | |
87 | ||
88 | - ``timeout`` | |
89 | ||
90 | - The timeout in milliseconds. This is the time the device will wait | |
706f8a99 MCC |
91 | for a message to be received before timing out. If it is set to 0, |
92 | then it will wait indefinitely when it is called by | |
93 | :ref:`CEC_RECEIVE`. If it is 0 and it is called by :ref:`CEC_TRANSMIT`, | |
94 | then it will be replaced by 1000 if the ``reply`` is non-zero or | |
95 | ignored if ``reply`` is 0. | |
e2460b1d MH |
96 | |
97 | - .. row 4 | |
98 | ||
99 | - __u32 | |
100 | ||
101 | - ``sequence`` | |
102 | ||
103 | - The sequence number is automatically assigned by the CEC framework | |
706f8a99 MCC |
104 | for all transmitted messages. It can be later used by the |
105 | framework to generate an event if a reply for a message was | |
106 | requested and the message was transmitted in a non-blocking mode. | |
e2460b1d MH |
107 | |
108 | - .. row 5 | |
109 | ||
110 | - __u32 | |
111 | ||
112 | - ``flags`` | |
113 | ||
114 | - Flags. No flags are defined yet, so set this to 0. | |
115 | ||
116 | - .. row 6 | |
117 | ||
118 | - __u8 | |
119 | ||
120 | - ``rx_status`` | |
121 | ||
122 | - The status bits of the received message. See | |
706f8a99 MCC |
123 | :ref:`cec-rx-status` for the possible status values. It is 0 if |
124 | this message was transmitted, not received, unless this is the | |
125 | reply to a transmitted message. In that case both ``rx_status`` | |
126 | and ``tx_status`` are set. | |
e2460b1d MH |
127 | |
128 | - .. row 7 | |
129 | ||
130 | - __u8 | |
131 | ||
132 | - ``tx_status`` | |
133 | ||
134 | - The status bits of the transmitted message. See | |
706f8a99 MCC |
135 | :ref:`cec-tx-status` for the possible status values. It is 0 if |
136 | this messages was received, not transmitted. | |
e2460b1d MH |
137 | |
138 | - .. row 8 | |
139 | ||
140 | - __u8 | |
141 | ||
142 | - ``msg``\ [16] | |
143 | ||
21c62694 | 144 | - The message payload. For :ref:`CEC_TRANSMIT` this is filled in by the |
706f8a99 MCC |
145 | application. The driver will fill this in for :ref:`CEC_RECEIVE` and |
146 | for :ref:`CEC_TRANSMIT` it will be filled in with the payload of the | |
147 | reply message if ``reply`` was set. | |
e2460b1d MH |
148 | |
149 | - .. row 9 | |
150 | ||
151 | - __u8 | |
152 | ||
153 | - ``reply`` | |
154 | ||
155 | - Wait until this message is replied. If ``reply`` is 0 and the | |
706f8a99 MCC |
156 | ``timeout`` is 0, then don't wait for a reply but return after |
157 | transmitting the message. If there was an error as indicated by a | |
158 | non-zero ``tx_status`` field, then ``reply`` and ``timeout`` are | |
159 | both set to 0 by the driver. Ignored by :ref:`CEC_RECEIVE`. The case | |
160 | where ``reply`` is 0 (this is the opcode for the Feature Abort | |
161 | message) and ``timeout`` is non-zero is specifically allowed to | |
162 | send a message and wait up to ``timeout`` milliseconds for a | |
163 | Feature Abort reply. In this case ``rx_status`` will either be set | |
164 | to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or :ref:`CEC_RX_STATUS-FEATURE-ABORT <CEC-RX-STATUS-FEATURE-ABORT>`. | |
e2460b1d MH |
165 | |
166 | - .. row 10 | |
167 | ||
168 | - __u8 | |
169 | ||
170 | - ``tx_arb_lost_cnt`` | |
171 | ||
172 | - A counter of the number of transmit attempts that resulted in the | |
706f8a99 MCC |
173 | Arbitration Lost error. This is only set if the hardware supports |
174 | this, otherwise it is always 0. This counter is only valid if the | |
175 | :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set. | |
e2460b1d MH |
176 | |
177 | - .. row 11 | |
178 | ||
179 | - __u8 | |
180 | ||
181 | - ``tx_nack_cnt`` | |
182 | ||
183 | - A counter of the number of transmit attempts that resulted in the | |
706f8a99 MCC |
184 | Not Acknowledged error. This is only set if the hardware supports |
185 | this, otherwise it is always 0. This counter is only valid if the | |
186 | :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set. | |
e2460b1d MH |
187 | |
188 | - .. row 12 | |
189 | ||
190 | - __u8 | |
191 | ||
192 | - ``tx_low_drive_cnt`` | |
193 | ||
194 | - A counter of the number of transmit attempts that resulted in the | |
706f8a99 MCC |
195 | Arbitration Lost error. This is only set if the hardware supports |
196 | this, otherwise it is always 0. This counter is only valid if the | |
197 | :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set. | |
e2460b1d MH |
198 | |
199 | - .. row 13 | |
200 | ||
201 | - __u8 | |
202 | ||
203 | - ``tx_error_cnt`` | |
204 | ||
205 | - A counter of the number of transmit errors other than Arbitration | |
706f8a99 MCC |
206 | Lost or Not Acknowledged. This is only set if the hardware |
207 | supports this, otherwise it is always 0. This counter is only | |
208 | valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. | |
e2460b1d MH |
209 | |
210 | ||
211 | ||
212 | .. _cec-tx-status: | |
213 | ||
214 | .. flat-table:: CEC Transmit Status | |
215 | :header-rows: 0 | |
216 | :stub-columns: 0 | |
b2a58436 | 217 | :widths: 3 1 16 |
e2460b1d MH |
218 | |
219 | ||
96f69e0e | 220 | - .. _`CEC-TX-STATUS-OK`: |
e2460b1d MH |
221 | |
222 | - ``CEC_TX_STATUS_OK`` | |
223 | ||
224 | - 0x01 | |
225 | ||
226 | - The message was transmitted successfully. This is mutually | |
706f8a99 MCC |
227 | exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still |
228 | be set if earlier attempts met with failure before the transmit | |
229 | was eventually successful. | |
e2460b1d | 230 | |
96f69e0e | 231 | - .. _`CEC-TX-STATUS-ARB-LOST`: |
e2460b1d MH |
232 | |
233 | - ``CEC_TX_STATUS_ARB_LOST`` | |
234 | ||
235 | - 0x02 | |
236 | ||
237 | - CEC line arbitration was lost. | |
238 | ||
96f69e0e | 239 | - .. _`CEC-TX-STATUS-NACK`: |
e2460b1d MH |
240 | |
241 | - ``CEC_TX_STATUS_NACK`` | |
242 | ||
243 | - 0x04 | |
244 | ||
245 | - Message was not acknowledged. | |
246 | ||
96f69e0e | 247 | - .. _`CEC-TX-STATUS-LOW-DRIVE`: |
e2460b1d MH |
248 | |
249 | - ``CEC_TX_STATUS_LOW_DRIVE`` | |
250 | ||
251 | - 0x08 | |
252 | ||
253 | - Low drive was detected on the CEC bus. This indicates that a | |
706f8a99 MCC |
254 | follower detected an error on the bus and requests a |
255 | retransmission. | |
e2460b1d | 256 | |
96f69e0e | 257 | - .. _`CEC-TX-STATUS-ERROR`: |
e2460b1d MH |
258 | |
259 | - ``CEC_TX_STATUS_ERROR`` | |
260 | ||
261 | - 0x10 | |
262 | ||
263 | - Some error occurred. This is used for any errors that do not fit | |
706f8a99 MCC |
264 | the previous two, either because the hardware could not tell which |
265 | error occurred, or because the hardware tested for other | |
266 | conditions besides those two. | |
e2460b1d | 267 | |
96f69e0e | 268 | - .. _`CEC-TX-STATUS-MAX-RETRIES`: |
e2460b1d MH |
269 | |
270 | - ``CEC_TX_STATUS_MAX_RETRIES`` | |
271 | ||
272 | - 0x20 | |
273 | ||
274 | - The transmit failed after one or more retries. This status bit is | |
706f8a99 MCC |
275 | mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still |
276 | be set to explain which failures were seen. | |
e2460b1d MH |
277 | |
278 | ||
279 | ||
280 | .. _cec-rx-status: | |
281 | ||
282 | .. flat-table:: CEC Receive Status | |
283 | :header-rows: 0 | |
284 | :stub-columns: 0 | |
b2a58436 | 285 | :widths: 3 1 16 |
e2460b1d MH |
286 | |
287 | ||
96f69e0e | 288 | - .. _`CEC-RX-STATUS-OK`: |
e2460b1d MH |
289 | |
290 | - ``CEC_RX_STATUS_OK`` | |
291 | ||
292 | - 0x01 | |
293 | ||
294 | - The message was received successfully. | |
295 | ||
96f69e0e | 296 | - .. _`CEC-RX-STATUS-TIMEOUT`: |
e2460b1d MH |
297 | |
298 | - ``CEC_RX_STATUS_TIMEOUT`` | |
299 | ||
300 | - 0x02 | |
301 | ||
302 | - The reply to an earlier transmitted message timed out. | |
303 | ||
96f69e0e | 304 | - .. _`CEC-RX-STATUS-FEATURE-ABORT`: |
e2460b1d MH |
305 | |
306 | - ``CEC_RX_STATUS_FEATURE_ABORT`` | |
307 | ||
308 | - 0x04 | |
309 | ||
310 | - The message was received successfully but the reply was | |
706f8a99 MCC |
311 | ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message |
312 | was the reply to an earlier transmitted message. | |
e2460b1d MH |
313 | |
314 | ||
315 | ||
316 | Return Value | |
317 | ============ | |
318 | ||
319 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
320 | appropriately. The generic error codes are described at the | |
321 | :ref:`Generic Error Codes <gen-errors>` chapter. |