Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 1 | .. -*- coding: utf-8; mode: rst -*- |
| 2 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 3 | .. _CEC_TRANSMIT: |
| 4 | .. _CEC_RECEIVE: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 5 | |
| 6 | ******************************* |
| 7 | ioctl CEC_RECEIVE, CEC_TRANSMIT |
| 8 | ******************************* |
| 9 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 10 | Name |
| 11 | ==== |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 12 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 13 | CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 14 | |
| 15 | |
| 16 | Synopsis |
| 17 | ======== |
| 18 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 19 | .. cpp:function:: int ioctl( int fd, int request, struct cec_msg *argp ) |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 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 | |
| 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. |
| 38 | |
| 39 | To receive a CEC message the application has to fill in the |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 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. |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 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 |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 50 | :ref:`CEC_TRANSMIT` ioctl. :ref:`CEC_TRANSMIT` is only available if |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 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 |
| 60 | :widths: 1 1 2 |
| 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 |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 70 | :ref:`CEC_TRANSMIT` with ``reply`` set to 0, or the timestamp of the |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 71 | received message in all other cases. |
| 72 | |
| 73 | - .. row 2 |
| 74 | |
| 75 | - __u32 |
| 76 | |
| 77 | - ``len`` |
| 78 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 79 | - The length of the message. For :ref:`CEC_TRANSMIT` this is filled in |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 80 | by the application. The driver will fill this in for |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 81 | :ref:`CEC_RECEIVE` and for :ref:`CEC_TRANSMIT` it will be filled in with |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 82 | the length of the reply message if ``reply`` was set. |
| 83 | |
| 84 | - .. row 3 |
| 85 | |
| 86 | - __u32 |
| 87 | |
| 88 | - ``timeout`` |
| 89 | |
| 90 | - The timeout in milliseconds. This is the time the device will wait |
| 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 |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 93 | :ref:`CEC_RECEIVE`. If it is 0 and it is called by :ref:`CEC_TRANSMIT`, |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 94 | then it will be replaced by 1000 if the ``reply`` is non-zero or |
| 95 | ignored if ``reply`` is 0. |
| 96 | |
| 97 | - .. row 4 |
| 98 | |
| 99 | - __u32 |
| 100 | |
| 101 | - ``sequence`` |
| 102 | |
| 103 | - The sequence number is automatically assigned by the CEC framework |
| 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. |
| 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 |
| 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. |
| 127 | |
| 128 | - .. row 7 |
| 129 | |
| 130 | - __u8 |
| 131 | |
| 132 | - ``tx_status`` |
| 133 | |
| 134 | - The status bits of the transmitted message. See |
| 135 | :ref:`cec-tx-status` for the possible status values. It is 0 if |
| 136 | this messages was received, not transmitted. |
| 137 | |
| 138 | - .. row 8 |
| 139 | |
| 140 | - __u8 |
| 141 | |
| 142 | - ``msg``\ [16] |
| 143 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 144 | - The message payload. For :ref:`CEC_TRANSMIT` this is filled in by the |
| 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 |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 147 | reply message if ``reply`` was set. |
| 148 | |
| 149 | - .. row 9 |
| 150 | |
| 151 | - __u8 |
| 152 | |
| 153 | - ``reply`` |
| 154 | |
| 155 | - Wait until this message is replied. If ``reply`` is 0 and the |
| 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 |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 159 | both set to 0 by the driver. Ignored by :ref:`CEC_RECEIVE`. The case |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 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 |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 164 | to :ref:`CEC_RX_STATUS_TIMEOUT <CEC_RX_STATUS_TIMEOUT>` or :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC_RX_STATUS_FEATURE_ABORT>`. |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 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 |
| 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 |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 175 | :ref:`CEC_TX_STATUS_ARB_LOST <CEC_TX_STATUS_ARB_LOST>` status bit is set. |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 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 |
| 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 |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 186 | :ref:`CEC_TX_STATUS_NACK <CEC_TX_STATUS_NACK>` status bit is set. |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 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 |
| 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 |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 197 | :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC_TX_STATUS_LOW_DRIVE>` status bit is set. |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 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 |
| 206 | Lost or Not Acknowledged. This is only set if the hardware |
| 207 | supports this, otherwise it is always 0. This counter is only |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 208 | valid if the :ref:`CEC_TX_STATUS_ERROR <CEC_TX_STATUS_ERROR>` status bit is set. |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 209 | |
| 210 | |
| 211 | |
| 212 | .. _cec-tx-status: |
| 213 | |
| 214 | .. flat-table:: CEC Transmit Status |
| 215 | :header-rows: 0 |
| 216 | :stub-columns: 0 |
| 217 | :widths: 3 1 4 |
| 218 | |
| 219 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 220 | - .. _`CEC_TX_STATUS_OK`: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 221 | |
| 222 | - ``CEC_TX_STATUS_OK`` |
| 223 | |
| 224 | - 0x01 |
| 225 | |
| 226 | - The message was transmitted successfully. This is mutually |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 227 | exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC_TX_STATUS_MAX_RETRIES>`. Other bits can still |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 228 | be set if earlier attempts met with failure before the transmit |
| 229 | was eventually successful. |
| 230 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 231 | - .. _`CEC_TX_STATUS_ARB_LOST`: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 232 | |
| 233 | - ``CEC_TX_STATUS_ARB_LOST`` |
| 234 | |
| 235 | - 0x02 |
| 236 | |
| 237 | - CEC line arbitration was lost. |
| 238 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 239 | - .. _`CEC_TX_STATUS_NACK`: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 240 | |
| 241 | - ``CEC_TX_STATUS_NACK`` |
| 242 | |
| 243 | - 0x04 |
| 244 | |
| 245 | - Message was not acknowledged. |
| 246 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 247 | - .. _`CEC_TX_STATUS_LOW_DRIVE`: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 248 | |
| 249 | - ``CEC_TX_STATUS_LOW_DRIVE`` |
| 250 | |
| 251 | - 0x08 |
| 252 | |
| 253 | - Low drive was detected on the CEC bus. This indicates that a |
| 254 | follower detected an error on the bus and requests a |
| 255 | retransmission. |
| 256 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 257 | - .. _`CEC_TX_STATUS_ERROR`: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 258 | |
| 259 | - ``CEC_TX_STATUS_ERROR`` |
| 260 | |
| 261 | - 0x10 |
| 262 | |
| 263 | - Some error occurred. This is used for any errors that do not fit |
| 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. |
| 267 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 268 | - .. _`CEC_TX_STATUS_MAX_RETRIES`: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 269 | |
| 270 | - ``CEC_TX_STATUS_MAX_RETRIES`` |
| 271 | |
| 272 | - 0x20 |
| 273 | |
| 274 | - The transmit failed after one or more retries. This status bit is |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 275 | mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC_TX_STATUS_OK>`. Other bits can still |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 276 | be set to explain which failures were seen. |
| 277 | |
| 278 | |
| 279 | |
| 280 | .. _cec-rx-status: |
| 281 | |
| 282 | .. flat-table:: CEC Receive Status |
| 283 | :header-rows: 0 |
| 284 | :stub-columns: 0 |
| 285 | :widths: 3 1 4 |
| 286 | |
| 287 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 288 | - .. _`CEC_RX_STATUS_OK`: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 289 | |
| 290 | - ``CEC_RX_STATUS_OK`` |
| 291 | |
| 292 | - 0x01 |
| 293 | |
| 294 | - The message was received successfully. |
| 295 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 296 | - .. _CEC_RX_STATUS_TIMEOUT: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 297 | |
| 298 | - ``CEC_RX_STATUS_TIMEOUT`` |
| 299 | |
| 300 | - 0x02 |
| 301 | |
| 302 | - The reply to an earlier transmitted message timed out. |
| 303 | |
Markus Heiser | 21c6269 | 2016-07-08 20:55:43 +0200 | [diff] [blame^] | 304 | - .. _`CEC_RX_STATUS_FEATURE_ABORT`: |
Markus Heiser | e2460b1 | 2016-07-08 20:55:42 +0200 | [diff] [blame] | 305 | |
| 306 | - ``CEC_RX_STATUS_FEATURE_ABORT`` |
| 307 | |
| 308 | - 0x04 |
| 309 | |
| 310 | - The message was received successfully but the reply was |
| 311 | ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message |
| 312 | was the reply to an earlier transmitted message. |
| 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. |