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