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