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