1 .. -*- coding: utf-8; mode: rst -*-
7 ********************************
8 ioctls CEC_G_MODE and CEC_S_MODE
9 ********************************
11 CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
16 .. cpp:function:: int ioctl( int fd, int request, __u32 *argp )
22 File descriptor returned by :ref:`open() <cec-func-open>`.
25 CEC_G_MODE, CEC_S_MODE
33 .. note:: This documents the proposed CEC API. This API is not yet finalized
34 and is currently only available as a staging kernel module.
36 By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
37 applications from stepping on each others toes it must be possible to
38 obtain exclusive access to the CEC adapter. This ioctl sets the
39 filehandle to initiator and/or follower mode which can be exclusive
40 depending on the chosen mode. The initiator is the filehandle that is
41 used to initiate messages, i.e. it commands other CEC devices. The
42 follower is the filehandle that receives messages sent to the CEC
43 adapter and processes them. The same filehandle can be both initiator
44 and follower, or this role can be taken by two different filehandles.
46 When a CEC message is received, then the CEC framework will decide how
47 it will be processed. If the message is a reply to an earlier
48 transmitted message, then the reply is sent back to the filehandle that
49 is waiting for it. In addition the CEC framework will process it.
51 If the message is not a reply, then the CEC framework will process it
52 first. If there is no follower, then the message is just discarded and a
53 feature abort is sent back to the initiator if the framework couldn't
54 process it. If there is a follower, then the message is passed on to the
55 follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
56 the new message. The framework expects the follower to make the right
59 The CEC framework will process core messages unless requested otherwise
60 by the follower. The follower can enable the passthrough mode. In that
61 case, the CEC framework will pass on most core messages without
62 processing them and the follower will have to implement those messages.
63 There are some messages that the core will always process, regardless of
64 the passthrough mode. See :ref:`cec-core-processing` for details.
66 If there is no initiator, then any CEC filehandle can use
67 :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
68 initiator then only that initiator can call
69 :ref:`CEC_TRANSMIT`. The follower can of course
70 always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
72 Available initiator modes are:
75 .. _cec-mode-initiator_e:
77 .. flat-table:: Initiator Modes
83 - .. _`CEC-MODE-NO-INITIATOR`:
85 - ``CEC_MODE_NO_INITIATOR``
89 - This is not an initiator, i.e. it cannot transmit CEC messages or
90 make any other changes to the CEC adapter.
92 - .. _`CEC-MODE-INITIATOR`:
94 - ``CEC_MODE_INITIATOR``
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.
102 - .. _`CEC-MODE-EXCL-INITIATOR`:
104 - ``CEC_MODE_EXCL_INITIATOR``
108 - This is an exclusive initiator and this file descriptor is the
109 only one that can transmit CEC messages and make changes to the
110 CEC adapter. If someone else is already the exclusive initiator
111 then an attempt to become one will return the ``EBUSY`` error code
115 Available follower modes are:
118 .. _cec-mode-follower_e:
120 .. flat-table:: Follower Modes
126 - .. _`CEC-MODE-NO-FOLLOWER`:
128 - ``CEC_MODE_NO_FOLLOWER``
132 - This is not a follower (the default when the device is opened).
134 - .. _`CEC-MODE-FOLLOWER`:
136 - ``CEC_MODE_FOLLOWER``
140 - This is a follower and it will receive CEC messages unless there
141 is an exclusive follower. You cannot become a follower if
142 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
143 was specified, the ``EINVAL`` error code is returned in that case.
145 - .. _`CEC-MODE-EXCL-FOLLOWER`:
147 - ``CEC_MODE_EXCL_FOLLOWER``
151 - This is an exclusive follower and only this file descriptor will
152 receive CEC messages for processing. If someone else is already
153 the exclusive follower then an attempt to become one will return
154 the ``EBUSY`` error code. You cannot become a follower if
155 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
156 was specified, the ``EINVAL`` error code is returned in that case.
158 - .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
160 - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
164 - This is an exclusive follower and only this file descriptor will
165 receive CEC messages for processing. In addition it will put the
166 CEC device into passthrough mode, allowing the exclusive follower
167 to handle most core messages instead of relying on the CEC
168 framework for that. If someone else is already the exclusive
169 follower then an attempt to become one will return the ``EBUSY`` error
170 code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
171 is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
172 the ``EINVAL`` error code is returned in that case.
174 - .. _`CEC-MODE-MONITOR`:
176 - ``CEC_MODE_MONITOR``
180 - Put the file descriptor into monitor mode. Can only be used in
181 combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise EINVAL error
182 code will be returned. 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.
189 - .. _`CEC-MODE-MONITOR-ALL`:
191 - ``CEC_MODE_MONITOR_ALL``
195 - Put the file descriptor into 'monitor all' mode. Can only be used
196 in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
197 the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
198 this CEC device transmits and all messages it receives, including
199 directed messages for other CEC devices will be reported. This is
200 very useful for debugging, but not all devices support this. This
201 mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
202 otherwise the ``EINVAL`` error code is returned. This is only allowed if
203 the process has the ``CAP_NET_ADMIN`` capability. If that is not
204 set, then the ``EPERM`` error code is returned.
207 Core message processing details:
210 .. _cec-core-processing:
212 .. flat-table:: Core Message Processing
218 - .. _`CEC-MSG-GET-CEC-VERSION`:
220 - ``CEC_MSG_GET_CEC_VERSION``
222 - When in passthrough mode this message has to be handled by
223 userspace, otherwise the core will return the CEC version that was
224 set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
226 - .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
228 - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
230 - When in passthrough mode this message has to be handled by
231 userspace, otherwise the core will return the vendor ID that was
232 set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
234 - .. _`CEC-MSG-ABORT`:
238 - When in passthrough mode this message has to be handled by
239 userspace, otherwise the core will return a feature refused
240 message as per the specification.
242 - .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
244 - ``CEC_MSG_GIVE_PHYSICAL_ADDR``
246 - When in passthrough mode this message has to be handled by
247 userspace, otherwise the core will report the current physical
250 - .. _`CEC-MSG-GIVE-OSD-NAME`:
252 - ``CEC_MSG_GIVE_OSD_NAME``
254 - When in passthrough mode this message has to be handled by
255 userspace, otherwise the core will report the current OSD name as
256 was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
258 - .. _`CEC-MSG-GIVE-FEATURES`:
260 - ``CEC_MSG_GIVE_FEATURES``
262 - When in passthrough mode this message has to be handled by
263 userspace, otherwise the core will report the current features as
264 was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
265 or the message is ignored if the CEC version was older than 2.0.
267 - .. _`CEC-MSG-USER-CONTROL-PRESSED`:
269 - ``CEC_MSG_USER_CONTROL_PRESSED``
271 - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
272 press. This message is always passed on to userspace.
274 - .. _`CEC-MSG-USER-CONTROL-RELEASED`:
276 - ``CEC_MSG_USER_CONTROL_RELEASED``
278 - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
279 release. This message is always passed on to userspace.
281 - .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
283 - ``CEC_MSG_REPORT_PHYSICAL_ADDR``
285 - The CEC framework will make note of the reported physical address
286 and then just pass the message on to userspace.
293 On success 0 is returned, on error -1 and the ``errno`` variable is set
294 appropriately. The generic error codes are described at the
295 :ref:`Generic Error Codes <gen-errors>` chapter.