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 .. flat-table:: Follower Modes
 112     :header-rows:  0
 113     :stub-columns: 0
 114     :widths:       3 1 16
 115
 116     * .. _`CEC-MODE-NO-FOLLOWER`:
 117
 118       - ``CEC_MODE_NO_FOLLOWER``
 119       - 0x00
 120       - This is not a follower (the default when the device is opened).
 121     * .. _`CEC-MODE-FOLLOWER`:
 122
 123       - ``CEC_MODE_FOLLOWER``
 124       - 0x10
 125       - This is a follower and it will receive CEC messages unless there
 126         is an exclusive follower. You cannot become a follower if
 127         :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
 128         was specified, the ``EINVAL`` error code is returned in that case.
 129     * .. _`CEC-MODE-EXCL-FOLLOWER`:
 130
 131       - ``CEC_MODE_EXCL_FOLLOWER``
 132       - 0x20
 133       - This is an exclusive follower and only this file descriptor will
 134         receive CEC messages for processing. If someone else is already
 135         the exclusive follower then an attempt to become one will return
 136         the ``EBUSY`` error code. You cannot become a follower if
 137         :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
 138         was specified, the ``EINVAL`` error code is returned in that case.
 139     * .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
 140
 141       - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
 142       - 0x30
 143       - This is an exclusive follower and only this file descriptor will
 144         receive CEC messages for processing. In addition it will put the
 145         CEC device into passthrough mode, allowing the exclusive follower
 146         to handle most core messages instead of relying on the CEC
 147         framework for that. If someone else is already the exclusive
 148         follower then an attempt to become one will return the ``EBUSY`` error
 149         code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
 150         is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
 151         the ``EINVAL`` error code is returned in that case.
 152     * .. _`CEC-MODE-MONITOR-PIN`:
 153
 154       - ``CEC_MODE_MONITOR_PIN``
 155       - 0xd0
 156       - Put the file descriptor into pin monitoring mode. Can only be used in
 157         combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
 158         otherwise the ``EINVAL`` error code will be returned.
 159         This mode requires that the :ref:`CEC_CAP_MONITOR_PIN <CEC-CAP-MONITOR-PIN>`
 160         capability is set, otherwise the ``EINVAL`` error code is returned.
 161         While in pin monitoring mode this file descriptor can receive the
 162         ``CEC_EVENT_PIN_LOW`` and ``CEC_EVENT_PIN_HIGH`` events to see the
 163         low-level CEC pin transitions. This is very useful for debugging.
 164         This mode is only allowed if the process has the ``CAP_NET_ADMIN``
 165         capability. If that is not set, then the ``EPERM`` error code is returned.
 166     * .. _`CEC-MODE-MONITOR`:
 167
 168       - ``CEC_MODE_MONITOR``
 169       - 0xe0
 170       - Put the file descriptor into monitor mode. Can only be used in
 171         combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,i
 172         otherwise the ``EINVAL`` error code will be returned.
 173         In monitor mode all messages this CEC
 174         device transmits and all messages it receives (both broadcast
 175         messages and directed messages for one its logical addresses) will
 176         be reported. This is very useful for debugging. This is only
 177         allowed if the process has the ``CAP_NET_ADMIN`` capability. If
 178         that is not set, then the ``EPERM`` error code is returned.
 179     * .. _`CEC-MODE-MONITOR-ALL`:
 180
 181       - ``CEC_MODE_MONITOR_ALL``
 182       - 0xf0
 183       - Put the file descriptor into 'monitor all' mode. Can only be used
 184         in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
 185         the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
 186         this CEC device transmits and all messages it receives, including
 187         directed messages for other CEC devices will be reported. This is
 188         very useful for debugging, but not all devices support this. This
 189         mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
 190         otherwise the ``EINVAL`` error code is returned. This is only allowed if
 191         the process has the ``CAP_NET_ADMIN`` capability. If that is not
 192         set, then the ``EPERM`` error code is returned.
 193
 194
 195 Core message processing details:
 196
 197 .. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
 198
 199 .. _cec-core-processing:
 200
 201 .. flat-table:: Core Message Processing
 202     :header-rows:  0
 203     :stub-columns: 0
 204     :widths: 1 8
 205
 206     * .. _`CEC-MSG-GET-CEC-VERSION`:
 207
 208       - ``CEC_MSG_GET_CEC_VERSION``
 209       - When in passthrough mode this message has to be handled by
 210         userspace, otherwise the core will return the CEC version that was
 211         set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
 212     * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
 213
 214       - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
 215       - When in passthrough mode this message has to be handled by
 216         userspace, otherwise the core will return the vendor ID that was
 217         set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
 218     * .. _`CEC-MSG-ABORT`:
 219
 220       - ``CEC_MSG_ABORT``
 221       - When in passthrough mode this message has to be handled by
 222         userspace, otherwise the core will return a feature refused
 223         message as per the specification.
 224     * .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
 225
 226       - ``CEC_MSG_GIVE_PHYSICAL_ADDR``
 227       - When in passthrough mode this message has to be handled by
 228         userspace, otherwise the core will report the current physical
 229         address.
 230     * .. _`CEC-MSG-GIVE-OSD-NAME`:
 231
 232       - ``CEC_MSG_GIVE_OSD_NAME``
 233       - When in passthrough mode this message has to be handled by
 234         userspace, otherwise the core will report the current OSD name as
 235         was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
 236     * .. _`CEC-MSG-GIVE-FEATURES`:
 237
 238       - ``CEC_MSG_GIVE_FEATURES``
 239       - When in passthrough mode this message has to be handled by
 240         userspace, otherwise the core will report the current features as
 241         was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
 242         or the message is ignored if the CEC version was older than 2.0.
 243     * .. _`CEC-MSG-USER-CONTROL-PRESSED`:
 244
 245       - ``CEC_MSG_USER_CONTROL_PRESSED``
 246       - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
 247         press. This message is always passed on to userspace.
 248     * .. _`CEC-MSG-USER-CONTROL-RELEASED`:
 249
 250       - ``CEC_MSG_USER_CONTROL_RELEASED``
 251       - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
 252         release. This message is always passed on to userspace.
 253     * .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
 254
 255       - ``CEC_MSG_REPORT_PHYSICAL_ADDR``
 256       - The CEC framework will make note of the reported physical address
 257         and then just pass the message on to userspace.
 258
 259
 260
 261 Return Value
 262 ============
 263
 264 On success 0 is returned, on error -1 and the ``errno`` variable is set
 265 appropriately. The generic error codes are described at the
 266 :ref:`Generic Error Codes <gen-errors>` chapter.
 267
 268 The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following
 269 error codes:
 270
 271 EINVAL
 272     The requested mode is invalid.
 273
 274 EPERM
 275     Monitor mode is requested without having root permissions
 276
 277 EBUSY
 278     Someone else is already an exclusive follower or initiator.