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
  90     -  .. row 1
  91
  92        -  __u64
  93
  94        -  ``tx_ts``
  95
  96        -  Timestamp in ns of when the last byte of the message was transmitted.
  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
 100     -  .. row 2
 101
 102        -  __u64
 103
 104        -  ``rx_ts``
 105
 106        -  Timestamp in ns of when the last byte of the message was received.
 107           The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock. To access
 108           the same clock from userspace use :c:func:`clock_gettime`.
 109
 110     -  .. row 3
 111
 112        -  __u32
 113
 114        -  ``len``
 115
 116        -  The length of the message. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in
 117           by the application. The driver will fill this in for
 118           :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be
 119           filled in by the driver with the length of the reply message if ``reply`` was set.
 120
 121     -  .. row 4
 122
 123        -  __u32
 124
 125        -  ``timeout``
 126
 127        -  The timeout in milliseconds. This is the time the device will wait
 128           for a message to be received before timing out. If it is set to 0,
 129           then it will wait indefinitely when it is called by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 130           If it is 0 and it is called by :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`,
 131           then it will be replaced by 1000 if the ``reply`` is non-zero or
 132           ignored if ``reply`` is 0.
 133
 134     -  .. row 5
 135
 136        -  __u32
 137
 138        -  ``sequence``
 139
 140        -  A non-zero sequence number is automatically assigned by the CEC framework
 141           for all transmitted messages. It is used by the CEC framework when it queues
 142           the transmit result (when transmit was called in non-blocking mode). This
 143           allows the application to associate the received message with the original
 144           transmit.
 145
 146     -  .. row 6
 147
 148        -  __u32
 149
 150        -  ``flags``
 151
 152        -  Flags. No flags are defined yet, so set this to 0.
 153
 154     -  .. row 7
 155
 156        -  __u8
 157
 158        -  ``tx_status``
 159
 160        -  The status bits of the transmitted message. See
 161           :ref:`cec-tx-status` for the possible status values. It is 0 if
 162           this messages was received, not transmitted.
 163
 164     -  .. row 8
 165
 166        -  __u8
 167
 168        -  ``msg[16]``
 169
 170        -  The message payload. For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` this is filled in by the
 171           application. The driver will fill this in for :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 172           For :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>` it will be filled in by the driver with
 173           the payload of the reply message if ``timeout`` was set.
 174
 175     -  .. row 8
 176
 177        -  __u8
 178
 179        -  ``reply``
 180
 181        -  Wait until this message is replied. If ``reply`` is 0 and the
 182           ``timeout`` is 0, then don't wait for a reply but return after
 183           transmitting the message. Ignored by :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>`.
 184           The case where ``reply`` is 0 (this is the opcode for the Feature Abort
 185           message) and ``timeout`` is non-zero is specifically allowed to make it
 186           possible to send a message and wait up to ``timeout`` milliseconds for a
 187           Feature Abort reply. In this case ``rx_status`` will either be set
 188           to :ref:`CEC_RX_STATUS_TIMEOUT <CEC-RX-STATUS-TIMEOUT>` or
 189           :ref:`CEC_RX_STATUS_FEATURE_ABORT <CEC-RX-STATUS-FEATURE-ABORT>`.
 190
 191     -  .. row 9
 192
 193        -  __u8
 194
 195        -  ``rx_status``
 196
 197        -  The status bits of the received message. See
 198           :ref:`cec-rx-status` for the possible status values. It is 0 if
 199           this message was transmitted, not received, unless this is the
 200           reply to a transmitted message. In that case both ``rx_status``
 201           and ``tx_status`` are set.
 202
 203     -  .. row 10
 204
 205        -  __u8
 206
 207        -  ``tx_status``
 208
 209        -  The status bits of the transmitted message. See
 210           :ref:`cec-tx-status` for the possible status values. It is 0 if
 211           this messages was received, not transmitted.
 212
 213     -  .. row 11
 214
 215        -  __u8
 216
 217        -  ``tx_arb_lost_cnt``
 218
 219        -  A counter of the number of transmit attempts that resulted in the
 220           Arbitration Lost error. This is only set if the hardware supports
 221           this, otherwise it is always 0. This counter is only valid if the
 222           :ref:`CEC_TX_STATUS_ARB_LOST <CEC-TX-STATUS-ARB-LOST>` status bit is set.
 223
 224     -  .. row 12
 225
 226        -  __u8
 227
 228        -  ``tx_nack_cnt``
 229
 230        -  A counter of the number of transmit attempts that resulted in the
 231           Not Acknowledged error. This is only set if the hardware supports
 232           this, otherwise it is always 0. This counter is only valid if the
 233           :ref:`CEC_TX_STATUS_NACK <CEC-TX-STATUS-NACK>` status bit is set.
 234
 235     -  .. row 13
 236
 237        -  __u8
 238
 239        -  ``tx_low_drive_cnt``
 240
 241        -  A counter of the number of transmit attempts that resulted in the
 242           Arbitration Lost error. This is only set if the hardware supports
 243           this, otherwise it is always 0. This counter is only valid if the
 244           :ref:`CEC_TX_STATUS_LOW_DRIVE <CEC-TX-STATUS-LOW-DRIVE>` status bit is set.
 245
 246     -  .. row 14
 247
 248        -  __u8
 249
 250        -  ``tx_error_cnt``
 251
 252        -  A counter of the number of transmit errors other than Arbitration
 253           Lost or Not Acknowledged. This is only set if the hardware
 254           supports this, otherwise it is always 0. This counter is only
 255           valid if the :ref:`CEC_TX_STATUS_ERROR <CEC-TX-STATUS-ERROR>` status bit is set.
 256
 257
 258 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 259
 260 .. _cec-tx-status:
 261
 262 .. flat-table:: CEC Transmit Status
 263     :header-rows:  0
 264     :stub-columns: 0
 265     :widths:       3 1 16
 266
 267
 268     -  .. _`CEC-TX-STATUS-OK`:
 269
 270        -  ``CEC_TX_STATUS_OK``
 271
 272        -  0x01
 273
 274        -  The message was transmitted successfully. This is mutually
 275           exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still
 276           be set if earlier attempts met with failure before the transmit
 277           was eventually successful.
 278
 279     -  .. _`CEC-TX-STATUS-ARB-LOST`:
 280
 281        -  ``CEC_TX_STATUS_ARB_LOST``
 282
 283        -  0x02
 284
 285        -  CEC line arbitration was lost.
 286
 287     -  .. _`CEC-TX-STATUS-NACK`:
 288
 289        -  ``CEC_TX_STATUS_NACK``
 290
 291        -  0x04
 292
 293        -  Message was not acknowledged.
 294
 295     -  .. _`CEC-TX-STATUS-LOW-DRIVE`:
 296
 297        -  ``CEC_TX_STATUS_LOW_DRIVE``
 298
 299        -  0x08
 300
 301        -  Low drive was detected on the CEC bus. This indicates that a
 302           follower detected an error on the bus and requests a
 303           retransmission.
 304
 305     -  .. _`CEC-TX-STATUS-ERROR`:
 306
 307        -  ``CEC_TX_STATUS_ERROR``
 308
 309        -  0x10
 310
 311        -  Some error occurred. This is used for any errors that do not fit
 312           the previous two, either because the hardware could not tell which
 313           error occurred, or because the hardware tested for other
 314           conditions besides those two.
 315
 316     -  .. _`CEC-TX-STATUS-MAX-RETRIES`:
 317
 318        -  ``CEC_TX_STATUS_MAX_RETRIES``
 319
 320        -  0x20
 321
 322        -  The transmit failed after one or more retries. This status bit is
 323           mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still
 324           be set to explain which failures were seen.
 325
 326
 327 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
 328
 329 .. _cec-rx-status:
 330
 331 .. flat-table:: CEC Receive Status
 332     :header-rows:  0
 333     :stub-columns: 0
 334     :widths:       3 1 16
 335
 336
 337     -  .. _`CEC-RX-STATUS-OK`:
 338
 339        -  ``CEC_RX_STATUS_OK``
 340
 341        -  0x01
 342
 343        -  The message was received successfully.
 344
 345     -  .. _`CEC-RX-STATUS-TIMEOUT`:
 346
 347        -  ``CEC_RX_STATUS_TIMEOUT``
 348
 349        -  0x02
 350
 351        -  The reply to an earlier transmitted message timed out.
 352
 353     -  .. _`CEC-RX-STATUS-FEATURE-ABORT`:
 354
 355        -  ``CEC_RX_STATUS_FEATURE_ABORT``
 356
 357        -  0x04
 358
 359        -  The message was received successfully but the reply was
 360           ``CEC_MSG_FEATURE_ABORT``. This status is only set if this message
 361           was the reply to an earlier transmitted message.
 362
 363
 364
 365 Return Value
 366 ============
 367
 368 On success 0 is returned, on error -1 and the ``errno`` variable is set
 369 appropriately. The generic error codes are described at the
 370 :ref:`Generic Error Codes <gen-errors>` chapter.