]>
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 | ||
99547836 MCC |
19 | .. c:function:: int ioctl( int fd, CEC_RECEIVE, struct cec_msg *argp ) |
20 | :name: CEC_RECEIVE | |
21 | ||
22 | .. c:function:: int ioctl( int fd, CEC_TRANSMIT, struct cec_msg *argp ) | |
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 MCC |
53 | To send a CEC message the application has to fill in the struct |
54 | :c:type:` cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. | |
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 | |
60 | to core messages (see :ref:cec-core-processing), so it is not a good | |
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 MH |
71 | |
72 | ||
0d6821ec | 73 | .. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}| |
5bd4bb78 | 74 | |
e8be7e97 | 75 | .. c:type:: cec_msg |
fa92b04d | 76 | |
b7824341 MCC |
77 | .. cssclass:: longtable |
78 | ||
e2460b1d MH |
79 | .. flat-table:: struct cec_msg |
80 | :header-rows: 0 | |
81 | :stub-columns: 0 | |
b2a58436 | 82 | :widths: 1 1 16 |
e2460b1d | 83 | |
77edf603 HV |
84 | * - __u64 |
85 | - ``tx_ts`` | |
86 | - Timestamp in ns of when the last byte of the message was transmitted. | |
87 | The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access | |
88 | the same clock from userspace use :c:func:`clock_gettime`. | |
89 | * - __u64 | |
90 | - ``rx_ts`` | |
91 | - Timestamp in ns of when the last byte of the message was received. | |
92 | The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access | |
93 | the same clock from userspace use :c:func:`clock_gettime`. | |
94 | * - __u32 | |
95 | - ``len`` | |
96 | - The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in | |
97 | by the application. The driver will fill this in for | |
98 | :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be | |
99 | filled in by the driver with the length of the reply message if ``reply`` was set. | |
100 | * - __u32 | |
101 | - ``timeout`` | |
102 | - The timeout in milliseconds. This is the time the device will wait | |
103 | for a message to be received before timing out. If it is set to 0, | |
104 | then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. | |
105 | If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, | |
106 | then it will be replaced by 1000 if the ``reply`` is non-zero or | |
107 | ignored if ``reply`` is 0. | |
108 | * - __u32 | |
109 | - ``sequence`` | |
110 | - A non-zero sequence number is automatically assigned by the CEC framework | |
111 | for all transmitted messages. It is used by the CEC framework when it queues | |
112 | the transmit result (when transmit was called in non-blocking mode). This | |
113 | allows the application to associate the received message with the original | |
114 | transmit. | |
115 | * - __u32 | |
116 | - ``flags`` | |
adc0c622 | 117 | - Flags. See :ref:`cec-msg-flags` for a list of available flags. |
77edf603 HV |
118 | * - __u8 |
119 | - ``tx_status`` | |
120 | - The status bits of the transmitted message. See | |
121 | :ref:`cec-tx-status` for the possible status values. It is 0 if | |
122 | this messages was received, not transmitted. | |
123 | * - __u8 | |
124 | - ``msg[16]`` | |
125 | - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the | |
126 | application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. | |
127 | For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with | |
128 | the payload of the reply message if ``timeout`` was set. | |
129 | * - __u8 | |
130 | - ``reply`` | |
131 | - Wait until this message is replied. If ``reply`` is 0 and the | |
132 | ``timeout`` is 0, then don't wait for a reply but return after | |
133 | transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. | |
134 | The case where ``reply`` is 0 (this is the opcode for the Feature Abort | |
135 | message) and ``timeout`` is non-zero is specifically allowed to make it | |
136 | possible to send a message and wait up to ``timeout`` milliseconds for a | |
137 | Feature Abort reply. In this case ``rx_status`` will either be set | |
138 | to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or | |
139 | :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`. | |
f5580d8d HV |
140 | |
141 | If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply`` | |
142 | values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED`` | |
143 | are processed differently: either value will match both possible replies. | |
144 | The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC | |
145 | message that has two possible replies other than Feature Abort. The | |
146 | ``reply`` field will be updated with the actual reply so that it is | |
147 | synchronized with the contents of the received message. | |
77edf603 HV |
148 | * - __u8 |
149 | - ``rx_status`` | |
150 | - The status bits of the received message. See | |
151 | :ref:`cec-rx-status` for the possible status values. It is 0 if | |
152 | this message was transmitted, not received, unless this is the | |
153 | reply to a transmitted message. In that case both ``rx_status`` | |
154 | and ``tx_status`` are set. | |
155 | * - __u8 | |
156 | - ``tx_status`` | |
157 | - The status bits of the transmitted message. See | |
158 | :ref:`cec-tx-status` for the possible status values. It is 0 if | |
159 | this messages was received, not transmitted. | |
160 | * - __u8 | |
161 | - ``tx_arb_lost_cnt`` | |
162 | - A counter of the number of transmit attempts that resulted in the | |
163 | Arbitration Lost error. This is only set if the hardware supports | |
164 | this, otherwise it is always 0. This counter is only valid if the | |
165 | :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set. | |
166 | * - __u8 | |
167 | - ``tx_nack_cnt`` | |
168 | - A counter of the number of transmit attempts that resulted in the | |
169 | Not Acknowledged error. This is only set if the hardware supports | |
170 | this, otherwise it is always 0. This counter is only valid if the | |
171 | :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set. | |
172 | * - __u8 | |
173 | - ``tx_low_drive_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_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set. | |
178 | * - __u8 | |
179 | - ``tx_error_cnt`` | |
180 | - A counter of the number of transmit errors other than Arbitration | |
181 | Lost or Not Acknowledged. This is only set if the hardware | |
182 | supports this, otherwise it is always 0. This counter is only | |
183 | valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set. | |
e2460b1d MH |
184 | |
185 | ||
adc0c622 HV |
186 | .. _cec-msg-flags: |
187 | ||
188 | .. flat-table:: Flags for struct cec_msg | |
189 | :header-rows: 0 | |
190 | :stub-columns: 0 | |
191 | :widths: 3 1 4 | |
192 | ||
193 | * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`: | |
194 | ||
195 | - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS`` | |
196 | - 1 | |
197 | - If a CEC transmit expects a reply, then by default that reply is only sent to | |
198 | the filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If this | |
199 | flag is set, then the reply is also sent to all followers, if any. If the | |
200 | filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is also a | |
201 | follower, then that filehandle will receive the reply twice: once as the | |
202 | result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via | |
203 | :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. | |
204 | ||
205 | ||
fa92b04d | 206 | .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| |
e2460b1d MH |
207 | |
208 | .. _cec-tx-status: | |
209 | ||
210 | .. flat-table:: CEC Transmit Status | |
211 | :header-rows: 0 | |
212 | :stub-columns: 0 | |
b2a58436 | 213 | :widths: 3 1 16 |
e2460b1d | 214 | |
77edf603 HV |
215 | * .. _`CEC-TX-STATUS-OK`: |
216 | ||
217 | - ``CEC_TX_STATUS_OK`` | |
218 | - 0x01 | |
219 | - The message was transmitted successfully. This is mutually | |
220 | exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still | |
221 | be set if earlier attempts met with failure before the transmit | |
222 | was eventually successful. | |
223 | * .. _`CEC-TX-STATUS-ARB-LOST`: | |
224 | ||
225 | - ``CEC_TX_STATUS_ARB_LOST`` | |
226 | - 0x02 | |
227 | - CEC line arbitration was lost. | |
228 | * .. _`CEC-TX-STATUS-NACK`: | |
229 | ||
230 | - ``CEC_TX_STATUS_NACK`` | |
231 | - 0x04 | |
232 | - Message was not acknowledged. | |
233 | * .. _`CEC-TX-STATUS-LOW-DRIVE`: | |
234 | ||
235 | - ``CEC_TX_STATUS_LOW_DRIVE`` | |
236 | - 0x08 | |
237 | - Low drive was detected on the CEC bus. This indicates that a | |
238 | follower detected an error on the bus and requests a | |
239 | retransmission. | |
240 | * .. _`CEC-TX-STATUS-ERROR`: | |
241 | ||
242 | - ``CEC_TX_STATUS_ERROR`` | |
243 | - 0x10 | |
244 | - Some error occurred. This is used for any errors that do not fit | |
245 | the previous two, either because the hardware could not tell which | |
246 | error occurred, or because the hardware tested for other | |
247 | conditions besides those two. | |
248 | * .. _`CEC-TX-STATUS-MAX-RETRIES`: | |
249 | ||
250 | - ``CEC_TX_STATUS_MAX_RETRIES`` | |
251 | - 0x20 | |
252 | - The transmit failed after one or more retries. This status bit is | |
253 | mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still | |
254 | be set to explain which failures were seen. | |
e2460b1d MH |
255 | |
256 | ||
fa92b04d | 257 | .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| |
e2460b1d MH |
258 | |
259 | .. _cec-rx-status: | |
260 | ||
261 | .. flat-table:: CEC Receive Status | |
262 | :header-rows: 0 | |
263 | :stub-columns: 0 | |
b2a58436 | 264 | :widths: 3 1 16 |
e2460b1d | 265 | |
77edf603 | 266 | * .. _`CEC-RX-STATUS-OK`: |
e2460b1d | 267 | |
77edf603 HV |
268 | - ``CEC_RX_STATUS_OK`` |
269 | - 0x01 | |
270 | - The message was received successfully. | |
271 | * .. _`CEC-RX-STATUS-TIMEOUT`: | |
e2460b1d | 272 | |
77edf603 HV |
273 | - ``CEC_RX_STATUS_TIMEOUT`` |
274 | - 0x02 | |
275 | - The reply to an earlier transmitted message timed out. | |
276 | * .. _`CEC-RX-STATUS-FEATURE-ABORT`: | |
e2460b1d | 277 | |
77edf603 HV |
278 | - ``CEC_RX_STATUS_FEATURE_ABORT`` |
279 | - 0x04 | |
280 | - The message was received successfully but the reply was | |
281 | ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message | |
282 | was the reply to an earlier transmitted message. | |
e2460b1d MH |
283 | |
284 | ||
285 | ||
286 | Return Value | |
287 | ============ | |
288 | ||
289 | On success 0 is returned, on error -1 and the ``errno`` variable is set | |
290 | appropriately. The generic error codes are described at the | |
291 | :ref:`Generic Error Codes <gen-errors>` chapter. |