1 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
2 .. c:namespace:: CEC
3
4 .. _CEC_MODE:
5 .. _CEC_G_MODE:
6 .. _CEC_S_MODE:
7
8 ********************************
9 ioctls CEC_G_MODE and CEC_S_MODE
10 ********************************
11
12 CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
13
14 Synopsis
15 ========
16
17 .. c:macro:: CEC_G_MODE
18
19 ``int ioctl(int fd, CEC_G_MODE, __u32 *argp)``
20
21 .. c:macro:: CEC_S_MODE
22
23 ``int ioctl(int fd, CEC_S_MODE, __u32 *argp)``
24
25 Arguments
26 =========
27
28 ``fd``
29 File descriptor returned by :c:func:`open()`.
30
31 ``argp``
32 Pointer to CEC mode.
33
34 Description
35 ===========
36
37 By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
38 applications from stepping on each others toes it must be possible to
39 obtain exclusive access to the CEC adapter. This ioctl sets the
40 filehandle to initiator and/or follower mode which can be exclusive
41 depending on the chosen mode. The initiator is the filehandle that is
42 used to initiate messages, i.e. it commands other CEC devices. The
43 follower is the filehandle that receives messages sent to the CEC
44 adapter and processes them. The same filehandle can be both initiator
45 and follower, or this role can be taken by two different filehandles.
46
47 When a CEC message is received, then the CEC framework will decide how
48 it will be processed. If the message is a reply to an earlier
49 transmitted message, then the reply is sent back to the filehandle that
50 is waiting for it. In addition the CEC framework will process it.
51
52 If the message is not a reply, then the CEC framework will process it
53 first. If there is no follower, then the message is just discarded and a
54 feature abort is sent back to the initiator if the framework couldn't
55 process it. If there is a follower, then the message is passed on to the
56 follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
57 the new message. The framework expects the follower to make the right
58 decisions.
59
60 The CEC framework will process core messages unless requested otherwise
61 by the follower. The follower can enable the passthrough mode. In that
62 case, the CEC framework will pass on most core messages without
63 processing them and the follower will have to implement those messages.
64 There are some messages that the core will always process, regardless of
65 the passthrough mode. See :ref:`cec-core-processing` for details.
66
67 If there is no initiator, then any CEC filehandle can use
68 :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
69 initiator then only that initiator can call
70 :ref:`CEC_TRANSMIT`. The follower can of course
71 always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
72
73 Available 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 Modes
80 :header-rows: 0
81 :stub-columns: 0
82 :widths: 3 1 16
83
84 * .. _`CEC-MODE-NO-INITIATOR`:
85
86 - ``CEC_MODE_NO_INITIATOR``
87 - 0x0
88 - This is not an initiator, i.e. it cannot transmit CEC messages or
89 make any other changes to the CEC adapter.
90 * .. _`CEC-MODE-INITIATOR`:
91
92 - ``CEC_MODE_INITIATOR``
93 - 0x1
94 - This is an initiator (the default when the device is opened) and
95 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 - 0x2
101 - This is an exclusive initiator and this file descriptor is the
102 only one that can transmit CEC messages and make changes to the
103 CEC adapter. If someone else is already the exclusive initiator
104 then an attempt to become one will return the ``EBUSY`` error code
105 error.
106
107 Available follower modes are:
108
109 .. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{9.8cm}|
110
111 .. _cec-mode-follower_e:
112
113 .. cssclass:: longtable
114
115 .. flat-table:: Follower Modes
116 :header-rows: 0
117 :stub-columns: 0
118 :widths: 3 1 16
119
120 * .. _`CEC-MODE-NO-FOLLOWER`:
121
122 - ``CEC_MODE_NO_FOLLOWER``
123 - 0x00
124 - This is not a follower (the default when the device is opened).
125 * .. _`CEC-MODE-FOLLOWER`:
126
127 - ``CEC_MODE_FOLLOWER``
128 - 0x10
129 - This is a follower and it will receive CEC messages unless there
130 is an exclusive follower. You cannot become a follower if
131 :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 - 0x20
137 - This is an exclusive follower and only this file descriptor will
138 receive CEC messages for processing. If someone else is already
139 the exclusive follower then an attempt to become one will return
140 the ``EBUSY`` error code. You cannot become a follower if
141 :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 - 0x30
147 - This is an exclusive follower and only this file descriptor will
148 receive CEC messages for processing. In addition it will put the
149 CEC device into passthrough mode, allowing the exclusive follower
150 to handle most core messages instead of relying on the CEC
151 framework for that. If someone else is already the exclusive
152 follower then an attempt to become one will return the ``EBUSY`` error
153 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 - 0xd0
160 - Put the file descriptor into pin monitoring mode. Can only be used in
161 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 the
166 ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the
167 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 - 0xe0
174 - Put the file descriptor into monitor mode. Can only be used in
175 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 CEC
178 device transmits and all messages it receives (both broadcast
179 messages and directed messages for one its logical addresses) will
180 be reported. This is very useful for debugging. This is only
181 allowed if the process has the ``CAP_NET_ADMIN`` capability. If
182 that is not set, then the ``EPERM`` error code is returned.
183 * .. _`CEC-MODE-MONITOR-ALL`:
184
185 - ``CEC_MODE_MONITOR_ALL``
186 - 0xf0
187 - Put the file descriptor into 'monitor all' mode. Can only be used
188 in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
189 the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
190 this CEC device transmits and all messages it receives, including
191 directed messages for other CEC devices, will be reported. This is
192 very useful for debugging, but not all devices support this. This
193 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 if
195 the process has the ``CAP_NET_ADMIN`` capability. If that is not
196 set, then the ``EPERM`` error code is returned.
197
198 Core message processing details:
199
200 .. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
201
202 .. _cec-core-processing:
203
204 .. flat-table:: Core Message Processing
205 :header-rows: 0
206 :stub-columns: 0
207 :widths: 1 8
208
209 * .. _`CEC-MSG-GET-CEC-VERSION`:
210
211 - ``CEC_MSG_GET_CEC_VERSION``
212 - The core will return the CEC version that was set with
213 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
214 except when in passthrough mode. In passthrough mode the core
215 does nothing and this message has to be handled by a follower
216 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 with
221 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
222 except when in passthrough mode. In passthrough mode the core
223 does nothing and this message has to be handled by a follower
224 instead.
225 * .. _`CEC-MSG-ABORT`:
226
227 - ``CEC_MSG_ABORT``
228 - The core will return a Feature Abort message with reason
229 'Feature Refused' as per the specification, except when in
230 passthrough mode. In passthrough mode the core does nothing
231 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 when
236 in 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-OSD-NAME`:
239
240 - ``CEC_MSG_GIVE_OSD_NAME``
241 - The core will report the current OSD name that was set with
242 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
243 except when in passthrough mode. In passthrough mode the core
244 does nothing and this message has to be handled by a follower
245 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 with
251 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
252 except when in passthrough mode. In passthrough mode the core
253 does nothing (for any CEC version) and this message has to be handled
254 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 if
259 :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
260 is set, then generate a remote control key
261 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 if
266 :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
267 is set, then generate a remote control key
268 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 address
273 and then just pass the message on to the follower(s).
274
275
276 Return Value
277 ============
278
279 On success 0 is returned, on error -1 and the ``errno`` variable is set
280 appropriately. The generic error codes are described at the
281 :ref:`Generic Error Codes <gen-errors>` chapter.
282
283 The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following
284 error codes:
285
286 EINVAL
287 The requested mode is invalid.
288
289 EPERM
290 Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN``
291 capability.
292
293 EBUSY
294 Someone else is already an exclusive follower or initiator.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.