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