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

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