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