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