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
35 This documents the proposed CEC API. This API is not yet finalized
36 and is currently only available as a staging kernel module.
38 By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
39 applications from stepping on each others toes it must be possible to
40 obtain exclusive access to the CEC adapter. This ioctl sets the
41 filehandle to initiator and/or follower mode which can be exclusive
42 depending on the chosen mode. The initiator is the filehandle that is
43 used to initiate messages, i.e. it commands other CEC devices. The
44 follower is the filehandle that receives messages sent to the CEC
45 adapter and processes them. The same filehandle can be both initiator
46 and follower, or this role can be taken by two different filehandles.
48 When a CEC message is received, then the CEC framework will decide how
49 it will be processed. If the message is a reply to an earlier
50 transmitted message, then the reply is sent back to the filehandle that
51 is waiting for it. In addition the CEC framework will process it.
53 If the message is not a reply, then the CEC framework will process it
54 first. If there is no follower, then the message is just discarded and a
55 feature abort is sent back to the initiator if the framework couldn't
56 process it. If there is a follower, then the message is passed on to the
57 follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
58 the new message. The framework expects the follower to make the right
61 The CEC framework will process core messages unless requested otherwise
62 by the follower. The follower can enable the passthrough mode. In that
63 case, the CEC framework will pass on most core messages without
64 processing them and the follower will have to implement those messages.
65 There are some messages that the core will always process, regardless of
66 the passthrough mode. See :ref:`cec-core-processing` for details.
68 If there is no initiator, then any CEC filehandle can use
69 :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
70 initiator then only that initiator can call
71 :ref:`CEC_TRANSMIT`. The follower can of course
72 always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
74 Available initiator modes are:
77 .. _cec-mode-initiator_e:
79 .. flat-table:: Initiator Modes
85 - .. _`CEC-MODE-NO-INITIATOR`:
87 - ``CEC_MODE_NO_INITIATOR``
91 - This is not an initiator, i.e. it cannot transmit CEC messages or
92 make any other changes to the CEC adapter.
94 - .. _`CEC-MODE-INITIATOR`:
96 - ``CEC_MODE_INITIATOR``
100 - This is an initiator (the default when the device is opened) and
101 it can transmit CEC messages and make changes to the CEC adapter,
102 unless there is an exclusive initiator.
104 - .. _`CEC-MODE-EXCL-INITIATOR`:
106 - ``CEC_MODE_EXCL_INITIATOR``
110 - This is an exclusive initiator and this file descriptor is the
111 only one that can transmit CEC messages and make changes to the
112 CEC adapter. If someone else is already the exclusive initiator
113 then an attempt to become one will return the ``EBUSY`` error code
117 Available follower modes are:
120 .. _cec-mode-follower_e:
122 .. flat-table:: Follower Modes
128 - .. _`CEC-MODE-NO-FOLLOWER`:
130 - ``CEC_MODE_NO_FOLLOWER``
134 - This is not a follower (the default when the device is opened).
136 - .. _`CEC-MODE-FOLLOWER`:
138 - ``CEC_MODE_FOLLOWER``
142 - This is a follower and it will receive CEC messages unless there
143 is an exclusive follower. You cannot become a follower if
144 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
145 was specified, the ``EINVAL`` error code is returned in that case.
147 - .. _`CEC-MODE-EXCL-FOLLOWER`:
149 - ``CEC_MODE_EXCL_FOLLOWER``
153 - This is an exclusive follower and only this file descriptor will
154 receive CEC messages for processing. If someone else is already
155 the exclusive follower then an attempt to become one will return
156 the ``EBUSY`` error code. You cannot become a follower if
157 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
158 was specified, the ``EINVAL`` error code is returned in that case.
160 - .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
162 - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
166 - This is an exclusive follower and only this file descriptor will
167 receive CEC messages for processing. In addition it will put the
168 CEC device into passthrough mode, allowing the exclusive follower
169 to handle most core messages instead of relying on the CEC
170 framework for that. If someone else is already the exclusive
171 follower then an attempt to become one will return the ``EBUSY`` error
172 code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
173 is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
174 the ``EINVAL`` error code is returned in that case.
176 - .. _`CEC-MODE-MONITOR`:
178 - ``CEC_MODE_MONITOR``
182 - Put the file descriptor into monitor mode. Can only be used in
183 combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise EINVAL error
184 code will be returned. In monitor mode all messages this CEC
185 device transmits and all messages it receives (both broadcast
186 messages and directed messages for one its logical addresses) will
187 be reported. This is very useful for debugging. This is only
188 allowed if the process has the ``CAP_NET_ADMIN`` capability. If
189 that is not set, then the ``EPERM`` error code is returned.
191 - .. _`CEC-MODE-MONITOR-ALL`:
193 - ``CEC_MODE_MONITOR_ALL``
197 - Put the file descriptor into 'monitor all' mode. Can only be used
198 in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
199 the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
200 this CEC device transmits and all messages it receives, including
201 directed messages for other CEC devices will be reported. This is
202 very useful for debugging, but not all devices support this. This
203 mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
204 otherwise the ``EINVAL`` error code is returned. This is only allowed if
205 the process has the ``CAP_NET_ADMIN`` capability. If that is not
206 set, then the ``EPERM`` error code is returned.
209 Core message processing details:
212 .. _cec-core-processing:
214 .. flat-table:: Core Message Processing
220 - .. _`CEC-MSG-GET-CEC-VERSION`:
222 - ``CEC_MSG_GET_CEC_VERSION``
224 - When in passthrough mode this message has to be handled by
225 userspace, otherwise the core will return the CEC version that was
226 set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
228 - .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
230 - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
232 - When in passthrough mode this message has to be handled by
233 userspace, otherwise the core will return the vendor ID that was
234 set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
236 - .. _`CEC-MSG-ABORT`:
240 - When in passthrough mode this message has to be handled by
241 userspace, otherwise the core will return a feature refused
242 message as per the specification.
244 - .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
246 - ``CEC_MSG_GIVE_PHYSICAL_ADDR``
248 - When in passthrough mode this message has to be handled by
249 userspace, otherwise the core will report the current physical
252 - .. _`CEC-MSG-GIVE-OSD-NAME`:
254 - ``CEC_MSG_GIVE_OSD_NAME``
256 - When in passthrough mode this message has to be handled by
257 userspace, otherwise the core will report the current OSD name as
258 was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`.
260 - .. _`CEC-MSG-GIVE-FEATURES`:
262 - ``CEC_MSG_GIVE_FEATURES``
264 - When in passthrough mode this message has to be handled by
265 userspace, otherwise the core will report the current features as
266 was set with :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
267 or the message is ignored if the CEC version was older than 2.0.
269 - .. _`CEC-MSG-USER-CONTROL-PRESSED`:
271 - ``CEC_MSG_USER_CONTROL_PRESSED``
273 - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
274 press. This message is always passed on to userspace.
276 - .. _`CEC-MSG-USER-CONTROL-RELEASED`:
278 - ``CEC_MSG_USER_CONTROL_RELEASED``
280 - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set, then generate a remote control key
281 release. This message is always passed on to userspace.
283 - .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
285 - ``CEC_MSG_REPORT_PHYSICAL_ADDR``
287 - The CEC framework will make note of the reported physical address
288 and then just pass the message on to userspace.
295 On success 0 is returned, on error -1 and the ``errno`` variable is set
296 appropriately. The generic error codes are described at the
297 :ref:`Generic Error Codes <gen-errors>` chapter.