1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later 2 3.. _CEC_MODE: 4.. _CEC_G_MODE: 5.. _CEC_S_MODE: 6 7******************************** 8ioctls CEC_G_MODE and CEC_S_MODE 9******************************** 10 11CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter 12 13Synopsis 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 22Arguments 23========= 24 25``fd`` 26 File descriptor returned by :c:func:`open() <cec-open>`. 27 28``argp`` 29 Pointer to CEC mode. 30 31Description 32=========== 33 34By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent 35applications from stepping on each others toes it must be possible to 36obtain exclusive access to the CEC adapter. This ioctl sets the 37filehandle to initiator and/or follower mode which can be exclusive 38depending on the chosen mode. The initiator is the filehandle that is 39used to initiate messages, i.e. it commands other CEC devices. The 40follower is the filehandle that receives messages sent to the CEC 41adapter and processes them. The same filehandle can be both initiator 42and follower, or this role can be taken by two different filehandles. 43 44When a CEC message is received, then the CEC framework will decide how 45it will be processed. If the message is a reply to an earlier 46transmitted message, then the reply is sent back to the filehandle that 47is waiting for it. In addition the CEC framework will process it. 48 49If the message is not a reply, then the CEC framework will process it 50first. If there is no follower, then the message is just discarded and a 51feature abort is sent back to the initiator if the framework couldn't 52process it. If there is a follower, then the message is passed on to the 53follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue 54the new message. The framework expects the follower to make the right 55decisions. 56 57The CEC framework will process core messages unless requested otherwise 58by the follower. The follower can enable the passthrough mode. In that 59case, the CEC framework will pass on most core messages without 60processing them and the follower will have to implement those messages. 61There are some messages that the core will always process, regardless of 62the passthrough mode. See :ref:`cec-core-processing` for details. 63 64If there is no initiator, then any CEC filehandle can use 65:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive 66initiator then only that initiator can call 67:ref:`CEC_TRANSMIT`. The follower can of course 68always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. 69 70Available 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 105Available 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>`, 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 197Core 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 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