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 .. cpp:function:: int ioctl( int fd, int request, struct cec_msg *argp )
  20
  21 Arguments
  22 =========
  23
  24 ``fd``
  25     File descriptor returned by :ref:`open() <cec-func-open>`.
  26
  27 ``request``
  28     CEC_RECEIVE, CEC_TRANSMIT
  29
  30 ``argp``
  31
  32
  33 Description
  34 ===========
  35
  36 .. note:: This documents the proposed CEC API. This API is not yet finalized
  37    and is currently only available as a staging kernel module.
  38
  39 To receive a CEC message the application has to fill in the
  40 ``timeout`` field of :c:type:`struct cec_msg` and pass it to :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
  41 If the file descriptor is in non-blocking mode and there are no received
  42 messages pending, then it will return -1 and set errno to the ``EAGAIN``
  43 error code. If the file descriptor is in blocking mode and ``timeout``
  44 is non-zero and no message arrived within ``timeout`` milliseconds, then
  45 it will return -1 and set errno to the ``ETIMEDOUT`` error code.
  46
  47 A received message can be:
  48
  49 1. a message received from another CEC device (the ``sequence`` field will
  50    be 0).
  51 2. the result of an earlier non-blocking transmit (the ``sequence`` field will
  52    be non-zero).
  53
  54 To send a CEC message the application has to fill in the
  55 :c:type:`struct cec_msg` and pass it to
  56 :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. The :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` is only available if
  57 ``CEC_CAP_TRANSMIT`` is set. If there is no more room in the transmit
  58 queue, then it will return -1 and set errno to the ``EBUSY`` error code.
  59 The transmit queue has enough room for 18 messages (about 1 second worth
  60 of 2-byte messages). Note that the CEC kernel framework will also reply
  61 to core messages (see :ref:cec-core-processing), so it is not a good
  62 idea to fully fill up the transmit queue.
  63
  64 If the file descriptor is in non-blocking mode then the transmit will
  65 return 0 and the result of the transmit will be available via
  66 :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` once the transmit has finished
  67 (including waiting for a reply, if requested).
  68
  69 The ``sequence`` field is filled in for every transmit and this can be
  70 checked against the received messages to find the corresponding transmit
  71 result.
  72
  73
  74 .. _cec-msg:
  75
  76 .. flat-table:: struct cec_msg
  77     :header-rows:  0
  78     :stub-columns: 0
  79     :widths:       1 1 16
  80
  81
  82     -  .. row 1
  83
  84        -  __u64
  85
  86        -  ``tx_ts``
  87
  88        -  Timestamp in ns of when the last byte of the message was transmitted.
  89           The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
  90           the same clock from userspace use :c:func:`clock_gettime(2)`.
  91
  92     -  .. row 2
  93
  94        -  __u64
  95
  96        -  ``rx_ts``
  97
  98        -  Timestamp in ns of when the last byte of the message was received.
  99           The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
 100           the same clock from userspace use :c:func:`clock_gettime(2)`.
 101
 102     -  .. row 3
 103
 104        -  __u32
 105
 106        -  ``len``
 107
 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
 113     -  .. row 4
 114
 115        -  __u32
 116
 117        -  ``timeout``
 118
 119        -  The timeout in milliseconds. This is the time the device will wait
 120           for a message to be received before timing out. If it is set to 0,
 121           then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 122           If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
 123           then it will be replaced by 1000 if the ``reply`` is non-zero or
 124           ignored if ``reply`` is 0.
 125
 126     -  .. row 5
 127
 128        -  __u32
 129
 130        -  ``sequence``
 131
 132        -  A non-zero sequence number is automatically assigned by the CEC framework
 133           for all transmitted messages. It is used by the CEC framework when it queues
 134           the transmit result (when transmit was called in non-blocking mode). This
 135           allows the application to associate the received message with the original
 136           transmit.
 137
 138     -  .. row 6
 139
 140        -  __u32
 141
 142        -  ``flags``
 143
 144        -  Flags. No flags are defined yet, so set this to 0.
 145
 146     -  .. row 7
 147
 148        -  __u8
 149
 150        -  ``tx_status``
 151
 152        -  The status bits of the transmitted message. See
 153           :ref:`cec-tx-status` for the possible status values. It is 0 if
 154           this messages was received, not transmitted.
 155
 156     -  .. row 8
 157
 158        -  __u8
 159
 160        -  ``msg[16]``
 161
 162        -  The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
 163           application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 164           For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
 165           the payload of the reply message if ``timeout`` was set.
 166
 167     -  .. row 8
 168
 169        -  __u8
 170
 171        -  ``reply``
 172
 173        -  Wait until this message is replied. If ``reply`` is 0 and the
 174           ``timeout`` is 0, then don't wait for a reply but return after
 175           transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 176           The case where ``reply`` is 0 (this is the opcode for the Feature Abort
 177           message) and ``timeout`` is non-zero is specifically allowed to make it
 178           possible to send a message and wait up to ``timeout`` milliseconds for a
 179           Feature Abort reply. In this case ``rx_status`` will either be set
 180           to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
 181           :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
 182
 183     -  .. row 9
 184
 185        -  __u8
 186
 187        -  ``rx_status``
 188
 189        -  The status bits of the received message. See
 190           :ref:`cec-rx-status` for the possible status values. It is 0 if
 191           this message was transmitted, not received, unless this is the
 192           reply to a transmitted message. In that case both ``rx_status``
 193           and ``tx_status`` are set.
 194
 195     -  .. row 10
 196
 197        -  __u8
 198
 199        -  ``tx_status``
 200
 201        -  The status bits of the transmitted message. See
 202           :ref:`cec-tx-status` for the possible status values. It is 0 if
 203           this messages was received, not transmitted.
 204
 205     -  .. row 11
 206
 207        -  __u8
 208
 209        -  ``tx_arb_lost_cnt``
 210
 211        -  A counter of the number of transmit attempts that resulted in the
 212           Arbitration Lost error. This is only set if the hardware supports
 213           this, otherwise it is always 0. This counter is only valid if the
 214           :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
 215
 216     -  .. row 12
 217
 218        -  __u8
 219
 220        -  ``tx_nack_cnt``
 221
 222        -  A counter of the number of transmit attempts that resulted in the
 223           Not Acknowledged error. This is only set if the hardware supports
 224           this, otherwise it is always 0. This counter is only valid if the
 225           :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
 226
 227     -  .. row 13
 228
 229        -  __u8
 230
 231        -  ``tx_low_drive_cnt``
 232
 233        -  A counter of the number of transmit attempts that resulted in the
 234           Arbitration Lost error. This is only set if the hardware supports
 235           this, otherwise it is always 0. This counter is only valid if the
 236           :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
 237
 238     -  .. row 14
 239
 240        -  __u8
 241
 242        -  ``tx_error_cnt``
 243
 244        -  A counter of the number of transmit errors other than Arbitration
 245           Lost or Not Acknowledged. This is only set if the hardware
 246           supports this, otherwise it is always 0. This counter is only
 247           valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
 248
 249
 250
 251 .. _cec-tx-status:
 252
 253 .. flat-table:: CEC Transmit Status
 254     :header-rows:  0
 255     :stub-columns: 0
 256     :widths:       3 1 16
 257
 258
 259     -  .. _`CEC-TX-STATUS-OK`:
 260
 261        -  ``CEC_TX_STATUS_OK``
 262
 263        -  0x01
 264
 265        -  The message was transmitted successfully. This is mutually
 266           exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still
 267           be set if earlier attempts met with failure before the transmit
 268           was eventually successful.
 269
 270     -  .. _`CEC-TX-STATUS-ARB-LOST`:
 271
 272        -  ``CEC_TX_STATUS_ARB_LOST``
 273
 274        -  0x02
 275
 276        -  CEC line arbitration was lost.
 277
 278     -  .. _`CEC-TX-STATUS-NACK`:
 279
 280        -  ``CEC_TX_STATUS_NACK``
 281
 282        -  0x04
 283
 284        -  Message was not acknowledged.
 285
 286     -  .. _`CEC-TX-STATUS-LOW-DRIVE`:
 287
 288        -  ``CEC_TX_STATUS_LOW_DRIVE``
 289
 290        -  0x08
 291
 292        -  Low drive was detected on the CEC bus. This indicates that a
 293           follower detected an error on the bus and requests a
 294           retransmission.
 295
 296     -  .. _`CEC-TX-STATUS-ERROR`:
 297
 298        -  ``CEC_TX_STATUS_ERROR``
 299
 300        -  0x10
 301
 302        -  Some error occurred. This is used for any errors that do not fit
 303           the previous two, either because the hardware could not tell which
 304           error occurred, or because the hardware tested for other
 305           conditions besides those two.
 306
 307     -  .. _`CEC-TX-STATUS-MAX-RETRIES`:
 308
 309        -  ``CEC_TX_STATUS_MAX_RETRIES``
 310
 311        -  0x20
 312
 313        -  The transmit failed after one or more retries. This status bit is
 314           mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still
 315           be set to explain which failures were seen.
 316
 317
 318
 319 .. _cec-rx-status:
 320
 321 .. flat-table:: CEC Receive Status
 322     :header-rows:  0
 323     :stub-columns: 0
 324     :widths:       3 1 16
 325
 326
 327     -  .. _`CEC-RX-STATUS-OK`:
 328
 329        -  ``CEC_RX_STATUS_OK``
 330
 331        -  0x01
 332
 333        -  The message was received successfully.
 334
 335     -  .. _`CEC-RX-STATUS-TIMEOUT`:
 336
 337        -  ``CEC_RX_STATUS_TIMEOUT``
 338
 339        -  0x02
 340
 341        -  The reply to an earlier transmitted message timed out.
 342
 343     -  .. _`CEC-RX-STATUS-FEATURE-ABORT`:
 344
 345        -  ``CEC_RX_STATUS_FEATURE_ABORT``
 346
 347        -  0x04
 348
 349        -  The message was received successfully but the reply was
 350           ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
 351           was the reply to an earlier transmitted message.
 352
 353
 354
 355 Return Value
 356 ============
 357
 358 On success 0 is returned, on error -1 and the ``errno`` variable is set
 359 appropriately. The generic error codes are described at the
 360 :ref:`Generic Error Codes <gen-errors>` chapter.