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