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_ADAP_LOG_ADDRS:
4.. _CEC_ADAP_G_LOG_ADDRS:
5.. _CEC_ADAP_S_LOG_ADDRS:
6
7****************************************************
8ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS
9****************************************************
10
11Name
12====
13
14CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
15
16
17Synopsis
18========
19
20.. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp )
21 :name: CEC_ADAP_G_LOG_ADDRS
22
23.. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp )
24 :name: CEC_ADAP_S_LOG_ADDRS
25
26Arguments
27=========
28
29``fd``
30 File descriptor returned by :c:func:`open() <cec-open>`.
31
32``argp``
33 Pointer to struct :c:type:`cec_log_addrs`.
34
35Description
36===========
37
38To query the current CEC logical addresses, applications call
39:ref:`ioctl CEC_ADAP_G_LOG_ADDRS <CEC_ADAP_G_LOG_ADDRS>` with a pointer to a
40struct :c:type:`cec_log_addrs` where the driver stores the logical addresses.
41
42To set new logical addresses, applications fill in
43struct :c:type:`cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
44with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
45is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is
46returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
47can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
48the ``EBUSY`` error code will be returned.
49
50To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields
51will be ignored in that case. The adapter will go to the unconfigured state.
52
53If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`),
54then this ioctl will block until all requested logical
55addresses have been claimed. If the file descriptor is in non-blocking mode then it will
56not wait for the logical addresses to be claimed, instead it just returns 0.
57
58A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the
59logical addresses are claimed or cleared.
60
61Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when
62logical address types are already defined will return with error ``EBUSY``.
63
64.. c:type:: cec_log_addrs
65
66.. tabularcolumns:: |p{1.0cm}|p{7.5cm}|p{8.0cm}|
67
68.. cssclass:: longtable
69
70.. flat-table:: struct cec_log_addrs
71 :header-rows: 0
72 :stub-columns: 0
73 :widths: 1 1 16
74
75 * - __u8
76 - ``log_addr[CEC_MAX_LOG_ADDRS]``
77 - The actual logical addresses that were claimed. This is set by the
78 driver. If no logical address could be claimed, then it is set to
79 ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then
80 ``log_addr[0]`` is set to 0xf and all others to
81 ``CEC_LOG_ADDR_INVALID``.
82 * - __u16
83 - ``log_addr_mask``
84 - The bitmask of all logical addresses this adapter has claimed. If
85 this adapter is Unregistered then ``log_addr_mask`` sets bit 15
86 and clears all other bits. If this adapter is not configured at
87 all, then ``log_addr_mask`` is set to 0. Set by the driver.
88 * - __u8
89 - ``cec_version``
90 - The CEC version that this adapter shall use. See
91 :ref:`cec-versions`. Used to implement the
92 ``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages.
93 Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC
94 framework.
95 * - __u8
96 - ``num_log_addrs``
97 - Number of logical addresses to set up. Must be ≤
98 ``available_log_addrs`` as returned by
99 :ref:`CEC_ADAP_G_CAPS`. All arrays in
100 this structure are only filled up to index
101 ``available_log_addrs``-1. The remaining array elements will be
102 ignored. Note that the CEC 2.0 standard allows for a maximum of 2
103 logical addresses, although some hardware has support for more.
104 ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual
105 number of logical addresses it could claim, which may be less than
106 what was requested. If this field is set to 0, then the CEC
107 adapter shall clear all claimed logical addresses and all other
108 fields will be ignored.
109 * - __u32
110 - ``vendor_id``
111 - The vendor ID is a 24-bit number that identifies the specific
112 vendor or entity. Based on this ID vendor specific commands may be
113 defined. If you do not want a vendor ID then set it to
114 ``CEC_VENDOR_ID_NONE``.
115 * - __u32
116 - ``flags``
117 - Flags. See :ref:`cec-log-addrs-flags` for a list of available flags.
118 * - char
119 - ``osd_name[15]``
120 - The On-Screen Display name as is returned by the
121 ``CEC_MSG_SET_OSD_NAME`` message.
122 * - __u8
123 - ``primary_device_type[CEC_MAX_LOG_ADDRS]``
124 - Primary device type for each logical address. See
125 :ref:`cec-prim-dev-types` for possible types.
126 * - __u8
127 - ``log_addr_type[CEC_MAX_LOG_ADDRS]``
128 - Logical address types. See :ref:`cec-log-addr-types` for
129 possible types. The driver will update this with the actual
130 logical address type that it claimed (e.g. it may have to fallback
131 to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`).
132 * - __u8
133 - ``all_device_types[CEC_MAX_LOG_ADDRS]``
134 - CEC 2.0 specific: the bit mask of all device types. See
135 :ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0
136 ``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave
137 this field to 0, or fill it in according to the CEC 2.0 guidelines to
138 give the CEC framework more information about the device type, even
139 though the framework won't use it directly in the CEC message.
140 * - __u8
141 - ``features[CEC_MAX_LOG_ADDRS][12]``
142 - Features for each logical address. It is used in the CEC 2.0
143 ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the
144 RC Profile and the Device Features. For CEC 1.4 you can either leave
145 this field to all 0, or fill it in according to the CEC 2.0 guidelines to
146 give the CEC framework more information about the device type, even
147 though the framework won't use it directly in the CEC message.
148
149.. _cec-log-addrs-flags:
150
151.. flat-table:: Flags for struct cec_log_addrs
152 :header-rows: 0
153 :stub-columns: 0
154 :widths: 3 1 4
155
156 * .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`:
157
158 - ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK``
159 - 1
160 - By default if no logical address of the requested type can be claimed, then
161 it will go back to the unconfigured state. If this flag is set, then it will
162 fallback to the Unregistered logical address. Note that if the Unregistered
163 logical address was explicitly requested, then this flag has no effect.
164 * .. _`CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU`:
165
166 - ``CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU``
167 - 2
168 - By default the ``CEC_MSG_USER_CONTROL_PRESSED`` and ``CEC_MSG_USER_CONTROL_RELEASED``
169 messages are only passed on to the follower(s), if any. If this flag is set,
170 then these messages are also passed on to the remote control input subsystem
171 and will appear as keystrokes. This features needs to be enabled explicitly.
172 If CEC is used to enter e.g. passwords, then you may not want to enable this
173 to avoid trivial snooping of the keystrokes.
174 * .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`:
175
176 - `CEC_LOG_ADDRS_FL_CDC_ONLY`
177 - 4
178 - If this flag is set, then the device is CDC-Only. CDC-Only CEC devices
179 are CEC devices that can only handle CDC messages.
180
181 All other messages are ignored.
182
183
184.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
185
186.. _cec-versions:
187
188.. flat-table:: CEC Versions
189 :header-rows: 0
190 :stub-columns: 0
191 :widths: 3 1 4
192
193 * .. _`CEC-OP-CEC-VERSION-1-3A`:
194
195 - ``CEC_OP_CEC_VERSION_1_3A``
196 - 4
197 - CEC version according to the HDMI 1.3a standard.
198 * .. _`CEC-OP-CEC-VERSION-1-4B`:
199
200 - ``CEC_OP_CEC_VERSION_1_4B``
201 - 5
202 - CEC version according to the HDMI 1.4b standard.
203 * .. _`CEC-OP-CEC-VERSION-2-0`:
204
205 - ``CEC_OP_CEC_VERSION_2_0``
206 - 6
207 - CEC version according to the HDMI 2.0 standard.
208
209
210.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
211
212.. _cec-prim-dev-types:
213
214.. flat-table:: CEC Primary Device Types
215 :header-rows: 0
216 :stub-columns: 0
217 :widths: 3 1 4
218
219 * .. _`CEC-OP-PRIM-DEVTYPE-TV`:
220
221 - ``CEC_OP_PRIM_DEVTYPE_TV``
222 - 0
223 - Use for a TV.
224 * .. _`CEC-OP-PRIM-DEVTYPE-RECORD`:
225
226 - ``CEC_OP_PRIM_DEVTYPE_RECORD``
227 - 1
228 - Use for a recording device.
229 * .. _`CEC-OP-PRIM-DEVTYPE-TUNER`:
230
231 - ``CEC_OP_PRIM_DEVTYPE_TUNER``
232 - 3
233 - Use for a device with a tuner.
234 * .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`:
235
236 - ``CEC_OP_PRIM_DEVTYPE_PLAYBACK``
237 - 4
238 - Use for a playback device.
239 * .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`:
240
241 - ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM``
242 - 5
243 - Use for an audio system (e.g. an audio/video receiver).
244 * .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`:
245
246 - ``CEC_OP_PRIM_DEVTYPE_SWITCH``
247 - 6
248 - Use for a CEC switch.
249 * .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`:
250
251 - ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC``
252 - 7
253 - Use for a video processor device.
254
255
256.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
257
258.. _cec-log-addr-types:
259
260.. flat-table:: CEC Logical Address Types
261 :header-rows: 0
262 :stub-columns: 0
263 :widths: 3 1 16
264
265 * .. _`CEC-LOG-ADDR-TYPE-TV`:
266
267 - ``CEC_LOG_ADDR_TYPE_TV``
268 - 0
269 - Use for a TV.
270 * .. _`CEC-LOG-ADDR-TYPE-RECORD`:
271
272 - ``CEC_LOG_ADDR_TYPE_RECORD``
273 - 1
274 - Use for a recording device.
275 * .. _`CEC-LOG-ADDR-TYPE-TUNER`:
276
277 - ``CEC_LOG_ADDR_TYPE_TUNER``
278 - 2
279 - Use for a tuner device.
280 * .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`:
281
282 - ``CEC_LOG_ADDR_TYPE_PLAYBACK``
283 - 3
284 - Use for a playback device.
285 * .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`:
286
287 - ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM``
288 - 4
289 - Use for an audio system device.
290 * .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`:
291
292 - ``CEC_LOG_ADDR_TYPE_SPECIFIC``
293 - 5
294 - Use for a second TV or for a video processor device.
295 * .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`:
296
297 - ``CEC_LOG_ADDR_TYPE_UNREGISTERED``
298 - 6
299 - Use this if you just want to remain unregistered. Used for pure
300 CEC switches or CDC-only devices (CDC: Capability Discovery and
301 Control).
302
303
304
305.. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
306
307.. _cec-all-dev-types-flags:
308
309.. flat-table:: CEC All Device Types Flags
310 :header-rows: 0
311 :stub-columns: 0
312 :widths: 3 1 4
313
314 * .. _`CEC-OP-ALL-DEVTYPE-TV`:
315
316 - ``CEC_OP_ALL_DEVTYPE_TV``
317 - 0x80
318 - This supports the TV type.
319 * .. _`CEC-OP-ALL-DEVTYPE-RECORD`:
320
321 - ``CEC_OP_ALL_DEVTYPE_RECORD``
322 - 0x40
323 - This supports the Recording type.
324 * .. _`CEC-OP-ALL-DEVTYPE-TUNER`:
325
326 - ``CEC_OP_ALL_DEVTYPE_TUNER``
327 - 0x20
328 - This supports the Tuner type.
329 * .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`:
330
331 - ``CEC_OP_ALL_DEVTYPE_PLAYBACK``
332 - 0x10
333 - This supports the Playback type.
334 * .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`:
335
336 - ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM``
337 - 0x08
338 - This supports the Audio System type.
339 * .. _`CEC-OP-ALL-DEVTYPE-SWITCH`:
340
341 - ``CEC_OP_ALL_DEVTYPE_SWITCH``
342 - 0x04
343 - This supports the CEC Switch or Video Processing type.
344
345
346
347Return Value
348============
349
350On success 0 is returned, on error -1 and the ``errno`` variable is set
351appropriately. The generic error codes are described at the
352:ref:`Generic Error Codes <gen-errors>` chapter.
353