Documentation/media/uapi/cec/cec-ioc-receive.rst

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