0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: CEC
0003
0004 .. _CEC_MODE:
0005 .. _CEC_G_MODE:
0006 .. _CEC_S_MODE:
0007
0008 ********************************
0009 ioctls CEC_G_MODE and CEC_S_MODE
0010 ********************************
0011
0012 CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
0013
0014 Synopsis
0015 ========
0016
0017 .. c:macro:: CEC_G_MODE
0018
0019 ``int ioctl(int fd, CEC_G_MODE, __u32 *argp)``
0020
0021 .. c:macro:: CEC_S_MODE
0022
0023 ``int ioctl(int fd, CEC_S_MODE, __u32 *argp)``
0024
0025 Arguments
0026 =========
0027
0028 ``fd``
0029 File descriptor returned by :c:func:`open()`.
0030
0031 ``argp``
0032 Pointer to CEC mode.
0033
0034 Description
0035 ===========
0036
0037 By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
0038 applications from stepping on each others toes it must be possible to
0039 obtain exclusive access to the CEC adapter. This ioctl sets the
0040 filehandle to initiator and/or follower mode which can be exclusive
0041 depending on the chosen mode. The initiator is the filehandle that is
0042 used to initiate messages, i.e. it commands other CEC devices. The
0043 follower is the filehandle that receives messages sent to the CEC
0044 adapter and processes them. The same filehandle can be both initiator
0045 and follower, or this role can be taken by two different filehandles.
0046
0047 When a CEC message is received, then the CEC framework will decide how
0048 it will be processed. If the message is a reply to an earlier
0049 transmitted message, then the reply is sent back to the filehandle that
0050 is waiting for it. In addition the CEC framework will process it.
0051
0052 If the message is not a reply, then the CEC framework will process it
0053 first. If there is no follower, then the message is just discarded and a
0054 feature abort is sent back to the initiator if the framework couldn't
0055 process it. If there is a follower, then the message is passed on to the
0056 follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
0057 the new message. The framework expects the follower to make the right
0058 decisions.
0059
0060 The CEC framework will process core messages unless requested otherwise
0061 by the follower. The follower can enable the passthrough mode. In that
0062 case, the CEC framework will pass on most core messages without
0063 processing them and the follower will have to implement those messages.
0064 There are some messages that the core will always process, regardless of
0065 the passthrough mode. See :ref:`cec-core-processing` for details.
0066
0067 If there is no initiator, then any CEC filehandle can use
0068 :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
0069 initiator then only that initiator can call
0070 :ref:`CEC_TRANSMIT`. The follower can of course
0071 always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
0072
0073 Available initiator modes are:
0074
0075 .. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}|
0076
0077 .. _cec-mode-initiator_e:
0078
0079 .. flat-table:: Initiator Modes
0080 :header-rows: 0
0081 :stub-columns: 0
0082 :widths: 3 1 16
0083
0084 * .. _`CEC-MODE-NO-INITIATOR`:
0085
0086 - ``CEC_MODE_NO_INITIATOR``
0087 - 0x0
0088 - This is not an initiator, i.e. it cannot transmit CEC messages or
0089 make any other changes to the CEC adapter.
0090 * .. _`CEC-MODE-INITIATOR`:
0091
0092 - ``CEC_MODE_INITIATOR``
0093 - 0x1
0094 - This is an initiator (the default when the device is opened) and
0095 it can transmit CEC messages and make changes to the CEC adapter,
0096 unless there is an exclusive initiator.
0097 * .. _`CEC-MODE-EXCL-INITIATOR`:
0098
0099 - ``CEC_MODE_EXCL_INITIATOR``
0100 - 0x2
0101 - This is an exclusive initiator and this file descriptor is the
0102 only one that can transmit CEC messages and make changes to the
0103 CEC adapter. If someone else is already the exclusive initiator
0104 then an attempt to become one will return the ``EBUSY`` error code
0105 error.
0106
0107 Available follower modes are:
0108
0109 .. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{9.8cm}|
0110
0111 .. _cec-mode-follower_e:
0112
0113 .. cssclass:: longtable
0114
0115 .. flat-table:: Follower Modes
0116 :header-rows: 0
0117 :stub-columns: 0
0118 :widths: 3 1 16
0119
0120 * .. _`CEC-MODE-NO-FOLLOWER`:
0121
0122 - ``CEC_MODE_NO_FOLLOWER``
0123 - 0x00
0124 - This is not a follower (the default when the device is opened).
0125 * .. _`CEC-MODE-FOLLOWER`:
0126
0127 - ``CEC_MODE_FOLLOWER``
0128 - 0x10
0129 - This is a follower and it will receive CEC messages unless there
0130 is an exclusive follower. You cannot become a follower if
0131 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
0132 was specified, the ``EINVAL`` error code is returned in that case.
0133 * .. _`CEC-MODE-EXCL-FOLLOWER`:
0134
0135 - ``CEC_MODE_EXCL_FOLLOWER``
0136 - 0x20
0137 - This is an exclusive follower and only this file descriptor will
0138 receive CEC messages for processing. If someone else is already
0139 the exclusive follower then an attempt to become one will return
0140 the ``EBUSY`` error code. You cannot become a follower if
0141 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
0142 was specified, the ``EINVAL`` error code is returned in that case.
0143 * .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
0144
0145 - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
0146 - 0x30
0147 - This is an exclusive follower and only this file descriptor will
0148 receive CEC messages for processing. In addition it will put the
0149 CEC device into passthrough mode, allowing the exclusive follower
0150 to handle most core messages instead of relying on the CEC
0151 framework for that. If someone else is already the exclusive
0152 follower then an attempt to become one will return the ``EBUSY`` error
0153 code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
0154 is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
0155 the ``EINVAL`` error code is returned in that case.
0156 * .. _`CEC-MODE-MONITOR-PIN`:
0157
0158 - ``CEC_MODE_MONITOR_PIN``
0159 - 0xd0
0160 - Put the file descriptor into pin monitoring mode. Can only be used in
0161 combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
0162 otherwise the ``EINVAL`` error code will be returned.
0163 This mode requires that the :ref:`CEC_CAP_MONITOR_PIN <CEC-CAP-MONITOR-PIN>`
0164 capability is set, otherwise the ``EINVAL`` error code is returned.
0165 While in pin monitoring mode this file descriptor can receive the
0166 ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the
0167 low-level CEC pin transitions. This is very useful for debugging.
0168 This mode is only allowed if the process has the ``CAP_NET_ADMIN``
0169 capability. If that is not set, then the ``EPERM`` error code is returned.
0170 * .. _`CEC-MODE-MONITOR`:
0171
0172 - ``CEC_MODE_MONITOR``
0173 - 0xe0
0174 - Put the file descriptor into monitor mode. Can only be used in
0175 combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
0176 otherwise the ``EINVAL`` error code will be returned.
0177 In monitor mode all messages this CEC
0178 device transmits and all messages it receives (both broadcast
0179 messages and directed messages for one its logical addresses) will
0180 be reported. This is very useful for debugging. This is only
0181 allowed if the process has the ``CAP_NET_ADMIN`` capability. If
0182 that is not set, then the ``EPERM`` error code is returned.
0183 * .. _`CEC-MODE-MONITOR-ALL`:
0184
0185 - ``CEC_MODE_MONITOR_ALL``
0186 - 0xf0
0187 - Put the file descriptor into 'monitor all' mode. Can only be used
0188 in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
0189 the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
0190 this CEC device transmits and all messages it receives, including
0191 directed messages for other CEC devices, will be reported. This is
0192 very useful for debugging, but not all devices support this. This
0193 mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
0194 otherwise the ``EINVAL`` error code is returned. This is only allowed if
0195 the process has the ``CAP_NET_ADMIN`` capability. If that is not
0196 set, then the ``EPERM`` error code is returned.
0197
0198 Core message processing details:
0199
0200 .. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
0201
0202 .. _cec-core-processing:
0203
0204 .. flat-table:: Core Message Processing
0205 :header-rows: 0
0206 :stub-columns: 0
0207 :widths: 1 8
0208
0209 * .. _`CEC-MSG-GET-CEC-VERSION`:
0210
0211 - ``CEC_MSG_GET_CEC_VERSION``
0212 - The core will return the CEC version that was set with
0213 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
0214 except when in passthrough mode. In passthrough mode the core
0215 does nothing and this message has to be handled by a follower
0216 instead.
0217 * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
0218
0219 - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
0220 - The core will return the vendor ID that was set with
0221 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
0222 except when in passthrough mode. In passthrough mode the core
0223 does nothing and this message has to be handled by a follower
0224 instead.
0225 * .. _`CEC-MSG-ABORT`:
0226
0227 - ``CEC_MSG_ABORT``
0228 - The core will return a Feature Abort message with reason
0229 'Feature Refused' as per the specification, except when in
0230 passthrough mode. In passthrough mode the core does nothing
0231 and this message has to be handled by a follower instead.
0232 * .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
0233
0234 - ``CEC_MSG_GIVE_PHYSICAL_ADDR``
0235 - The core will report the current physical address, except when
0236 in passthrough mode. In passthrough mode the core does nothing
0237 and this message has to be handled by a follower instead.
0238 * .. _`CEC-MSG-GIVE-OSD-NAME`:
0239
0240 - ``CEC_MSG_GIVE_OSD_NAME``
0241 - The core will report the current OSD name that was set with
0242 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
0243 except when in passthrough mode. In passthrough mode the core
0244 does nothing and this message has to be handled by a follower
0245 instead.
0246 * .. _`CEC-MSG-GIVE-FEATURES`:
0247
0248 - ``CEC_MSG_GIVE_FEATURES``
0249 - The core will do nothing if the CEC version is older than 2.0,
0250 otherwise it will report the current features that were set with
0251 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
0252 except when in passthrough mode. In passthrough mode the core
0253 does nothing (for any CEC version) and this message has to be handled
0254 by a follower instead.
0255 * .. _`CEC-MSG-USER-CONTROL-PRESSED`:
0256
0257 - ``CEC_MSG_USER_CONTROL_PRESSED``
0258 - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
0259 :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
0260 is set, then generate a remote control key
0261 press. This message is always passed on to the follower(s).
0262 * .. _`CEC-MSG-USER-CONTROL-RELEASED`:
0263
0264 - ``CEC_MSG_USER_CONTROL_RELEASED``
0265 - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
0266 :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
0267 is set, then generate a remote control key
0268 release. This message is always passed on to the follower(s).
0269 * .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
0270
0271 - ``CEC_MSG_REPORT_PHYSICAL_ADDR``
0272 - The CEC framework will make note of the reported physical address
0273 and then just pass the message on to the follower(s).
0274
0275
0276 Return Value
0277 ============
0278
0279 On success 0 is returned, on error -1 and the ``errno`` variable is set
0280 appropriately. The generic error codes are described at the
0281 :ref:`Generic Error Codes <gen-errors>` chapter.
0282
0283 The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following
0284 error codes:
0285
0286 EINVAL
0287 The requested mode is invalid.
0288
0289 EPERM
0290 Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN``
0291 capability.
0292
0293 EBUSY
0294 Someone else is already an exclusive follower or initiator.
