summaryrefslogtreecommitdiff
path: root/Documentation/DocBook/media/v4l/cec-ioc-adap-g-log-addrs.xml
blob: 302b8294f7fc73fd371e604d2180bc7450e52083 (plain)
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
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
<refentry id="cec-ioc-adap-g-log-addrs">
  <refmeta>
    <refentrytitle>ioctl CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</refentrytitle>
    &manvol;
  </refmeta>

  <refnamediv>
    <refname>CEC_ADAP_G_LOG_ADDRS</refname>
    <refname>CEC_ADAP_S_LOG_ADDRS</refname>
    <refpurpose>Get or set the logical addresses</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <funcsynopsis>
      <funcprototype>
	<funcdef>int <function>ioctl</function></funcdef>
	<paramdef>int <parameter>fd</parameter></paramdef>
	<paramdef>int <parameter>request</parameter></paramdef>
	<paramdef>struct cec_log_addrs *<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_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS</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>To query the current CEC logical addresses, applications call the
<constant>CEC_ADAP_G_LOG_ADDRS</constant> ioctl with a pointer to a
<structname>cec_log_addrs</structname> structure where the drivers stores the
logical addresses.</para>

    <para>To set new logical addresses, applications fill in struct <structname>cec_log_addrs</structname>
and call the <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl with a pointer to this struct.
The <constant>CEC_ADAP_S_LOG_ADDRS</constant> ioctl is only available if
<constant>CEC_CAP_LOG_ADDRS</constant> is set (&ENOTTY; is returned otherwise). This ioctl will block until all
requested logical addresses have been claimed. <constant>CEC_ADAP_S_LOG_ADDRS</constant>
can only be called by a file handle in initiator mode (see &CEC-S-MODE;).</para>

    <table pgwide="1" frame="none" id="cec-log-addrs">
      <title>struct <structname>cec_log_addrs</structname></title>
      <tgroup cols="3">
	&cs-str;
	<tbody valign="top">
	  <row>
	    <entry>__u8</entry>
	    <entry><structfield>log_addr</structfield>[CEC_MAX_LOG_ADDRS]</entry>
	    <entry>The actual logical addresses that were claimed. This is set by the
	    driver. If no logical address could be claimed, then it is set to
	    <constant>CEC_LOG_ADDR_INVALID</constant>. If this adapter is Unregistered,
	    then <structfield>log_addr[0]</structfield> is set to 0xf and all others to
	    <constant>CEC_LOG_ADDR_INVALID</constant>.</entry>
	  </row>
	  <row>
	    <entry>__u16</entry>
	    <entry><structfield>log_addr_mask</structfield></entry>
	    <entry>The bitmask of all logical addresses this adapter has claimed.
	    If this adapter is Unregistered then <structfield>log_addr_mask</structfield>
	    sets bit 15 and clears all other bits. If this adapter is not configured at all, then
	    <structfield>log_addr_mask</structfield> is set to 0. Set by the driver.</entry>
	  </row>
	  <row>
	    <entry>__u8</entry>
	    <entry><structfield>cec_version</structfield></entry>
	    <entry>The CEC version that this adapter shall use. See
	    <xref linkend="cec-versions" />.
	    Used to implement the <constant>CEC_MSG_CEC_VERSION</constant> and
	    <constant>CEC_MSG_REPORT_FEATURES</constant> messages. Note that
	    <constant>CEC_OP_CEC_VERSION_1_3A</constant> is not allowed
	    by the CEC framework.
	    </entry>
	  </row>
	  <row>
	    <entry>__u8</entry>
	    <entry><structfield>num_log_addrs</structfield></entry>
	    <entry>Number of logical addresses to set up. Must be &le;
	    <structfield>available_log_addrs</structfield> as returned by
	    &CEC-ADAP-G-CAPS;. All arrays in this structure are only filled up to
	    index <structfield>available_log_addrs</structfield>-1. The remaining
	    array elements will be ignored. Note that the CEC 2.0 standard allows
	    for a maximum of 2 logical addresses, although some hardware has support
	    for more. <constant>CEC_MAX_LOG_ADDRS</constant> is 4. The driver will
	    return the actual number of logical addresses it could claim, which may
	    be less than what was requested. If this field is set to 0, then the
	    CEC adapter shall clear all claimed logical addresses and all other
	    fields will be ignored.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>vendor_id</structfield></entry>
	    <entry>The vendor ID is a 24-bit number that identifies the specific
	    vendor or entity. Based on this ID vendor specific commands may be
	    defined. If you do not want a vendor ID then set it to
	    <constant>CEC_VENDOR_ID_NONE</constant>.</entry>
	  </row>
	  <row>
	    <entry>__u32</entry>
	    <entry><structfield>flags</structfield></entry>
	    <entry>Flags. No flags are defined yet, so set this to 0.</entry>
	  </row>
	  <row>
	    <entry>char</entry>
	    <entry><structfield>osd_name</structfield>[15]</entry>
	    <entry>The On-Screen Display name as is returned by the
	    <constant>CEC_MSG_SET_OSD_NAME</constant> message.</entry>
	  </row>
	  <row>
	    <entry>__u8</entry>
	    <entry><structfield>primary_device_type</structfield>[CEC_MAX_LOG_ADDRS]</entry>
	    <entry>Primary device type for each logical address. See
	    <xref linkend="cec-prim-dev-types" /> for possible types.</entry>
	  </row>
	  <row>
	    <entry>__u8</entry>
	    <entry><structfield>log_addr_type</structfield>[CEC_MAX_LOG_ADDRS]</entry>
	    <entry>Logical address types. See <xref linkend="cec-log-addr-types" /> for
	    possible types. The driver will update this with the actual logical address
	    type that it claimed (e.g. it may have to fallback to
	    <constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant>).</entry>
	  </row>
	  <row>
	    <entry>__u8</entry>
	    <entry><structfield>all_device_types</structfield>[CEC_MAX_LOG_ADDRS]</entry>
	    <entry>CEC 2.0 specific: all device types. See <xref linkend="cec-all-dev-types-flags" />.
	    Used to implement the <constant>CEC_MSG_REPORT_FEATURES</constant> message.
	    This field is ignored if <structfield>cec_version</structfield> &lt;
	    <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry>
	  </row>
	  <row>
	    <entry>__u8</entry>
	    <entry><structfield>features</structfield>[CEC_MAX_LOG_ADDRS][12]</entry>
	    <entry>Features for each logical address. Used to implement the
	    <constant>CEC_MSG_REPORT_FEATURES</constant> message. The 12 bytes include
	    both the RC Profile and the Device Features.
	    This field is ignored if <structfield>cec_version</structfield> &lt;
	    <constant>CEC_OP_CEC_VERSION_2_0</constant>.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="cec-versions">
      <title>CEC Versions</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>CEC_OP_CEC_VERSION_1_3A</constant></entry>
	    <entry>4</entry>
	    <entry>CEC version according to the HDMI 1.3a standard.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_CEC_VERSION_1_4B</constant></entry>
	    <entry>5</entry>
	    <entry>CEC version according to the HDMI 1.4b standard.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_CEC_VERSION_2_0</constant></entry>
	    <entry>6</entry>
	    <entry>CEC version according to the HDMI 2.0 standard.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="cec-prim-dev-types">
      <title>CEC Primary Device Types</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>CEC_OP_PRIM_DEVTYPE_TV</constant></entry>
	    <entry>0</entry>
	    <entry>Use for a TV.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_PRIM_DEVTYPE_RECORD</constant></entry>
	    <entry>1</entry>
	    <entry>Use for a recording device.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_PRIM_DEVTYPE_TUNER</constant></entry>
	    <entry>3</entry>
	    <entry>Use for a device with a tuner.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_PRIM_DEVTYPE_PLAYBACK</constant></entry>
	    <entry>4</entry>
	    <entry>Use for a playback device.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM</constant></entry>
	    <entry>5</entry>
	    <entry>Use for an audio system (e.g. an audio/video receiver).</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_PRIM_DEVTYPE_SWITCH</constant></entry>
	    <entry>6</entry>
	    <entry>Use for a CEC switch.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_PRIM_DEVTYPE_VIDEOPROC</constant></entry>
	    <entry>7</entry>
	    <entry>Use for a video processor device.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="cec-log-addr-types">
      <title>CEC Logical Address Types</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>CEC_LOG_ADDR_TYPE_TV</constant></entry>
	    <entry>0</entry>
	    <entry>Use for a TV.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_LOG_ADDR_TYPE_RECORD</constant></entry>
	    <entry>1</entry>
	    <entry>Use for a recording device.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_LOG_ADDR_TYPE_TUNER</constant></entry>
	    <entry>2</entry>
	    <entry>Use for a tuner device.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_LOG_ADDR_TYPE_PLAYBACK</constant></entry>
	    <entry>3</entry>
	    <entry>Use for a playback device.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_LOG_ADDR_TYPE_AUDIOSYSTEM</constant></entry>
	    <entry>4</entry>
	    <entry>Use for an audio system device.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_LOG_ADDR_TYPE_SPECIFIC</constant></entry>
	    <entry>5</entry>
	    <entry>Use for a second TV or for a video processor device.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_LOG_ADDR_TYPE_UNREGISTERED</constant></entry>
	    <entry>6</entry>
	    <entry>Use this if you just want to remain unregistered.
	    Used for pure CEC switches or CDC-only devices (CDC:
	    Capability Discovery and Control).</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>

    <table pgwide="1" frame="none" id="cec-all-dev-types-flags">
      <title>CEC All Device Types Flags</title>
      <tgroup cols="3">
	&cs-def;
	<tbody valign="top">
	  <row>
	    <entry><constant>CEC_OP_ALL_DEVTYPE_TV</constant></entry>
	    <entry>0x80</entry>
	    <entry>This supports the TV type.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_ALL_DEVTYPE_RECORD</constant></entry>
	    <entry>0x40</entry>
	    <entry>This supports the Recording type.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_ALL_DEVTYPE_TUNER</constant></entry>
	    <entry>0x20</entry>
	    <entry>This supports the Tuner type.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_ALL_DEVTYPE_PLAYBACK</constant></entry>
	    <entry>0x10</entry>
	    <entry>This supports the Playback type.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM</constant></entry>
	    <entry>0x08</entry>
	    <entry>This supports the Audio System type.</entry>
	  </row>
	  <row>
	    <entry><constant>CEC_OP_ALL_DEVTYPE_SWITCH</constant></entry>
	    <entry>0x04</entry>
	    <entry>This supports the CEC Switch or Video Processing type.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>

  <refsect1>
    &return-value;
  </refsect1>
</refentry>