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 .. _cec-msg:
  77
  78 .. tabularcolumns:: |p{1.0cm}|p{1.0cm}|p{15.5cm}|
  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
 255 .. _cec-tx-status:
 256
 257 .. tabularcolumns:: |p{2.6cm}|p{0.9cm}|p{14.0cm}|
 258
 259 .. flat-table:: CEC Transmit Status
 260     :header-rows:  0
 261     :stub-columns: 0
 262     :widths:       3 1 16
 263
 264
 265     -  .. _`CEC-TX-STATUS-OK`:
 266
 267        -  ``CEC_TX_STATUS_OK``
 268
 269        -  0x01
 270
 271        -  The message was transmitted successfully. This is mutually
 272           exclusive with :ref:`CEC_TX_STATUS_MAX_RETRIES <CEC-TX-STATUS-MAX-RETRIES>`. Other bits can still
 273           be set if earlier attempts met with failure before the transmit
 274           was eventually successful.
 275
 276     -  .. _`CEC-TX-STATUS-ARB-LOST`:
 277
 278        -  ``CEC_TX_STATUS_ARB_LOST``
 279
 280        -  0x02
 281
 282        -  CEC line arbitration was lost.
 283
 284     -  .. _`CEC-TX-STATUS-NACK`:
 285
 286        -  ``CEC_TX_STATUS_NACK``
 287
 288        -  0x04
 289
 290        -  Message was not acknowledged.
 291
 292     -  .. _`CEC-TX-STATUS-LOW-DRIVE`:
 293
 294        -  ``CEC_TX_STATUS_LOW_DRIVE``
 295
 296        -  0x08
 297
 298        -  Low drive was detected on the CEC bus. This indicates that a
 299           follower detected an error on the bus and requests a
 300           retransmission.
 301
 302     -  .. _`CEC-TX-STATUS-ERROR`:
 303
 304        -  ``CEC_TX_STATUS_ERROR``
 305
 306        -  0x10
 307
 308        -  Some error occurred. This is used for any errors that do not fit
 309           the previous two, either because the hardware could not tell which
 310           error occurred, or because the hardware tested for other
 311           conditions besides those two.
 312
 313     -  .. _`CEC-TX-STATUS-MAX-RETRIES`:
 314
 315        -  ``CEC_TX_STATUS_MAX_RETRIES``
 316
 317        -  0x20
 318
 319        -  The transmit failed after one or more retries. This status bit is
 320           mutually exclusive with :ref:`CEC_TX_STATUS_OK <CEC-TX-STATUS-OK>`. Other bits can still
 321           be set to explain which failures were seen.
 322
 323
 324
 325 .. _cec-rx-status:
 326
 327 .. tabularcolumns:: |p{2.6cm}|p{0.9cm}|p{14.0cm}|
 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.