tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
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/media/uapi/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>`,i
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 without having root permissions
298
299EBUSY
300 Someone else is already an exclusive follower or initiator.