Documentation/media/uapi/cec/cec-ioc-g-mode.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _CEC_MODE:
   4 .. _CEC_G_MODE:
   5 .. _CEC_S_MODE:
   6
   7 ********************************
   8 ioctls CEC_G_MODE and CEC_S_MODE
   9 ********************************
  10
  11 CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
  12
  13 Synopsis
  14 ========
  15
  16 .. cpp:function:: int ioctl( int fd, int request, __u32 *argp )
  17
  18 Arguments
  19 =========
  20
  21 ``fd``
  22     File descriptor returned by :ref:`open() <cec-func-open>`.
  23
  24 ``request``
  25     CEC_G_MODE, CEC_S_MODE
  26
  27 ``argp``
  28
  29
  30 Description
  31 ===========
  32
  33 .. note:: This documents the proposed CEC API. This API is not yet finalized
  34    and is currently only available as a staging kernel module.
  35
  36 By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
  37 applications from stepping on each others toes it must be possible to
  38 obtain exclusive access to the CEC adapter. This ioctl sets the
  39 filehandle to initiator and/or follower mode which can be exclusive
  40 depending on the chosen mode. The initiator is the filehandle that is
  41 used to initiate messages, i.e. it commands other CEC devices. The
  42 follower is the filehandle that receives messages sent to the CEC
  43 adapter and processes them. The same filehandle can be both initiator
  44 and follower, or this role can be taken by two different filehandles.
  45
  46 When a CEC message is received, then the CEC framework will decide how
  47 it will be processed. If the message is a reply to an earlier
  48 transmitted message, then the reply is sent back to the filehandle that
  49 is waiting for it. In addition the CEC framework will process it.
  50
  51 If the message is not a reply, then the CEC framework will process it
  52 first. If there is no follower, then the message is just discarded and a
  53 feature abort is sent back to the initiator if the framework couldn't
  54 process it. If there is a follower, then the message is passed on to the
  55 follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
  56 the new message. The framework expects the follower to make the right
  57 decisions.
  58
  59 The CEC framework will process core messages unless requested otherwise
  60 by the follower. The follower can enable the passthrough mode. In that
  61 case, the CEC framework will pass on most core messages without
  62 processing them and the follower will have to implement those messages.
  63 There are some messages that the core will always process, regardless of
  64 the passthrough mode. See :ref:`cec-core-processing` for details.
  65
  66 If there is no initiator, then any CEC filehandle can use
  67 :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
  68 initiator then only that initiator can call
  69 :ref:`CEC_TRANSMIT`. The follower can of course
  70 always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
  71
  72 Available initiator modes are:
  73
  74
  75 .. _cec-mode-initiator_e:
  76
  77 .. flat-table:: Initiator Modes
  78     :header-rows:  0
  79     :stub-columns: 0
  80     :widths:       3 1 16
  81
  82
  83     -  .. _`CEC-MODE-NO-INITIATOR`:
  84
  85        -  ``CEC_MODE_NO_INITIATOR``
  86
  87        -  0x0
  88
  89        -  This is not an initiator, i.e. it cannot transmit CEC messages or
  90           make any other changes to the CEC adapter.
  91
  92     -  .. _`CEC-MODE-INITIATOR`:
  93
  94        -  ``CEC_MODE_INITIATOR``
  95
  96        -  0x1
  97
  98        -  This is an initiator (the default when the device is opened) and
  99           it can transmit CEC messages and make changes to the CEC adapter,
 100           unless there is an exclusive initiator.
 101
 102     -  .. _`CEC-MODE-EXCL-INITIATOR`:
 103
 104        -  ``CEC_MODE_EXCL_INITIATOR``
 105
 106        -  0x2
 107
 108        -  This is an exclusive initiator and this file descriptor is the
 109           only one that can transmit CEC messages and make changes to the
 110           CEC adapter. If someone else is already the exclusive initiator
 111           then an attempt to become one will return the ``EBUSY`` error code
 112           error.
 113
 114
 115 Available follower modes are:
 116
 117
 118 .. _cec-mode-follower_e:
 119
 120 .. flat-table:: Follower Modes
 121     :header-rows:  0
 122     :stub-columns: 0
 123     :widths:       3 1 16
 124
 125
 126     -  .. _`CEC-MODE-NO-FOLLOWER`:
 127
 128        -  ``CEC_MODE_NO_FOLLOWER``
 129
 130        -  0x00
 131
 132        -  This is not a follower (the default when the device is opened).
 133
 134     -  .. _`CEC-MODE-FOLLOWER`:
 135
 136        -  ``CEC_MODE_FOLLOWER``
 137
 138        -  0x10
 139
 140        -  This is a follower and it will receive CEC messages unless there
 141           is an exclusive follower. You cannot become a follower if
 142           :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
 143           was specified, the ``EINVAL`` error code is returned in that case.
 144
 145     -  .. _`CEC-MODE-EXCL-FOLLOWER`:
 146
 147        -  ``CEC_MODE_EXCL_FOLLOWER``
 148
 149        -  0x20
 150
 151        -  This is an exclusive follower and only this file descriptor will
 152           receive CEC messages for processing. If someone else is already
 153           the exclusive follower then an attempt to become one will return
 154           the ``EBUSY`` error code. You cannot become a follower if
 155           :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
 156           was specified, the ``EINVAL`` error code is returned in that case.
 157
 158     -  .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
 159
 160        -  ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
 161
 162        -  0x30
 163
 164        -  This is an exclusive follower and only this file descriptor will
 165           receive CEC messages for processing. In addition it will put the
 166           CEC device into passthrough mode, allowing the exclusive follower
 167           to handle most core messages instead of relying on the CEC
 168           framework for that. If someone else is already the exclusive
 169           follower then an attempt to become one will return the ``EBUSY`` error
 170           code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
 171           is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
 172           the ``EINVAL`` error code is returned in that case.
 173
 174     -  .. _`CEC-MODE-MONITOR`:
 175
 176        -  ``CEC_MODE_MONITOR``
 177
 178        -  0xe0
 179
 180        -  Put the file descriptor into monitor mode. Can only be used in
 181           combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise EINVAL error
 182           code will be returned. In monitor mode all messages this CEC
 183           device transmits and all messages it receives (both broadcast
 184           messages and directed messages for one its logical addresses) will
 185           be reported. This is very useful for debugging. This is only
 186           allowed if the process has the ``CAP_NET_ADMIN`` capability. If
 187           that is not set, then the ``EPERM`` error code is returned.
 188
 189     -  .. _`CEC-MODE-MONITOR-ALL`:
 190
 191        -  ``CEC_MODE_MONITOR_ALL``
 192
 193        -  0xf0
 194
 195        -  Put the file descriptor into 'monitor all' mode. Can only be used
 196           in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
 197           the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
 198           this CEC device transmits and all messages it receives, including
 199           directed messages for other CEC devices will be reported. This is
 200           very useful for debugging, but not all devices support this. This
 201           mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
 202           otherwise the ``EINVAL`` error code is returned. This is only allowed if
 203           the process has the ``CAP_NET_ADMIN`` capability. If that is not
 204           set, then the ``EPERM`` error code is returned.
 205
 206
 207 Core message processing details:
 208
 209
 210 .. _cec-core-processing:
 211
 212 .. flat-table:: Core Message Processing
 213     :header-rows:  0
 214     :stub-columns: 0
 215     :widths: 1 8
 216
 217
 218     -  .. _`CEC-MSG-GET-CEC-VERSION`:
 219
 220        -  ``CEC_MSG_GET_CEC_VERSION``
 221
 222        -  When in passthrough mode this message has to be handled by
 223           userspace, otherwise the core will return the CEC version that was
 224           set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
 225
 226     -  .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
 227
 228        -  ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
 229
 230        -  When in passthrough mode this message has to be handled by
 231           userspace, otherwise the core will return the vendor ID that was
 232           set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
 233
 234     -  .. _`CEC-MSG-ABORT`:
 235
 236        -  ``CEC_MSG_ABORT``
 237
 238        -  When in passthrough mode this message has to be handled by
 239           userspace, otherwise the core will return a feature refused
 240           message as per the specification.
 241
 242     -  .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
 243
 244        -  ``CEC_MSG_GIVE_PHYSICAL_ADDR``
 245
 246        -  When in passthrough mode this message has to be handled by
 247           userspace, otherwise the core will report the current physical
 248           address.
 249
 250     -  .. _`CEC-MSG-GIVE-OSD-NAME`:
 251
 252        -  ``CEC_MSG_GIVE_OSD_NAME``
 253
 254        -  When in passthrough mode this message has to be handled by
 255           userspace, otherwise the core will report the current OSD name as
 256           was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
 257
 258     -  .. _`CEC-MSG-GIVE-FEATURES`:
 259
 260        -  ``CEC_MSG_GIVE_FEATURES``
 261
 262        -  When in passthrough mode this message has to be handled by
 263           userspace, otherwise the core will report the current features as
 264           was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
 265           or the message is ignored if the CEC version was older than 2.0.
 266
 267     -  .. _`CEC-MSG-USER-CONTROL-PRESSED`:
 268
 269        -  ``CEC_MSG_USER_CONTROL_PRESSED``
 270
 271        -  If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
 272           press. This message is always passed on to userspace.
 273
 274     -  .. _`CEC-MSG-USER-CONTROL-RELEASED`:
 275
 276        -  ``CEC_MSG_USER_CONTROL_RELEASED``
 277
 278        -  If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
 279           release. This message is always passed on to userspace.
 280
 281     -  .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
 282
 283        -  ``CEC_MSG_REPORT_PHYSICAL_ADDR``
 284
 285        -  The CEC framework will make note of the reported physical address
 286           and then just pass the message on to userspace.
 287
 288
 289
 290 Return Value
 291 ============
 292
 293 On success 0 is returned, on error -1 and the ``errno`` variable is set
 294 appropriately. The generic error codes are described at the
 295 :ref:`Generic Error Codes <gen-errors>` chapter.