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.. c:function:: int ioctl( int fd, CEC_G_MODE, __u32 *argp )
17 :name: CEC_G_MODE
18
19.. c:function:: int ioctl( int fd, CEC_S_MODE, __u32 *argp )
20 :name: CEC_S_MODE
21
22Arguments
23=========
24
25``fd``
26 File descriptor returned by :c:func:`open() <cec-open>`.
27
28``argp``
29 Pointer to CEC mode.
30
31Description
32===========
33
34By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
35applications from stepping on each others toes it must be possible to
36obtain exclusive access to the CEC adapter. This ioctl sets the
37filehandle to initiator and/or follower mode which can be exclusive
38depending on the chosen mode. The initiator is the filehandle that is
39used to initiate messages, i.e. it commands other CEC devices. The
40follower is the filehandle that receives messages sent to the CEC
41adapter and processes them. The same filehandle can be both initiator
42and follower, or this role can be taken by two different filehandles.
43
44When a CEC message is received, then the CEC framework will decide how
45it will be processed. If the message is a reply to an earlier
46transmitted message, then the reply is sent back to the filehandle that
47is waiting for it. In addition the CEC framework will process it.
48
49If the message is not a reply, then the CEC framework will process it
50first. If there is no follower, then the message is just discarded and a
51feature abort is sent back to the initiator if the framework couldn't
52process it. If there is a follower, then the message is passed on to the
53follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
54the new message. The framework expects the follower to make the right
55decisions.
56
57The CEC framework will process core messages unless requested otherwise
58by the follower. The follower can enable the passthrough mode. In that
59case, the CEC framework will pass on most core messages without
60processing them and the follower will have to implement those messages.
61There are some messages that the core will always process, regardless of
62the passthrough mode. See :ref:`cec-core-processing` for details.
63
64If there is no initiator, then any CEC filehandle can use
65:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
66initiator then only that initiator can call
67:ref:`CEC_TRANSMIT`. The follower can of course
68always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
69
70Available initiator modes are:
71
72.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
73
74.. _cec-mode-initiator_e:
75
76.. flat-table:: Initiator Modes
77 :header-rows: 0
78 :stub-columns: 0
79 :widths: 3 1 16
80
81 * .. _`CEC-MODE-NO-INITIATOR`:
82
83 - ``CEC_MODE_NO_INITIATOR``
84 - 0x0
85 - This is not an initiator, i.e. it cannot transmit CEC messages or
86 make any other changes to the CEC adapter.
87 * .. _`CEC-MODE-INITIATOR`:
88
89 - ``CEC_MODE_INITIATOR``
90 - 0x1
91 - This is an initiator (the default when the device is opened) and
92 it can transmit CEC messages and make changes to the CEC adapter,
93 unless there is an exclusive initiator.
94 * .. _`CEC-MODE-EXCL-INITIATOR`:
95
96 - ``CEC_MODE_EXCL_INITIATOR``
97 - 0x2
98 - This is an exclusive initiator and this file descriptor is the
99 only one that can transmit CEC messages and make changes to the
100 CEC adapter. If someone else is already the exclusive initiator
101 then an attempt to become one will return the ``EBUSY`` error code
102 error.
103
104
105Available follower modes are:
106
107.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}|
108
109.. _cec-mode-follower_e:
110
111.. cssclass:: longtable
112
113.. flat-table:: Follower Modes
114 :header-rows: 0
115 :stub-columns: 0
116 :widths: 3 1 16
117
118 * .. _`CEC-MODE-NO-FOLLOWER`:
119
120 - ``CEC_MODE_NO_FOLLOWER``
121 - 0x00
122 - This is not a follower (the default when the device is opened).
123 * .. _`CEC-MODE-FOLLOWER`:
124
125 - ``CEC_MODE_FOLLOWER``
126 - 0x10
127 - This is a follower and it will receive CEC messages unless there
128 is an exclusive follower. You cannot become a follower if
129 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
130 was specified, the ``EINVAL`` error code is returned in that case.
131 * .. _`CEC-MODE-EXCL-FOLLOWER`:
132
133 - ``CEC_MODE_EXCL_FOLLOWER``
134 - 0x20
135 - This is an exclusive follower and only this file descriptor will
136 receive CEC messages for processing. If someone else is already
137 the exclusive follower then an attempt to become one will return
138 the ``EBUSY`` error code. You cannot become a follower if
139 :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
140 was specified, the ``EINVAL`` error code is returned in that case.
141 * .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:
142
143 - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
144 - 0x30
145 - This is an exclusive follower and only this file descriptor will
146 receive CEC messages for processing. In addition it will put the
147 CEC device into passthrough mode, allowing the exclusive follower
148 to handle most core messages instead of relying on the CEC
149 framework for that. If someone else is already the exclusive
150 follower then an attempt to become one will return the ``EBUSY`` error
151 code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
152 is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
153 the ``EINVAL`` error code is returned in that case.
154 * .. _`CEC-MODE-MONITOR-PIN`:
155
156 - ``CEC_MODE_MONITOR_PIN``
157 - 0xd0
158 - Put the file descriptor into pin monitoring mode. Can only be used in
159 combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
160 otherwise the ``EINVAL`` error code will be returned.
161 This mode requires that the :ref:`CEC_CAP_MONITOR_PIN <CEC-CAP-MONITOR-PIN>`
162 capability is set, otherwise the ``EINVAL`` error code is returned.
163 While in pin monitoring mode this file descriptor can receive the
164 ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the
165 low-level CEC pin transitions. This is very useful for debugging.
166 This mode is only allowed if the process has the ``CAP_NET_ADMIN``
167 capability. If that is not set, then the ``EPERM`` error code is returned.
168 * .. _`CEC-MODE-MONITOR`:
169
170 - ``CEC_MODE_MONITOR``
171 - 0xe0
172 - Put the file descriptor into monitor mode. Can only be used in
173 combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,i
174 otherwise the ``EINVAL`` error code will be returned.
175 In monitor mode all messages this CEC
176 device transmits and all messages it receives (both broadcast
177 messages and directed messages for one its logical addresses) will
178 be reported. This is very useful for debugging. This is only
179 allowed if the process has the ``CAP_NET_ADMIN`` capability. If
180 that is not set, then the ``EPERM`` error code is returned.
181 * .. _`CEC-MODE-MONITOR-ALL`:
182
183 - ``CEC_MODE_MONITOR_ALL``
184 - 0xf0
185 - Put the file descriptor into 'monitor all' mode. Can only be used
186 in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
187 the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
188 this CEC device transmits and all messages it receives, including
189 directed messages for other CEC devices will be reported. This is
190 very useful for debugging, but not all devices support this. This
191 mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
192 otherwise the ``EINVAL`` error code is returned. This is only allowed if
193 the process has the ``CAP_NET_ADMIN`` capability. If that is not
194 set, then the ``EPERM`` error code is returned.
195
196
197Core message processing details:
198
199.. tabularcolumns:: |p{6.6cm}|p{10.9cm}|
200
201.. _cec-core-processing:
202
203.. flat-table:: Core Message Processing
204 :header-rows: 0
205 :stub-columns: 0
206 :widths: 1 8
207
208 * .. _`CEC-MSG-GET-CEC-VERSION`:
209
210 - ``CEC_MSG_GET_CEC_VERSION``
211 - The core will return the CEC version that was set with
212 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
213 except when in passthrough mode. In passthrough mode the core
214 does nothing and this message has to be handled by a follower
215 instead.
216 * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:
217
218 - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
219 - The core will return the vendor ID that was set with
220 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
221 except when in passthrough mode. In passthrough mode the core
222 does nothing and this message has to be handled by a follower
223 instead.
224 * .. _`CEC-MSG-ABORT`:
225
226 - ``CEC_MSG_ABORT``
227 - The core will return a Feature Abort message with reason
228 'Feature Refused' as per the specification, except when in
229 passthrough mode. In passthrough mode the core does nothing
230 and this message has to be handled by a follower instead.
231 * .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:
232
233 - ``CEC_MSG_GIVE_PHYSICAL_ADDR``
234 - The core will report the current physical address, except when
235 in passthrough mode. In passthrough mode the core does nothing
236 and this message has to be handled by a follower instead.
237 * .. _`CEC-MSG-GIVE-OSD-NAME`:
238
239 - ``CEC_MSG_GIVE_OSD_NAME``
240 - The core will report the current OSD name that was set with
241 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
242 except when in passthrough mode. In passthrough mode the core
243 does nothing and this message has to be handled by a follower
244 instead.
245 * .. _`CEC-MSG-GIVE-FEATURES`:
246
247 - ``CEC_MSG_GIVE_FEATURES``
248 - The core will do nothing if the CEC version is older than 2.0,
249 otherwise it will report the current features that were set with
250 :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
251 except when in passthrough mode. In passthrough mode the core
252 does nothing (for any CEC version) and this message has to be handled
253 by a follower instead.
254 * .. _`CEC-MSG-USER-CONTROL-PRESSED`:
255
256 - ``CEC_MSG_USER_CONTROL_PRESSED``
257 - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
258 :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
259 is set, then generate a remote control key
260 press. This message is always passed on to the follower(s).
261 * .. _`CEC-MSG-USER-CONTROL-RELEASED`:
262
263 - ``CEC_MSG_USER_CONTROL_RELEASED``
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 release. This message is always passed on to the follower(s).
268 * .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:
269
270 - ``CEC_MSG_REPORT_PHYSICAL_ADDR``
271 - The CEC framework will make note of the reported physical address
272 and then just pass the message on to the follower(s).
273
274
275
276Return Value
277============
278
279On success 0 is returned, on error -1 and the ``errno`` variable is set
280appropriately. The generic error codes are described at the
281:ref:`Generic Error Codes <gen-errors>` chapter.
282
283The :ref:`ioctl CEC_S_MODE <CEC_S_MODE>` can return the following
284error codes:
285
286EINVAL
287 The requested mode is invalid.
288
289EPERM
290 Monitor mode is requested without having root permissions
291
292EBUSY
293 Someone else is already an exclusive follower or initiator.