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