Documentation/userspace-api/media/cec/cec-ioc-g-mode.rst

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