401 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: CEC3 4.. _CEC_TRANSMIT:5.. _CEC_RECEIVE:6 7***********************************8ioctls CEC_RECEIVE and CEC_TRANSMIT9***********************************10 11Name12====13 14CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message15 16Synopsis17========18 19.. c:macro:: CEC_RECEIVE20 21``int ioctl(int fd, CEC_RECEIVE, struct cec_msg *argp)``22 23.. c:macro:: CEC_TRANSMIT24 25``int ioctl(int fd, CEC_TRANSMIT, struct cec_msg *argp)``26 27Arguments28=========29 30``fd``31 File descriptor returned by :c:func:`open()`.32 33``argp``34 Pointer to struct cec_msg.35 36Description37===========38 39To receive a CEC message the application has to fill in the40``timeout`` field of struct :c:type:`cec_msg` and pass it to41:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.42If the file descriptor is in non-blocking mode and there are no received43messages pending, then it will return -1 and set errno to the ``EAGAIN``44error code. If the file descriptor is in blocking mode and ``timeout``45is non-zero and no message arrived within ``timeout`` milliseconds, then46it will return -1 and set errno to the ``ETIMEDOUT`` error code.47 48A received message can be:49 501. a message received from another CEC device (the ``sequence`` field will51 be 0, ``tx_status`` will be 0 and ``rx_status`` will be non-zero).522. the transmit result of an earlier non-blocking transmit (the ``sequence``53 field will be non-zero, ``tx_status`` will be non-zero and ``rx_status``54 will be 0).553. the reply to an earlier non-blocking transmit (the ``sequence`` field will56 be non-zero, ``tx_status`` will be 0 and ``rx_status`` will be non-zero).57 58To send a CEC message the application has to fill in the struct59:c:type:`cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.60The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if61``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit62queue, then it will return -1 and set errno to the ``EBUSY`` error code.63The transmit queue has enough room for 18 messages (about 1 second worth64of 2-byte messages). Note that the CEC kernel framework will also reply65to core messages (see :ref:`cec-core-processing`), so it is not a good66idea to fully fill up the transmit queue.67 68If the file descriptor is in non-blocking mode then the transmit will69return 0 and the result of the transmit will be available via70:ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished.71If a non-blocking transmit also specified waiting for a reply, then72the reply will arrive in a later message. The ``sequence`` field can73be used to associate both transmit results and replies with the original74transmit.75 76Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical77address is invalid (due to e.g. a disconnect) will return ``ENONET``.78 79However, the CEC specification allows sending messages from 'Unregistered' to80'TV' when the physical address is invalid since some TVs pull the hotplug detect81pin of the HDMI connector low when they go into standby, or when switching to82another input.83 84When the hotplug detect pin goes low the EDID disappears, and thus the85physical address, but the cable is still connected and CEC still works.86In order to detect/wake up the device it is allowed to send poll and 'Image/Text87View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').88 89.. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{12.8cm}|90 91.. c:type:: cec_msg92 93.. cssclass:: longtable94 95.. flat-table:: struct cec_msg96 :header-rows: 097 :stub-columns: 098 :widths: 1 1 1699 100 * - __u64101 - ``tx_ts``102 - Timestamp in ns of when the last byte of the message was transmitted.103 The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access104 the same clock from userspace use :c:func:`clock_gettime`.105 * - __u64106 - ``rx_ts``107 - Timestamp in ns of when the last byte of the message was received.108 The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access109 the same clock from userspace use :c:func:`clock_gettime`.110 * - __u32111 - ``len``112 - The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in113 by the application. The driver will fill this in for114 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be115 filled in by the driver with the length of the reply message if ``reply`` was set.116 * - __u32117 - ``timeout``118 - The timeout in milliseconds. This is the time the device will wait119 for a message to be received before timing out. If it is set to 0,120 then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.121 If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,122 then it will be replaced by 1000 if the ``reply`` is non-zero or123 ignored if ``reply`` is 0.124 * - __u32125 - ``sequence``126 - A non-zero sequence number is automatically assigned by the CEC framework127 for all transmitted messages. It is used by the CEC framework when it queues128 the transmit result for a non-blocking transmit. This allows the application129 to associate the received message with the original transmit.130 131 In addition, if a non-blocking transmit will wait for a reply (ii.e. ``timeout``132 was not 0), then the ``sequence`` field of the reply will be set to the sequence133 value of the original transmit. This allows the application to associate the134 received message with the original transmit.135 * - __u32136 - ``flags``137 - Flags. See :ref:`cec-msg-flags` for a list of available flags.138 * - __u8139 - ``msg[16]``140 - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the141 application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.142 For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with143 the payload of the reply message if ``timeout`` was set.144 * - __u8145 - ``reply``146 - Wait until this message is replied. If ``reply`` is 0 and the147 ``timeout`` is 0, then don't wait for a reply but return after148 transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.149 The case where ``reply`` is 0 (this is the opcode for the Feature Abort150 message) and ``timeout`` is non-zero is specifically allowed to make it151 possible to send a message and wait up to ``timeout`` milliseconds for a152 Feature Abort reply. In this case ``rx_status`` will either be set153 to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or154 :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.155 156 If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply``157 values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED``158 are processed differently: either value will match both possible replies.159 The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC160 message that has two possible replies other than Feature Abort. The161 ``reply`` field will be updated with the actual reply so that it is162 synchronized with the contents of the received message.163 * - __u8164 - ``rx_status``165 - The status bits of the received message. See166 :ref:`cec-rx-status` for the possible status values.167 * - __u8168 - ``tx_status``169 - The status bits of the transmitted message. See170 :ref:`cec-tx-status` for the possible status values.171 When calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` in non-blocking mode,172 this field will be 0 if the transmit started, or non-0 if the transmit173 result is known immediately. The latter would be the case when attempting174 to transmit a Poll message to yourself. That results in a175 :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` without ever actually176 transmitting the Poll message.177 * - __u8178 - ``tx_arb_lost_cnt``179 - A counter of the number of transmit attempts that resulted in the180 Arbitration Lost error. This is only set if the hardware supports181 this, otherwise it is always 0. This counter is only valid if the182 :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.183 * - __u8184 - ``tx_nack_cnt``185 - A counter of the number of transmit attempts that resulted in the186 Not Acknowledged error. This is only set if the hardware supports187 this, otherwise it is always 0. This counter is only valid if the188 :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.189 * - __u8190 - ``tx_low_drive_cnt``191 - A counter of the number of transmit attempts that resulted in the192 Arbitration Lost error. This is only set if the hardware supports193 this, otherwise it is always 0. This counter is only valid if the194 :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.195 * - __u8196 - ``tx_error_cnt``197 - A counter of the number of transmit errors other than Arbitration198 Lost or Not Acknowledged. This is only set if the hardware199 supports this, otherwise it is always 0. This counter is only200 valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.201 202.. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.1cm}|203 204.. _cec-msg-flags:205 206.. flat-table:: Flags for struct cec_msg207 :header-rows: 0208 :stub-columns: 0209 :widths: 3 1 4210 211 * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:212 213 - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``214 - 1215 - If a CEC transmit expects a reply, then by default that reply is only sent to216 the filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If this217 flag is set, then the reply is also sent to all followers, if any. If the218 filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is also a219 follower, then that filehandle will receive the reply twice: once as the220 result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via221 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.222 223 * .. _`CEC-MSG-FL-RAW`:224 225 - ``CEC_MSG_FL_RAW``226 - 2227 - Normally CEC messages are validated before transmitting them. If this228 flag is set when :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is called,229 then no validation takes place and the message is transmitted as-is.230 This is useful when debugging CEC issues.231 This flag is only allowed if the process has the ``CAP_SYS_RAWIO``232 capability. If that is not set, then the ``EPERM`` error code is233 returned.234 235 * .. _`CEC-MSG-FL-REPLY-VENDOR-ID`:236 237 - ``CEC_MSG_FL_REPLY_VENDOR_ID``238 - 4239 - This flag is only available if the ``CEC_CAP_REPLY_VENDOR_ID`` capability240 is set. If this flag is set, then the reply is expected to consist of241 the ``CEC_MSG_VENDOR_COMMAND_WITH_ID`` opcode followed by the Vendor ID242 (in bytes 1-4 of the message), followed by the ``struct cec_msg``243 ``reply`` field.244 245 Note that this assumes that the byte after the Vendor ID is a246 vendor-specific opcode.247 248 This flag makes it easier to wait for replies to vendor commands.249 250.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}|251 252.. _cec-tx-status:253 254.. flat-table:: CEC Transmit Status255 :header-rows: 0256 :stub-columns: 0257 :widths: 3 1 16258 259 * .. _`CEC-TX-STATUS-OK`:260 261 - ``CEC_TX_STATUS_OK``262 - 0x01263 - The message was transmitted successfully. This is mutually264 exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`.265 Other bits can still be set if earlier attempts met with failure before266 the transmit was eventually successful.267 * .. _`CEC-TX-STATUS-ARB-LOST`:268 269 - ``CEC_TX_STATUS_ARB_LOST``270 - 0x02271 - CEC line arbitration was lost, i.e. another transmit started at the272 same time with a higher priority. Optional status, not all hardware273 can detect this error condition.274 * .. _`CEC-TX-STATUS-NACK`:275 276 - ``CEC_TX_STATUS_NACK``277 - 0x04278 - Message was not acknowledged. Note that some hardware cannot tell apart279 a 'Not Acknowledged' status from other error conditions, i.e. the result280 of a transmit is just OK or FAIL. In that case this status will be281 returned when the transmit failed.282 * .. _`CEC-TX-STATUS-LOW-DRIVE`:283 284 - ``CEC_TX_STATUS_LOW_DRIVE``285 - 0x08286 - Low drive was detected on the CEC bus. This indicates that a287 follower detected an error on the bus and requests a288 retransmission. Optional status, not all hardware can detect this289 error condition.290 * .. _`CEC-TX-STATUS-ERROR`:291 292 - ``CEC_TX_STATUS_ERROR``293 - 0x10294 - Some error occurred. This is used for any errors that do not fit295 ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because296 the hardware could not tell which error occurred, or because the hardware297 tested for other conditions besides those two. Optional status.298 * .. _`CEC-TX-STATUS-MAX-RETRIES`:299 300 - ``CEC_TX_STATUS_MAX_RETRIES``301 - 0x20302 - The transmit failed after one or more retries. This status bit is303 mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`.304 Other bits can still be set to explain which failures were seen.305 * .. _`CEC-TX-STATUS-ABORTED`:306 307 - ``CEC_TX_STATUS_ABORTED``308 - 0x40309 - The transmit was aborted due to an HDMI disconnect, or the adapter310 was unconfigured, or a transmit was interrupted, or the driver311 returned an error when attempting to start a transmit.312 * .. _`CEC-TX-STATUS-TIMEOUT`:313 314 - ``CEC_TX_STATUS_TIMEOUT``315 - 0x80316 - The transmit timed out. This should not normally happen and this317 indicates a driver problem.318 319.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}|320 321.. _cec-rx-status:322 323.. flat-table:: CEC Receive Status324 :header-rows: 0325 :stub-columns: 0326 :widths: 3 1 16327 328 * .. _`CEC-RX-STATUS-OK`:329 330 - ``CEC_RX_STATUS_OK``331 - 0x01332 - The message was received successfully.333 * .. _`CEC-RX-STATUS-TIMEOUT`:334 335 - ``CEC_RX_STATUS_TIMEOUT``336 - 0x02337 - The reply to an earlier transmitted message timed out.338 * .. _`CEC-RX-STATUS-FEATURE-ABORT`:339 340 - ``CEC_RX_STATUS_FEATURE_ABORT``341 - 0x04342 - The message was received successfully but the reply was343 ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message344 was the reply to an earlier transmitted message.345 * .. _`CEC-RX-STATUS-ABORTED`:346 347 - ``CEC_RX_STATUS_ABORTED``348 - 0x08349 - The wait for a reply to an earlier transmitted message was aborted350 because the HDMI cable was disconnected, the adapter was unconfigured351 or the :ref:`CEC_TRANSMIT <CEC_RECEIVE>` that waited for a352 reply was interrupted.353 354 355Return Value356============357 358On success 0 is returned, on error -1 and the ``errno`` variable is set359appropriately. The generic error codes are described at the360:ref:`Generic Error Codes <gen-errors>` chapter.361 362The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can return the following363error codes:364 365EAGAIN366 No messages are in the receive queue, and the filehandle is in non-blocking mode.367 368ETIMEDOUT369 The ``timeout`` was reached while waiting for a message.370 371ERESTARTSYS372 The wait for a message was interrupted (e.g. by Ctrl-C).373 374The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` can return the following375error codes:376 377ENOTTY378 The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported.379 380EPERM381 The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`382 has never been called, or ``CEC_MSG_FL_RAW`` was used from a process that383 did not have the ``CAP_SYS_RAWIO`` capability.384 385ENONET386 The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`387 was called, but the physical address is invalid so no logical address was claimed.388 An exception is made in this case for transmits from initiator 0xf ('Unregistered')389 to destination 0 ('TV'). In that case the transmit will proceed as usual.390 391EBUSY392 Another filehandle is in exclusive follower or initiator mode, or the filehandle393 is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit394 queue is full.395 396EINVAL397 The contents of struct :c:type:`cec_msg` is invalid.398 399ERESTARTSYS400 The wait for a successful transmit was interrupted (e.g. by Ctrl-C).401