295 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: CEC3 4.. _CEC_MODE:5.. _CEC_G_MODE:6.. _CEC_S_MODE:7 8********************************9ioctls CEC_G_MODE and CEC_S_MODE10********************************11 12CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter13 14Synopsis15========16 17.. c:macro:: CEC_G_MODE18 19``int ioctl(int fd, CEC_G_MODE, __u32 *argp)``20 21.. c:macro:: CEC_S_MODE22 23``int ioctl(int fd, CEC_S_MODE, __u32 *argp)``24 25Arguments26=========27 28``fd``29 File descriptor returned by :c:func:`open()`.30 31``argp``32 Pointer to CEC mode.33 34Description35===========36 37By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent38applications from stepping on each others toes it must be possible to39obtain exclusive access to the CEC adapter. This ioctl sets the40filehandle to initiator and/or follower mode which can be exclusive41depending on the chosen mode. The initiator is the filehandle that is42used to initiate messages, i.e. it commands other CEC devices. The43follower is the filehandle that receives messages sent to the CEC44adapter and processes them. The same filehandle can be both initiator45and follower, or this role can be taken by two different filehandles.46 47When a CEC message is received, then the CEC framework will decide how48it will be processed. If the message is a reply to an earlier49transmitted message, then the reply is sent back to the filehandle that50is 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 it53first. If there is no follower, then the message is just discarded and a54feature abort is sent back to the initiator if the framework couldn't55process it. If there is a follower, then the message is passed on to the56follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue57the new message. The framework expects the follower to make the right58decisions.59 60The CEC framework will process core messages unless requested otherwise61by the follower. The follower can enable the passthrough mode. In that62case, the CEC framework will pass on most core messages without63processing them and the follower will have to implement those messages.64There are some messages that the core will always process, regardless of65the passthrough mode. See :ref:`cec-core-processing` for details.66 67If there is no initiator, then any CEC filehandle can use68:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive69initiator then only that initiator can call70:ref:`CEC_TRANSMIT`. The follower can of course71always 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 Modes80 :header-rows: 081 :stub-columns: 082 :widths: 3 1 1683 84 * .. _`CEC-MODE-NO-INITIATOR`:85 86 - ``CEC_MODE_NO_INITIATOR``87 - 0x088 - This is not an initiator, i.e. it cannot transmit CEC messages or89 make any other changes to the CEC adapter.90 * .. _`CEC-MODE-INITIATOR`:91 92 - ``CEC_MODE_INITIATOR``93 - 0x194 - This is an initiator (the default when the device is opened) and95 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 - 0x2101 - This is an exclusive initiator and this file descriptor is the102 only one that can transmit CEC messages and make changes to the103 CEC adapter. If someone else is already the exclusive initiator104 then an attempt to become one will return the ``EBUSY`` error code105 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:: longtable114 115.. flat-table:: Follower Modes116 :header-rows: 0117 :stub-columns: 0118 :widths: 3 1 16119 120 * .. _`CEC-MODE-NO-FOLLOWER`:121 122 - ``CEC_MODE_NO_FOLLOWER``123 - 0x00124 - This is not a follower (the default when the device is opened).125 * .. _`CEC-MODE-FOLLOWER`:126 127 - ``CEC_MODE_FOLLOWER``128 - 0x10129 - This is a follower and it will receive CEC messages unless there130 is an exclusive follower. You cannot become a follower if131 :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 - 0x20137 - This is an exclusive follower and only this file descriptor will138 receive CEC messages for processing. If someone else is already139 the exclusive follower then an attempt to become one will return140 the ``EBUSY`` error code. You cannot become a follower if141 :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 - 0x30147 - This is an exclusive follower and only this file descriptor will148 receive CEC messages for processing. In addition it will put the149 CEC device into passthrough mode, allowing the exclusive follower150 to handle most core messages instead of relying on the CEC151 framework for that. If someone else is already the exclusive152 follower then an attempt to become one will return the ``EBUSY`` error153 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 - 0xd0160 - Put the file descriptor into pin monitoring mode. Can only be used in161 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 the166 ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the167 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 - 0xe0174 - Put the file descriptor into monitor mode. Can only be used in175 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 CEC178 device transmits and all messages it receives (both broadcast179 messages and directed messages for one its logical addresses) will180 be reported. This is very useful for debugging. This is only181 allowed if the process has the ``CAP_NET_ADMIN`` capability. If182 that is not set, then the ``EPERM`` error code is returned.183 * .. _`CEC-MODE-MONITOR-ALL`:184 185 - ``CEC_MODE_MONITOR_ALL``186 - 0xf0187 - Put the file descriptor into 'monitor all' mode. Can only be used188 in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise189 the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages190 this CEC device transmits and all messages it receives, including191 directed messages for other CEC devices, will be reported. This is192 very useful for debugging, but not all devices support this. This193 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 if195 the process has the ``CAP_NET_ADMIN`` capability. If that is not196 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 Processing205 :header-rows: 0206 :stub-columns: 0207 :widths: 1 8208 209 * .. _`CEC-MSG-GET-CEC-VERSION`:210 211 - ``CEC_MSG_GET_CEC_VERSION``212 - The core will return the CEC version that was set with213 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,214 except when in passthrough mode. In passthrough mode the core215 does nothing and this message has to be handled by a follower216 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 with221 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,222 except when in passthrough mode. In passthrough mode the core223 does nothing and this message has to be handled by a follower224 instead.225 * .. _`CEC-MSG-ABORT`:226 227 - ``CEC_MSG_ABORT``228 - The core will return a Feature Abort message with reason229 'Feature Refused' as per the specification, except when in230 passthrough mode. In passthrough mode the core does nothing231 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 when236 in passthrough mode. In passthrough mode the core does nothing237 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 with242 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,243 except when in passthrough mode. In passthrough mode the core244 does nothing and this message has to be handled by a follower245 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 with251 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,252 except when in passthrough mode. In passthrough mode the core253 does nothing (for any CEC version) and this message has to be handled254 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 if259 :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`260 is set, then generate a remote control key261 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 if266 :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`267 is set, then generate a remote control key268 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 address273 and then just pass the message on to the follower(s).274 275 276Return Value277============278 279On success 0 is returned, on error -1 and the ``errno`` variable is set280appropriately. The generic error codes are described at the281:ref:`Generic Error Codes <gen-errors>` chapter.282 283The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following284error codes:285 286EINVAL287 The requested mode is invalid.288 289EPERM290 Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN``291 capability.292 293EBUSY294 Someone else is already an exclusive follower or initiator.295