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 .. note::
  38
  39    This documents the proposed CEC API. This API is not yet finalized
  40    and is currently only available as a staging kernel module.
  41
  42 To receive a CEC message the application has to fill in the
  43 ``timeout`` field of struct :c:type:`cec_msg` and pass it to
  44 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
  45 If the file descriptor is in non-blocking mode and there are no received
  46 messages pending, then it will return -1 and set errno to the ``EAGAIN``
  47 error code. If the file descriptor is in blocking mode and ``timeout``
  48 is non-zero and no message arrived within ``timeout`` milliseconds, then
  49 it will return -1 and set errno to the ``ETIMEDOUT`` error code.
  50
  51 A received message can be:
  52
  53 1. a message received from another CEC device (the ``sequence`` field will
  54    be 0).
  55 2. the result of an earlier non-blocking transmit (the ``sequence`` field will
  56    be non-zero).
  57
  58 To send a CEC message the application has to fill in the struct
  59 :c:type:` cec_msg` and pass it to :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
  60 The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if
  61 ``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
  62 queue, then it will return -1 and set errno to the ``EBUSY`` error code.
  63 The transmit queue has enough room for 18 messages (about 1 second worth
  64 of 2-byte messages). Note that the CEC kernel framework will also reply
  65 to core messages (see :ref:cec-core-processing), so it is not a good
  66 idea to fully fill up the transmit queue.
  67
  68 If the file descriptor is in non-blocking mode then the transmit will
  69 return 0 and the result of the transmit will be available via
  70 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished
  71 (including waiting for a reply, if requested).
  72
  73 The ``sequence`` field is filled in for every transmit and this can be
  74 checked against the received messages to find the corresponding transmit
  75 result.
  76
  77
  78 .. tabularcolumns:: |p{1.0cm}|p{3.5cm}|p{13.0cm}|
  79
  80 .. c:type:: cec_msg
  81
  82 .. cssclass:: longtable
  83
  84 .. flat-table:: struct cec_msg
  85     :header-rows:  0
  86     :stub-columns: 0
  87     :widths:       1 1 16
  88
  89     * - __u64
  90       - ``tx_ts``
  91       - Timestamp in ns of when the last byte of the message was transmitted.
  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     * - __u64
  95       - ``rx_ts``
  96       - Timestamp in ns of when the last byte of the message was received.
  97         The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
  98         the same clock from userspace use :c:func:`clock_gettime`.
  99     * - __u32
 100       - ``len``
 101       - The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
 102         by the application. The driver will fill this in for
 103         :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be
 104         filled in by the driver with the length of the reply message if ``reply`` was set.
 105     * - __u32
 106       - ``timeout``
 107       - The timeout in milliseconds. This is the time the device will wait
 108         for a message to be received before timing out. If it is set to 0,
 109         then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 110         If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
 111         then it will be replaced by 1000 if the ``reply`` is non-zero or
 112         ignored if ``reply`` is 0.
 113     * - __u32
 114       - ``sequence``
 115       - A non-zero sequence number is automatically assigned by the CEC framework
 116         for all transmitted messages. It is used by the CEC framework when it queues
 117         the transmit result (when transmit was called in non-blocking mode). This
 118         allows the application to associate the received message with the original
 119         transmit.
 120     * - __u32
 121       - ``flags``
 122       - Flags. See :ref:`cec-msg-flags` for a list of available flags.
 123     * - __u8
 124       - ``tx_status``
 125       - The status bits of the transmitted message. See
 126         :ref:`cec-tx-status` for the possible status values. It is 0 if
 127         this messages was received, not transmitted.
 128     * - __u8
 129       - ``msg[16]``
 130       - The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
 131         application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 132         For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
 133         the payload of the reply message if ``timeout`` was set.
 134     * - __u8
 135       - ``reply``
 136       - Wait until this message is replied. If ``reply`` is 0 and the
 137         ``timeout`` is 0, then don't wait for a reply but return after
 138         transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 139         The case where ``reply`` is 0 (this is the opcode for the Feature Abort
 140         message) and ``timeout`` is non-zero is specifically allowed to make it
 141         possible to send a message and wait up to ``timeout`` milliseconds for a
 142         Feature Abort reply. In this case ``rx_status`` will either be set
 143         to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
 144         :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
 145
 146         If the transmitter message is ``CEC_MSG_INITIATE_ARC`` then the ``reply``
 147         values ``CEC_MSG_REPORT_ARC_INITIATED`` and ``CEC_MSG_REPORT_ARC_TERMINATED``
 148         are processed differently: either value will match both possible replies.
 149         The reason is that the ``CEC_MSG_INITIATE_ARC`` message is the only CEC
 150         message that has two possible replies other than Feature Abort. The
 151         ``reply`` field will be updated with the actual reply so that it is
 152         synchronized with the contents of the received message.
 153     * - __u8
 154       - ``rx_status``
 155       - The status bits of the received message. See
 156         :ref:`cec-rx-status` for the possible status values. It is 0 if
 157         this message was transmitted, not received, unless this is the
 158         reply to a transmitted message. In that case both ``rx_status``
 159         and ``tx_status`` are set.
 160     * - __u8
 161       - ``tx_status``
 162       - The status bits of the transmitted message. See
 163         :ref:`cec-tx-status` for the possible status values. It is 0 if
 164         this messages was received, not transmitted.
 165     * - __u8
 166       - ``tx_arb_lost_cnt``
 167       - A counter of the number of transmit attempts that resulted in the
 168         Arbitration Lost error. This is only set if the hardware supports
 169         this, otherwise it is always 0. This counter is only valid if the
 170         :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
 171     * - __u8
 172       - ``tx_nack_cnt``
 173       - A counter of the number of transmit attempts that resulted in the
 174         Not Acknowledged error. This is only set if the hardware supports
 175         this, otherwise it is always 0. This counter is only valid if the
 176         :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
 177     * - __u8
 178       - ``tx_low_drive_cnt``
 179       - A counter of the number of transmit attempts that resulted in the
 180         Arbitration Lost error. This is only set if the hardware supports
 181         this, otherwise it is always 0. This counter is only valid if the
 182         :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
 183     * - __u8
 184       - ``tx_error_cnt``
 185       - A counter of the number of transmit errors other than Arbitration
 186         Lost or Not Acknowledged. This is only set if the hardware
 187         supports this, otherwise it is always 0. This counter is only
 188         valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
 189
 190
 191 .. _cec-msg-flags:
 192
 193 .. flat-table:: Flags for struct cec_msg
 194     :header-rows:  0
 195     :stub-columns: 0
 196     :widths:       3 1 4
 197
 198     * .. _`CEC-MSG-FL-REPLY-TO-FOLLOWERS`:
 199
 200       - ``CEC_MSG_FL_REPLY_TO_FOLLOWERS``
 201       - 1
 202       - If a CEC transmit expects a reply, then by default that reply is only sent to
 203         the filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If this
 204         flag is set, then the reply is also sent to all followers, if any. If the
 205         filehandle that called :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is also a
 206         follower, then that filehandle will receive the reply twice: once as the
 207         result of the :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`, and once via
 208         :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 209
 210
 211 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 212
 213 .. _cec-tx-status:
 214
 215 .. flat-table:: CEC Transmit Status
 216     :header-rows:  0
 217     :stub-columns: 0
 218     :widths:       3 1 16
 219
 220     * .. _`CEC-TX-STATUS-OK`:
 221
 222       - ``CEC_TX_STATUS_OK``
 223       - 0x01
 224       - The message was transmitted successfully. This is mutually
 225         exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still
 226         be set if earlier attempts met with failure before the transmit
 227         was eventually successful.
 228     * .. _`CEC-TX-STATUS-ARB-LOST`:
 229
 230       - ``CEC_TX_STATUS_ARB_LOST``
 231       - 0x02
 232       - CEC line arbitration was lost.
 233     * .. _`CEC-TX-STATUS-NACK`:
 234
 235       - ``CEC_TX_STATUS_NACK``
 236       - 0x04
 237       - Message was not acknowledged.
 238     * .. _`CEC-TX-STATUS-LOW-DRIVE`:
 239
 240       - ``CEC_TX_STATUS_LOW_DRIVE``
 241       - 0x08
 242       - Low drive was detected on the CEC bus. This indicates that a
 243         follower detected an error on the bus and requests a
 244         retransmission.
 245     * .. _`CEC-TX-STATUS-ERROR`:
 246
 247       - ``CEC_TX_STATUS_ERROR``
 248       - 0x10
 249       - Some error occurred. This is used for any errors that do not fit
 250         the previous two, either because the hardware could not tell which
 251         error occurred, or because the hardware tested for other
 252         conditions besides those two.
 253     * .. _`CEC-TX-STATUS-MAX-RETRIES`:
 254
 255       - ``CEC_TX_STATUS_MAX_RETRIES``
 256       - 0x20
 257       - The transmit failed after one or more retries. This status bit is
 258         mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still
 259         be set to explain which failures were seen.
 260
 261
 262 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 263
 264 .. _cec-rx-status:
 265
 266 .. flat-table:: CEC Receive Status
 267     :header-rows:  0
 268     :stub-columns: 0
 269     :widths:       3 1 16
 270
 271     * .. _`CEC-RX-STATUS-OK`:
 272
 273       - ``CEC_RX_STATUS_OK``
 274       - 0x01
 275       - The message was received successfully.
 276     * .. _`CEC-RX-STATUS-TIMEOUT`:
 277
 278       - ``CEC_RX_STATUS_TIMEOUT``
 279       - 0x02
 280       - The reply to an earlier transmitted message timed out.
 281     * .. _`CEC-RX-STATUS-FEATURE-ABORT`:
 282
 283       - ``CEC_RX_STATUS_FEATURE_ABORT``
 284       - 0x04
 285       - The message was received successfully but the reply was
 286         ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
 287         was the reply to an earlier transmitted message.
 288
 289
 290
 291 Return Value
 292 ============
 293
 294 On success 0 is returned, on error -1 and the ``errno`` variable is set
 295 appropriately. The generic error codes are described at the
 296 :ref:`Generic Error Codes <gen-errors>` chapter.