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