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
  73 .. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}|
  74
  75 .. c:type:: cec_msg
  76
  77 .. cssclass:: longtable
  78
  79 .. flat-table:: struct cec_msg
  80     :header-rows:  0
  81     :stub-columns: 0
  82     :widths:       1 1 16
  83
  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``
 117       - Flags. See :ref:`cec-msg-flags` for a list of available flags.
 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>`.
 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.
 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.
 184
 185
 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
 206 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 207
 208 .. _cec-tx-status:
 209
 210 .. flat-table:: CEC Transmit Status
 211     :header-rows:  0
 212     :stub-columns: 0
 213     :widths:       3 1 16
 214
 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.
 255
 256
 257 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 258
 259 .. _cec-rx-status:
 260
 261 .. flat-table:: CEC Receive Status
 262     :header-rows:  0
 263     :stub-columns: 0
 264     :widths:       3 1 16
 265
 266     * .. _`CEC-RX-STATUS-OK`:
 267
 268       - ``CEC_RX_STATUS_OK``
 269       - 0x01
 270       - The message was received successfully.
 271     * .. _`CEC-RX-STATUS-TIMEOUT`:
 272
 273       - ``CEC_RX_STATUS_TIMEOUT``
 274       - 0x02
 275       - The reply to an earlier transmitted message timed out.
 276     * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
 277
 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.
 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.