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******************************** 9ioctls CEC_G_MODE and CEC_S_MODE 10******************************** 11 12CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter 13 14Synopsis 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 25Arguments 26========= 27 28``fd`` 29 File descriptor returned by :c:func:`open()`. 30 31``argp`` 32 Pointer to CEC mode. 33 34Description 35=========== 36 37By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent 38applications from stepping on each others toes it must be possible to 39obtain exclusive access to the CEC adapter. This ioctl sets the 40filehandle to initiator and/or follower mode which can be exclusive 41depending on the chosen mode. The initiator is the filehandle that is 42used to initiate messages, i.e. it commands other CEC devices. The 43follower is the filehandle that receives messages sent to the CEC 44adapter and processes them. The same filehandle can be both initiator 45and follower, or this role can be taken by two different filehandles. 46 47When a CEC message is received, then the CEC framework will decide how 48it will be processed. If the message is a reply to an earlier 49transmitted message, then the reply is sent back to the filehandle that 50is waiting for it. In addition the CEC framework will process it. 51 52If the message is not a reply, then the CEC framework will process it 53first. If there is no follower, then the message is just discarded and a 54feature abort is sent back to the initiator if the framework couldn't 55process it. If there is a follower, then the message is passed on to the 56follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue 57the new message. The framework expects the follower to make the right 58decisions. 59 60The CEC framework will process core messages unless requested otherwise 61by the follower. The follower can enable the passthrough mode. In that 62case, the CEC framework will pass on most core messages without 63processing them and the follower will have to implement those messages. 64There are some messages that the core will always process, regardless of 65the passthrough mode. See :ref:`cec-core-processing` for details. 66 67If there is no initiator, then any CEC filehandle can use 68:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive 69initiator then only that initiator can call 70:ref:`CEC_TRANSMIT`. The follower can of course 71always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. 72 73Available initiator modes are: 74 75.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}| 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 107Available follower modes are: 108 109.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{9.8cm}| 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 198Core 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 276Return Value 277============ 278 279On success 0 is returned, on error -1 and the ``errno`` variable is set 280appropriately. The generic error codes are described at the 281:ref:`Generic Error Codes <gen-errors>` chapter. 282 283The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following 284error codes: 285 286EINVAL 287 The requested mode is invalid. 288 289EPERM 290 Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN`` 291 capability. 292 293EBUSY 294 Someone else is already an exclusive follower or initiator. 295