1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
|
<refentry id="cec-ioc-g-mode">
<refmeta>
<refentrytitle>ioctl CEC_G_MODE, CEC_S_MODE</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>CEC_G_MODE</refname>
<refname>CEC_S_MODE</refname>
<refpurpose>Get or set exclusive use of the CEC adapter</refpurpose>
</refnamediv>
<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>ioctl</function></funcdef>
<paramdef>int <parameter>fd</parameter></paramdef>
<paramdef>int <parameter>request</parameter></paramdef>
<paramdef>__u32 *<parameter>argp</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>fd</parameter></term>
<listitem>
<para>File descriptor returned by
<link linkend='cec-func-open'><function>open()</function></link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>CEC_G_MODE, CEC_S_MODE</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>argp</parameter></term>
<listitem>
<para></para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Note: this documents the proposed CEC API. This API is not yet finalized and
is currently only available as a staging kernel module.
</para>
<para>By default any filehandle can use &CEC-TRANSMIT; and &CEC-RECEIVE;, but
in order to prevent applications from stepping on each others toes it must be possible
to obtain exclusive access to the CEC adapter. This ioctl sets the filehandle
to initiator and/or follower mode which can be exclusive depending on the chosen
mode. The initiator is the filehandle that is used
to initiate messages, i.e. it commands other CEC devices. The follower is the filehandle
that receives messages sent to the CEC adapter and processes them. The same filehandle
can be both initiator and follower, or this role can be taken by two different
filehandles.</para>
<para>When a CEC message is received, then the CEC framework will decide how
it will be processed. If the message is a reply to an earlier transmitted message,
then the reply is sent back to the filehandle that is waiting for it. In addition
the CEC framework will process it.</para>
<para>If the message is not a reply, then the CEC framework will process it
first. If there is no follower, then the message is just discarded and a feature
abort is sent back to the initiator if the framework couldn't process it. If there
is a follower, then the message is passed on to the follower who will use
&CEC-RECEIVE; to dequeue the new message. The framework expects the follower to
make the right decisions.</para>
<para>The CEC framework will process core messages unless requested otherwise
by the follower. The follower can enable the passthrough mode. In that case, the
CEC framework will pass on most core messages without processing them and
the follower will have to implement those messages. There are some messages
that the core will always process, regardless of the passthrough mode. See
<xref linkend="cec-core-processing" /> for details.</para>
<para>If there is no initiator, then any CEC filehandle can use &CEC-TRANSMIT;.
If there is an exclusive initiator then only that initiator can call &CEC-TRANSMIT;.
The follower can of course always call &CEC-TRANSMIT;.</para>
<para>Available initiator modes are:</para>
<table pgwide="1" frame="none" id="cec-mode-initiator">
<title>Initiator Modes</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>CEC_MODE_NO_INITIATOR</constant></entry>
<entry>0x0</entry>
<entry>This is not an initiator, i.e. it cannot transmit CEC messages
or make any other changes to the CEC adapter.</entry>
</row>
<row>
<entry><constant>CEC_MODE_INITIATOR</constant></entry>
<entry>0x1</entry>
<entry>This is an initiator (the default when the device is opened) and it
can transmit CEC messages and make changes to the CEC adapter, unless there
is an exclusive initiator.</entry>
</row>
<row>
<entry><constant>CEC_MODE_EXCL_INITIATOR</constant></entry>
<entry>0x2</entry>
<entry>This is an exclusive initiator and this file descriptor is the only one
that can transmit CEC messages and make changes to the CEC adapter. If someone
else is already the exclusive initiator then an attempt to become one will return
the &EBUSY; error.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Available follower modes are:</para>
<table pgwide="1" frame="none" id="cec-mode-follower">
<title>Follower Modes</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>CEC_MODE_NO_FOLLOWER</constant></entry>
<entry>0x00</entry>
<entry>This is not a follower (the default when the device is opened).</entry>
</row>
<row>
<entry><constant>CEC_MODE_FOLLOWER</constant></entry>
<entry>0x10</entry>
<entry>This is a follower and it will receive CEC messages unless there is
an exclusive follower. You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant>
is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified,
&EINVAL; is returned in that case.</entry>
</row>
<row>
<entry><constant>CEC_MODE_EXCL_FOLLOWER</constant></entry>
<entry>0x20</entry>
<entry>This is an exclusive follower and only this file descriptor will receive
CEC messages for processing. If someone else is already the exclusive follower
then an attempt to become one will return the &EBUSY; error. You cannot become
a follower if <constant>CEC_CAP_TRANSMIT</constant> is not set or if
<constant>CEC_MODE_NO_INITIATOR</constant> was specified, &EINVAL; is returned
in that case.</entry>
</row>
<row>
<entry><constant>CEC_MODE_EXCL_FOLLOWER_PASSTHRU</constant></entry>
<entry>0x30</entry>
<entry>This is an exclusive follower and only this file descriptor will receive
CEC messages for processing. In addition it will put the CEC device into
passthrough mode, allowing the exclusive follower to handle most core messages
instead of relying on the CEC framework for that. If someone else is already the
exclusive follower then an attempt to become one will return the &EBUSY; error.
You cannot become a follower if <constant>CEC_CAP_TRANSMIT</constant>
is not set or if <constant>CEC_MODE_NO_INITIATOR</constant> was specified,
&EINVAL; is returned in that case.</entry>
</row>
<row>
<entry><constant>CEC_MODE_MONITOR</constant></entry>
<entry>0xe0</entry>
<entry>Put the file descriptor into monitor mode. Can only be used in combination
with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be
returned. In monitor mode all messages this CEC device transmits and all messages
it receives (both broadcast messages and directed messages for one its logical
addresses) will be reported. This is very useful for debugging. This is only
allowed if the process has the <constant>CAP_NET_ADMIN</constant>
capability. If that is not set, then &EPERM; is returned.</entry>
</row>
<row>
<entry><constant>CEC_MODE_MONITOR_ALL</constant></entry>
<entry>0xf0</entry>
<entry>Put the file descriptor into 'monitor all' mode. Can only be used in combination
with <constant>CEC_MODE_NO_INITIATOR</constant>, otherwise &EINVAL; will be
returned. In 'monitor all' mode all messages this CEC device transmits and all messages
it receives, including directed messages for other CEC devices will be reported. This
is very useful for debugging, but not all devices support this. This mode requires that
the <constant>CEC_CAP_MONITOR_ALL</constant> capability is set, otherwise &EINVAL; is
returned. This is only allowed if the process has the <constant>CAP_NET_ADMIN</constant>
capability. If that is not set, then &EPERM; is returned.</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Core message processing details:</para>
<table pgwide="1" frame="none" id="cec-core-processing">
<title>Core Message Processing</title>
<tgroup cols="2">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>CEC_MSG_GET_CEC_VERSION</constant></entry>
<entry>When in passthrough mode this message has to be handled by userspace,
otherwise the core will return the CEC version that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry>
</row>
<row>
<entry><constant>CEC_MSG_GIVE_DEVICE_VENDOR_ID</constant></entry>
<entry>When in passthrough mode this message has to be handled by userspace,
otherwise the core will return the vendor ID that was set with &CEC-ADAP-S-LOG-ADDRS;.</entry>
</row>
<row>
<entry><constant>CEC_MSG_ABORT</constant></entry>
<entry>When in passthrough mode this message has to be handled by userspace,
otherwise the core will return a feature refused message as per the specification.</entry>
</row>
<row>
<entry><constant>CEC_MSG_GIVE_PHYSICAL_ADDR</constant></entry>
<entry>When in passthrough mode this message has to be handled by userspace,
otherwise the core will report the current physical address.</entry>
</row>
<row>
<entry><constant>CEC_MSG_GIVE_OSD_NAME</constant></entry>
<entry>When in passthrough mode this message has to be handled by userspace,
otherwise the core will report the current OSD name as was set with
&CEC-ADAP-S-LOG-ADDRS;.</entry>
</row>
<row>
<entry><constant>CEC_MSG_GIVE_FEATURES</constant></entry>
<entry>When in passthrough mode this message has to be handled by userspace,
otherwise the core will report the current features as was set with
&CEC-ADAP-S-LOG-ADDRS; or the message is ignore if the CEC version was
older than 2.0.</entry>
</row>
<row>
<entry><constant>CEC_MSG_USER_CONTROL_PRESSED</constant></entry>
<entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control
key press. This message is always passed on to userspace.</entry>
</row>
<row>
<entry><constant>CEC_MSG_USER_CONTROL_RELEASED</constant></entry>
<entry>If <constant>CEC_CAP_RC</constant> is set, then generate a remote control
key release. This message is always passed on to userspace.</entry>
</row>
<row>
<entry><constant>CEC_MSG_REPORT_PHYSICAL_ADDR</constant></entry>
<entry>The CEC framework will make note of the reported physical address
and then just pass the message on to userspace.</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;
</refsect1>
</refentry>
|
