1.. Permission is granted to copy, distribute and/or modify this 2.. document under the terms of the GNU Free Documentation License, 3.. Version 1.1 or any later version published by the Free Software 4.. Foundation, with no Invariant Sections, no Front-Cover Texts 5.. and no Back-Cover Texts. A copy of the license is included at 6.. Documentation/userspace-api/media/fdl-appendix.rst. 7.. 8.. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections 9 10.. _CEC_MODE: 11.. _CEC_G_MODE: 12.. _CEC_S_MODE: 13 14******************************** 15ioctls CEC_G_MODE and CEC_S_MODE 16******************************** 17 18CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter 19 20Synopsis 21======== 22 23.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp ) 24 :name: CEC_G_MODE 25 26.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp ) 27 :name: CEC_S_MODE 28 29Arguments 30========= 31 32``fd`` 33 File descriptor returned by :c:func:`open() <cec-open>`. 34 35``argp`` 36 Pointer to CEC mode. 37 38Description 39=========== 40 41By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent 42applications from stepping on each others toes it must be possible to 43obtain exclusive access to the CEC adapter. This ioctl sets the 44filehandle to initiator and/or follower mode which can be exclusive 45depending on the chosen mode. The initiator is the filehandle that is 46used to initiate messages, i.e. it commands other CEC devices. The 47follower is the filehandle that receives messages sent to the CEC 48adapter and processes them. The same filehandle can be both initiator 49and follower, or this role can be taken by two different filehandles. 50 51When a CEC message is received, then the CEC framework will decide how 52it will be processed. If the message is a reply to an earlier 53transmitted message, then the reply is sent back to the filehandle that 54is waiting for it. In addition the CEC framework will process it. 55 56If the message is not a reply, then the CEC framework will process it 57first. If there is no follower, then the message is just discarded and a 58feature abort is sent back to the initiator if the framework couldn't 59process it. If there is a follower, then the message is passed on to the 60follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue 61the new message. The framework expects the follower to make the right 62decisions. 63 64The CEC framework will process core messages unless requested otherwise 65by the follower. The follower can enable the passthrough mode. In that 66case, the CEC framework will pass on most core messages without 67processing them and the follower will have to implement those messages. 68There are some messages that the core will always process, regardless of 69the passthrough mode. See :ref:`cec-core-processing` for details. 70 71If there is no initiator, then any CEC filehandle can use 72:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive 73initiator then only that initiator can call 74:ref:`CEC_TRANSMIT`. The follower can of course 75always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. 76 77Available initiator modes are: 78 79.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}| 80 81.. _cec-mode-initiator_e: 82 83.. flat-table:: Initiator Modes 84 :header-rows: 0 85 :stub-columns: 0 86 :widths: 3 1 16 87 88 * .. _`CEC-MODE-NO-INITIATOR`: 89 90 - ``CEC_MODE_NO_INITIATOR`` 91 - 0x0 92 - This is not an initiator, i.e. it cannot transmit CEC messages or 93 make any other changes to the CEC adapter. 94 * .. _`CEC-MODE-INITIATOR`: 95 96 - ``CEC_MODE_INITIATOR`` 97 - 0x1 98 - This is an initiator (the default when the device is opened) and 99 it can transmit CEC messages and make changes to the CEC adapter, 100 unless there is an exclusive initiator. 101 * .. _`CEC-MODE-EXCL-INITIATOR`: 102 103 - ``CEC_MODE_EXCL_INITIATOR`` 104 - 0x2 105 - This is an exclusive initiator and this file descriptor is the 106 only one that can transmit CEC messages and make changes to the 107 CEC adapter. If someone else is already the exclusive initiator 108 then an attempt to become one will return the ``EBUSY`` error code 109 error. 110 111 112Available follower modes are: 113 114.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}| 115 116.. _cec-mode-follower_e: 117 118.. cssclass:: longtable 119 120.. flat-table:: Follower Modes 121 :header-rows: 0 122 :stub-columns: 0 123 :widths: 3 1 16 124 125 * .. _`CEC-MODE-NO-FOLLOWER`: 126 127 - ``CEC_MODE_NO_FOLLOWER`` 128 - 0x00 129 - This is not a follower (the default when the device is opened). 130 * .. _`CEC-MODE-FOLLOWER`: 131 132 - ``CEC_MODE_FOLLOWER`` 133 - 0x10 134 - This is a follower and it will receive CEC messages unless there 135 is an exclusive follower. You cannot become a follower if 136 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` 137 was specified, the ``EINVAL`` error code is returned in that case. 138 * .. _`CEC-MODE-EXCL-FOLLOWER`: 139 140 - ``CEC_MODE_EXCL_FOLLOWER`` 141 - 0x20 142 - This is an exclusive follower and only this file descriptor will 143 receive CEC messages for processing. If someone else is already 144 the exclusive follower then an attempt to become one will return 145 the ``EBUSY`` error code. You cannot become a follower if 146 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` 147 was specified, the ``EINVAL`` error code is returned in that case. 148 * .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`: 149 150 - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU`` 151 - 0x30 152 - This is an exclusive follower and only this file descriptor will 153 receive CEC messages for processing. In addition it will put the 154 CEC device into passthrough mode, allowing the exclusive follower 155 to handle most core messages instead of relying on the CEC 156 framework for that. If someone else is already the exclusive 157 follower then an attempt to become one will return the ``EBUSY`` error 158 code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` 159 is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified, 160 the ``EINVAL`` error code is returned in that case. 161 * .. _`CEC-MODE-MONITOR-PIN`: 162 163 - ``CEC_MODE_MONITOR_PIN`` 164 - 0xd0 165 - Put the file descriptor into pin monitoring mode. Can only be used in 166 combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, 167 otherwise the ``EINVAL`` error code will be returned. 168 This mode requires that the :ref:`CEC_CAP_MONITOR_PIN <CEC-CAP-MONITOR-PIN>` 169 capability is set, otherwise the ``EINVAL`` error code is returned. 170 While in pin monitoring mode this file descriptor can receive the 171 ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the 172 low-level CEC pin transitions. This is very useful for debugging. 173 This mode is only allowed if the process has the ``CAP_NET_ADMIN`` 174 capability. If that is not set, then the ``EPERM`` error code is returned. 175 * .. _`CEC-MODE-MONITOR`: 176 177 - ``CEC_MODE_MONITOR`` 178 - 0xe0 179 - Put the file descriptor into monitor mode. Can only be used in 180 combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, 181 otherwise the ``EINVAL`` error code will be returned. 182 In monitor mode all messages this CEC 183 device transmits and all messages it receives (both broadcast 184 messages and directed messages for one its logical addresses) will 185 be reported. This is very useful for debugging. This is only 186 allowed if the process has the ``CAP_NET_ADMIN`` capability. If 187 that is not set, then the ``EPERM`` error code is returned. 188 * .. _`CEC-MODE-MONITOR-ALL`: 189 190 - ``CEC_MODE_MONITOR_ALL`` 191 - 0xf0 192 - Put the file descriptor into 'monitor all' mode. Can only be used 193 in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise 194 the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages 195 this CEC device transmits and all messages it receives, including 196 directed messages for other CEC devices will be reported. This is 197 very useful for debugging, but not all devices support this. This 198 mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set, 199 otherwise the ``EINVAL`` error code is returned. This is only allowed if 200 the process has the ``CAP_NET_ADMIN`` capability. If that is not 201 set, then the ``EPERM`` error code is returned. 202 203 204Core message processing details: 205 206.. tabularcolumns:: |p{6.6cm}|p{10.9cm}| 207 208.. _cec-core-processing: 209 210.. flat-table:: Core Message Processing 211 :header-rows: 0 212 :stub-columns: 0 213 :widths: 1 8 214 215 * .. _`CEC-MSG-GET-CEC-VERSION`: 216 217 - ``CEC_MSG_GET_CEC_VERSION`` 218 - The core will return the CEC version that was set with 219 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`, 220 except when in passthrough mode. In passthrough mode the core 221 does nothing and this message has to be handled by a follower 222 instead. 223 * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`: 224 225 - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID`` 226 - The core will return the vendor ID that was set with 227 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`, 228 except when in passthrough mode. In passthrough mode the core 229 does nothing and this message has to be handled by a follower 230 instead. 231 * .. _`CEC-MSG-ABORT`: 232 233 - ``CEC_MSG_ABORT`` 234 - The core will return a Feature Abort message with reason 235 'Feature Refused' as per the specification, except when in 236 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-PHYSICAL-ADDR`: 239 240 - ``CEC_MSG_GIVE_PHYSICAL_ADDR`` 241 - The core will report the current physical address, except when 242 in passthrough mode. In passthrough mode the core does nothing 243 and this message has to be handled by a follower instead. 244 * .. _`CEC-MSG-GIVE-OSD-NAME`: 245 246 - ``CEC_MSG_GIVE_OSD_NAME`` 247 - The core will report the current OSD name that was set with 248 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`, 249 except when in passthrough mode. In passthrough mode the core 250 does nothing and this message has to be handled by a follower 251 instead. 252 * .. _`CEC-MSG-GIVE-FEATURES`: 253 254 - ``CEC_MSG_GIVE_FEATURES`` 255 - The core will do nothing if the CEC version is older than 2.0, 256 otherwise it will report the current features that were set with 257 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`, 258 except when in passthrough mode. In passthrough mode the core 259 does nothing (for any CEC version) and this message has to be handled 260 by a follower instead. 261 * .. _`CEC-MSG-USER-CONTROL-PRESSED`: 262 263 - ``CEC_MSG_USER_CONTROL_PRESSED`` 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 press. This message is always passed on to the follower(s). 268 * .. _`CEC-MSG-USER-CONTROL-RELEASED`: 269 270 - ``CEC_MSG_USER_CONTROL_RELEASED`` 271 - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if 272 :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>` 273 is set, then generate a remote control key 274 release. This message is always passed on to the follower(s). 275 * .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`: 276 277 - ``CEC_MSG_REPORT_PHYSICAL_ADDR`` 278 - The CEC framework will make note of the reported physical address 279 and then just pass the message on to the follower(s). 280 281 282 283Return Value 284============ 285 286On success 0 is returned, on error -1 and the ``errno`` variable is set 287appropriately. The generic error codes are described at the 288:ref:`Generic Error Codes <gen-errors>` chapter. 289 290The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following 291error codes: 292 293EINVAL 294 The requested mode is invalid. 295 296EPERM 297 Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN`` 298 capability. 299 300EBUSY 301 Someone else is already an exclusive follower or initiator. 302