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