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