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********************************
9ioctls CEC_G_MODE and CEC_S_MODE
10********************************
11
12CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter
13
14Synopsis
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
25Arguments
26=========
27
28``fd``
29    File descriptor returned by :c:func:`open()`.
30
31``argp``
32    Pointer to CEC mode.
33
34Description
35===========
36
37By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
38applications from stepping on each others toes it must be possible to
39obtain exclusive access to the CEC adapter. This ioctl sets the
40filehandle to initiator and/or follower mode which can be exclusive
41depending on the chosen mode. The initiator is the filehandle that is
42used to initiate messages, i.e. it commands other CEC devices. The
43follower is the filehandle that receives messages sent to the CEC
44adapter and processes them. The same filehandle can be both initiator
45and follower, or this role can be taken by two different filehandles.
46
47When a CEC message is received, then the CEC framework will decide how
48it will be processed. If the message is a reply to an earlier
49transmitted message, then the reply is sent back to the filehandle that
50is waiting for it. In addition the CEC framework will process it.
51
52If the message is not a reply, then the CEC framework will process it
53first. If there is no follower, then the message is just discarded and a
54feature abort is sent back to the initiator if the framework couldn't
55process it. If there is a follower, then the message is passed on to the
56follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
57the new message. The framework expects the follower to make the right
58decisions.
59
60The CEC framework will process core messages unless requested otherwise
61by the follower. The follower can enable the passthrough mode. In that
62case, the CEC framework will pass on most core messages without
63processing them and the follower will have to implement those messages.
64There are some messages that the core will always process, regardless of
65the passthrough mode. See :ref:`cec-core-processing` for details.
66
67If there is no initiator, then any CEC filehandle can use
68:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
69initiator then only that initiator can call
70:ref:`CEC_TRANSMIT`. The follower can of course
71always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.
72
73Available initiator modes are:
74
75.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{11.0cm}|
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
107Available follower modes are:
108
109.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{10.0cm}|
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
198Core 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
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, but the process does have the ``CAP_NET_ADMIN``
291    capability.
292
293EBUSY
294    Someone else is already an exclusive follower or initiator.
295