tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1.. -*- coding: utf-8; mode: rst -*-
2
3.. _CEC_MODE:
4.. _CEC_G_MODE:
5.. _CEC_S_MODE:
6
7********************************
8ioctls CEC_G_MODE and CEC_S_MODE
9********************************
10
11CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
12
13Synopsis
14========
15
16.. cpp:function:: int ioctl( int fd, int request, __u32 *argp )
17
18Arguments
19=========
20
21``fd``
22 File descriptor returned by :ref:`open() <cec-func-open>`.
23
24``request``
25 CEC_G_MODE, CEC_S_MODE
26
27``argp``
28
29
30Description
31===========
32
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.
35
36By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
37applications from stepping on each others toes it must be possible to
38obtain exclusive access to the CEC adapter. This ioctl sets the
39filehandle to initiator and/or follower mode which can be exclusive
40depending on the chosen mode. The initiator is the filehandle that is
41used to initiate messages, i.e. it commands other CEC devices. The
42follower is the filehandle that receives messages sent to the CEC
43adapter and processes them. The same filehandle can be both initiator
44and follower, or this role can be taken by two different filehandles.
45
46When a CEC message is received, then the CEC framework will decide how
47it will be processed. If the message is a reply to an earlier
48transmitted message, then the reply is sent back to the filehandle that
49is waiting for it. In addition the CEC framework will process it.
50
51If the message is not a reply, then the CEC framework will process it
52first. If there is no follower, then the message is just discarded and a
53feature abort is sent back to the initiator if the framework couldn't
54process it. If there is a follower, then the message is passed on to the
55follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
56the new message. The framework expects the follower to make the right
57decisions.
58
59The CEC framework will process core messages unless requested otherwise
60by the follower. The follower can enable the passthrough mode. In that
61case, the CEC framework will pass on most core messages without
62processing them and the follower will have to implement those messages.
63There are some messages that the core will always process, regardless of
64the passthrough mode. See :ref:`cec-core-processing` for details.
65
66If there is no initiator, then any CEC filehandle can use
67:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
68initiator then only that initiator can call
69:ref:`CEC_TRANSMIT`. The follower can of course
70always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
71
72Available initiator modes are:
73
74
75.. _cec-mode-initiator_e:
76
77.. flat-table:: Initiator Modes
78 :header-rows: 0
79 :stub-columns: 0
80 :widths: 3 1 16
81
82
83 - .. _`CEC-MODE-NO-INITIATOR`:
84
85 - ``CEC_MODE_NO_INITIATOR``
86
87 - 0x0
88
89 - This is not an initiator, i.e. it cannot transmit CEC messages or
90 make any other changes to the CEC adapter.
91
92 - .. _`CEC-MODE-INITIATOR`:
93
94 - ``CEC_MODE_INITIATOR``
95
96 - 0x1
97
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
102 - .. _`CEC-MODE-EXCL-INITIATOR`:
103
104 - ``CEC_MODE_EXCL_INITIATOR``
105
106 - 0x2
107
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
112 error.
113
114
115Available follower modes are:
116
117
118.. _cec-mode-follower_e:
119
120.. flat-table:: Follower Modes
121 :header-rows: 0
122 :stub-columns: 0
123 :widths: 3 1 16
124
125
126 - .. _`CEC-MODE-NO-FOLLOWER`:
127
128 - ``CEC_MODE_NO_FOLLOWER``
129
130 - 0x00
131
132 - This is not a follower (the default when the device is opened).
133
134 - .. _`CEC-MODE-FOLLOWER`:
135
136 - ``CEC_MODE_FOLLOWER``
137
138 - 0x10
139
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.
144
145 - .. _`CEC-MODE-EXCL-FOLLOWER`:
146
147 - ``CEC_MODE_EXCL_FOLLOWER``
148
149 - 0x20
150
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.
157
158 - .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
159
160 - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
161
162 - 0x30
163
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.
173
174 - .. _`CEC-MODE-MONITOR`:
175
176 - ``CEC_MODE_MONITOR``
177
178 - 0xe0
179
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.
188
189 - .. _`CEC-MODE-MONITOR-ALL`:
190
191 - ``CEC_MODE_MONITOR_ALL``
192
193 - 0xf0
194
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.
205
206
207Core message processing details:
208
209
210.. _cec-core-processing:
211
212.. flat-table:: Core Message Processing
213 :header-rows: 0
214 :stub-columns: 0
215 :widths: 1 8
216
217
218 - .. _`CEC-MSG-GET-CEC-VERSION`:
219
220 - ``CEC_MSG_GET_CEC_VERSION``
221
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>`.
225
226 - .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
227
228 - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
229
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>`.
233
234 - .. _`CEC-MSG-ABORT`:
235
236 - ``CEC_MSG_ABORT``
237
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.
241
242 - .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
243
244 - ``CEC_MSG_GIVE_PHYSICAL_ADDR``
245
246 - When in passthrough mode this message has to be handled by
247 userspace, otherwise the core will report the current physical
248 address.
249
250 - .. _`CEC-MSG-GIVE-OSD-NAME`:
251
252 - ``CEC_MSG_GIVE_OSD_NAME``
253
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>`.
257
258 - .. _`CEC-MSG-GIVE-FEATURES`:
259
260 - ``CEC_MSG_GIVE_FEATURES``
261
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.
266
267 - .. _`CEC-MSG-USER-CONTROL-PRESSED`:
268
269 - ``CEC_MSG_USER_CONTROL_PRESSED``
270
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.
273
274 - .. _`CEC-MSG-USER-CONTROL-RELEASED`:
275
276 - ``CEC_MSG_USER_CONTROL_RELEASED``
277
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.
280
281 - .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
282
283 - ``CEC_MSG_REPORT_PHYSICAL_ADDR``
284
285 - The CEC framework will make note of the reported physical address
286 and then just pass the message on to userspace.
287
288
289
290Return Value
291============
292
293On success 0 is returned, on error -1 and the ``errno`` variable is set
294appropriately. The generic error codes are described at the
295:ref:`Generic Error Codes <gen-errors>` chapter.