Documentation/media/uapi/cec/cec-ioc-receive.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _CEC_TRANSMIT:
   4 .. _CEC_RECEIVE:
   5
   6 ***********************************
   7 ioctls CEC_RECEIVE and CEC_TRANSMIT
   8 ***********************************
   9
  10 Name
  11 ====
  12
  13 CEC_RECEIVE, CEC_TRANSMIT - Receive or transmit a CEC message
  14
  15
  16 Synopsis
  17 ========
  18
  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
  24
  25 Arguments
  26 =========
  27
  28 ``fd``
  29     File descriptor returned by :c:func:`open() <cec-open>`.
  30
  31 ``argp``
  32     Pointer to struct cec_msg.
  33
  34 Description
  35 ===========
  36
  37 To receive a CEC message the application has to fill in the
  38 ``timeout`` field of struct :c:type:`cec_msg` and pass it to
  39 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
  40 If the file descriptor is in non-blocking mode and there are no received
  41 messages pending, then it will return -1 and set errno to the ``EAGAIN``
  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
  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).
  52
  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
  56 ``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
  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.
  71
  72 Normally calling :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` when the physical
  73 address is invalid (due to e.g. a disconnect) will return ``ENONET``.
  74
  75 However, the CEC specification allows sending messages from 'Unregistered' to
  76 'TV' when the physical address is invalid since some TVs pull the hotplug detect
  77 pin of the HDMI connector low when they go into standby, or when switching to
  78 another input.
  79
  80 When the hotplug detect pin goes low the EDID disappears, and thus the
  81 physical address, but the cable is still connected and CEC still works.
  82 In order to detect/wake up the device it is allowed to send poll and 'Image/Text
  83 View On' messages from initiator 0xf ('Unregistered') to destination 0 ('TV').
  84
  85 .. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}|
  86
  87 .. c:type:: cec_msg
  88
  89 .. cssclass:: longtable
  90
  91 .. flat-table:: struct cec_msg
  92     :header-rows:  0
  93     :stub-columns: 0
  94     :widths:       1 1 16
  95
  96     * - __u64
  97       - ``tx_ts``
  98       - Timestamp in ns of when the last byte of the message was transmitted.
  99         The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
 100         the same clock from userspace use :c:func:`clock_gettime`.
 101     * - __u64
 102       - ``rx_ts``
 103       - Timestamp in ns of when the last byte of the message was received.
 104         The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
 105         the same clock from userspace use :c:func:`clock_gettime`.
 106     * - __u32
 107       - ``len``
 108       - The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
 109         by the application. The driver will fill this in for
 110         :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be
 111         filled in by the driver with the length of the reply message if ``reply`` was set.
 112     * - __u32
 113       - ``timeout``
 114       - The timeout in milliseconds. This is the time the device will wait
 115         for a message to be received before timing out. If it is set to 0,
 116         then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 117         If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
 118         then it will be replaced by 1000 if the ``reply`` is non-zero or
 119         ignored if ``reply`` is 0.
 120     * - __u32
 121       - ``sequence``
 122       - A non-zero sequence number is automatically assigned by the CEC framework
 123         for all transmitted messages. It is used by the CEC framework when it queues
 124         the transmit result (when transmit was called in non-blocking mode). This
 125         allows the application to associate the received message with the original
 126         transmit.
 127     * - __u32
 128       - ``flags``
 129       - Flags. See :ref:`cec-msg-flags` for a list of available flags.
 130     * - __u8
 131       - ``tx_status``
 132       - The status bits of the transmitted message. See
 133         :ref:`cec-tx-status` for the possible status values. It is 0 if
 134         this message was received, not transmitted.
 135     * - __u8
 136       - ``msg[16]``
 137       - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
 138         application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 139         For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
 140         the payload of the reply message if ``timeout`` was set.
 141     * - __u8
 142       - ``reply``
 143       - Wait until this message is replied. If ``reply`` is 0 and the
 144         ``timeout`` is 0, then don't wait for a reply but return after
 145         transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 146         The case where ``reply`` is 0 (this is the opcode for the Feature Abort
 147         message) and ``timeout`` is non-zero is specifically allowed to make it
 148         possible to send a message and wait up to ``timeout`` milliseconds for a
 149         Feature Abort reply. In this case ``rx_status`` will either be set
 150         to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
 151         :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
 152
 153         If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply``
 154         values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED``
 155         are processed differently: either value will match both possible replies.
 156         The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC
 157         message that has two possible replies other than Feature Abort. The
 158         ``reply`` field will be updated with the actual reply so that it is
 159         synchronized with the contents of the received message.
 160     * - __u8
 161       - ``rx_status``
 162       - The status bits of the received message. See
 163         :ref:`cec-rx-status` for the possible status values. It is 0 if
 164         this message was transmitted, not received, unless this is the
 165         reply to a transmitted message. In that case both ``rx_status``
 166         and ``tx_status`` are set.
 167     * - __u8
 168       - ``tx_status``
 169       - The status bits of the transmitted message. See
 170         :ref:`cec-tx-status` for the possible status values. It is 0 if
 171         this message was received, not transmitted.
 172     * - __u8
 173       - ``tx_arb_lost_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_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
 178     * - __u8
 179       - ``tx_nack_cnt``
 180       - A counter of the number of transmit attempts that resulted in the
 181         Not Acknowledged error. This is only set if the hardware supports
 182         this, otherwise it is always 0. This counter is only valid if the
 183         :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
 184     * - __u8
 185       - ``tx_low_drive_cnt``
 186       - A counter of the number of transmit attempts that resulted in the
 187         Arbitration Lost error. This is only set if the hardware supports
 188         this, otherwise it is always 0. This counter is only valid if the
 189         :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
 190     * - __u8
 191       - ``tx_error_cnt``
 192       - A counter of the number of transmit errors other than Arbitration
 193         Lost or Not Acknowledged. This is only set if the hardware
 194         supports this, otherwise it is always 0. This counter is only
 195         valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
 196
 197
 198 .. tabularcolumns:: |p{6.2cm}|p{1.0cm}|p{10.3cm}|
 199
 200 .. _cec-msg-flags:
 201
 202 .. flat-table:: Flags for struct cec_msg
 203     :header-rows:  0
 204     :stub-columns: 0
 205     :widths:       3 1 4
 206
 207     * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
 208
 209       - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``
 210       - 1
 211       - If a CEC transmit expects a reply, then by default that reply is only sent to
 212         the filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If this
 213         flag is set, then the reply is also sent to all followers, if any. If the
 214         filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is also a
 215         follower, then that filehandle will receive the reply twice: once as the
 216         result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via
 217         :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 218
 219
 220 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 221
 222 .. _cec-tx-status:
 223
 224 .. flat-table:: CEC Transmit Status
 225     :header-rows:  0
 226     :stub-columns: 0
 227     :widths:       3 1 16
 228
 229     * .. _`CEC-TX-STATUS-OK`:
 230
 231       - ``CEC_TX_STATUS_OK``
 232       - 0x01
 233       - The message was transmitted successfully. This is mutually
 234         exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still
 235         be set if earlier attempts met with failure before the transmit
 236         was eventually successful.
 237     * .. _`CEC-TX-STATUS-ARB-LOST`:
 238
 239       - ``CEC_TX_STATUS_ARB_LOST``
 240       - 0x02
 241       - CEC line arbitration was lost.
 242     * .. _`CEC-TX-STATUS-NACK`:
 243
 244       - ``CEC_TX_STATUS_NACK``
 245       - 0x04
 246       - Message was not acknowledged.
 247     * .. _`CEC-TX-STATUS-LOW-DRIVE`:
 248
 249       - ``CEC_TX_STATUS_LOW_DRIVE``
 250       - 0x08
 251       - Low drive was detected on the CEC bus. This indicates that a
 252         follower detected an error on the bus and requests a
 253         retransmission.
 254     * .. _`CEC-TX-STATUS-ERROR`:
 255
 256       - ``CEC_TX_STATUS_ERROR``
 257       - 0x10
 258       - Some error occurred. This is used for any errors that do not fit
 259         ``CEC_TX_STATUS_ARB_LOST`` or ``CEC_TX_STATUS_LOW_DRIVE``, either because
 260         the hardware could not tell which error occurred, or because the hardware
 261         tested for other conditions besides those two.
 262     * .. _`CEC-TX-STATUS-MAX-RETRIES`:
 263
 264       - ``CEC_TX_STATUS_MAX_RETRIES``
 265       - 0x20
 266       - The transmit failed after one or more retries. This status bit is
 267         mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still
 268         be set to explain which failures were seen.
 269
 270
 271 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 272
 273 .. _cec-rx-status:
 274
 275 .. flat-table:: CEC Receive Status
 276     :header-rows:  0
 277     :stub-columns: 0
 278     :widths:       3 1 16
 279
 280     * .. _`CEC-RX-STATUS-OK`:
 281
 282       - ``CEC_RX_STATUS_OK``
 283       - 0x01
 284       - The message was received successfully.
 285     * .. _`CEC-RX-STATUS-TIMEOUT`:
 286
 287       - ``CEC_RX_STATUS_TIMEOUT``
 288       - 0x02
 289       - The reply to an earlier transmitted message timed out.
 290     * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
 291
 292       - ``CEC_RX_STATUS_FEATURE_ABORT``
 293       - 0x04
 294       - The message was received successfully but the reply was
 295         ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
 296         was the reply to an earlier transmitted message.
 297
 298
 299
 300 Return Value
 301 ============
 302
 303 On success 0 is returned, on error -1 and the ``errno`` variable is set
 304 appropriately. The generic error codes are described at the
 305 :ref:`Generic Error Codes <gen-errors>` chapter.
 306
 307 The :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` can return the following
 308 error codes:
 309
 310 EAGAIN
 311     No messages are in the receive queue, and the filehandle is in non-blocking mode.
 312
 313 ETIMEDOUT
 314     The ``timeout`` was reached while waiting for a message.
 315
 316 ERESTARTSYS
 317     The wait for a message was interrupted (e.g. by Ctrl-C).
 318
 319 The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` can return the following
 320 error codes:
 321
 322 ENOTTY
 323     The ``CEC_CAP_TRANSMIT`` capability wasn't set, so this ioctl is not supported.
 324
 325 EPERM
 326     The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
 327     has never been called.
 328
 329 ENONET
 330     The CEC adapter is not configured, i.e. :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
 331     was called, but the physical address is invalid so no logical address was claimed.
 332     An exception is made in this case for transmits from initiator 0xf ('Unregistered')
 333     to destination 0 ('TV'). In that case the transmit will proceed as usual.
 334
 335 EBUSY
 336     Another filehandle is in exclusive follower or initiator mode, or the filehandle
 337     is in mode ``CEC_MODE_NO_INITIATOR``. This is also returned if the transmit
 338     queue is full.
 339
 340 EINVAL
 341     The contents of struct :c:type:`cec_msg` is invalid.
 342
 343 ERESTARTSYS
 344     The wait for a successful transmit was interrupted (e.g. by Ctrl-C).