1 .. -*- coding: utf-8; mode: rst -*-
3 .. _CEC_ADAP_LOG_ADDRS:
4 .. _CEC_ADAP_G_LOG_ADDRS:
5 .. _CEC_ADAP_S_LOG_ADDRS:
7 ****************************************************
8 ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS
9 ****************************************************
14 CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
20 .. c:function:: int ioctl( int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp )
21 :name: CEC_ADAP_G_LOG_ADDRS
23 .. c:function:: int ioctl( int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp )
24 :name: CEC_ADAP_S_LOG_ADDRS
30 File descriptor returned by :c:func:`open() <cec-open>`.
33 Pointer to struct cec_log_addrs
40 This documents the proposed CEC API. This API is not yet finalized
41 and is currently only available as a staging kernel module.
43 To query the current CEC logical addresses, applications call
44 :ref:`ioctl CEC_ADAP_G_LOG_ADDRS <CEC_ADAP_G_LOG_ADDRS>` with a pointer to a
45 :c:type:`struct cec_log_addrs` where the driver stores the logical addresses.
47 To set new logical addresses, applications fill in
48 :c:type:`struct cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
49 with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
50 is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is
51 returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
52 can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
53 the ``EBUSY`` error code will be returned.
55 To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields
56 will be ignored in that case. The adapter will go to the unconfigured state.
58 If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`),
59 then this ioctl will block until all requested logical
60 addresses have been claimed. If the file descriptor is in non-blocking mode then it will
61 not wait for the logical addresses to be claimed, instead it just returns 0.
63 A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the
64 logical addresses are claimed or cleared.
66 Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when
67 logical address types are already defined will return with error ``EBUSY``.
69 .. tabularcolumns:: |p{1.0cm}|p{7.5cm}|p{8.0cm}|
73 .. cssclass:: longtable
75 .. flat-table:: struct cec_log_addrs
85 - ``log_addr[CEC_MAX_LOG_ADDRS]``
87 - The actual logical addresses that were claimed. This is set by the
88 driver. If no logical address could be claimed, then it is set to
89 ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then
90 ``log_addr[0]`` is set to 0xf and all others to
91 ``CEC_LOG_ADDR_INVALID``.
99 - The bitmask of all logical addresses this adapter has claimed. If
100 this adapter is Unregistered then ``log_addr_mask`` sets bit 15
101 and clears all other bits. If this adapter is not configured at
102 all, then ``log_addr_mask`` is set to 0. Set by the driver.
110 - The CEC version that this adapter shall use. See
111 :ref:`cec-versions`. Used to implement the
112 ``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages.
113 Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC
122 - Number of logical addresses to set up. Must be ≤
123 ``available_log_addrs`` as returned by
124 :ref:`CEC_ADAP_G_CAPS`. All arrays in
125 this structure are only filled up to index
126 ``available_log_addrs``-1. The remaining array elements will be
127 ignored. Note that the CEC 2.0 standard allows for a maximum of 2
128 logical addresses, although some hardware has support for more.
129 ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual
130 number of logical addresses it could claim, which may be less than
131 what was requested. If this field is set to 0, then the CEC
132 adapter shall clear all claimed logical addresses and all other
133 fields will be ignored.
141 - The vendor ID is a 24-bit number that identifies the specific
142 vendor or entity. Based on this ID vendor specific commands may be
143 defined. If you do not want a vendor ID then set it to
144 ``CEC_VENDOR_ID_NONE``.
152 - Flags. No flags are defined yet, so set this to 0.
160 - The On-Screen Display name as is returned by the
161 ``CEC_MSG_SET_OSD_NAME`` message.
167 - ``primary_device_type[CEC_MAX_LOG_ADDRS]``
169 - Primary device type for each logical address. See
170 :ref:`cec-prim-dev-types` for possible types.
176 - ``log_addr_type[CEC_MAX_LOG_ADDRS]``
178 - Logical address types. See :ref:`cec-log-addr-types` for
179 possible types. The driver will update this with the actual
180 logical address type that it claimed (e.g. it may have to fallback
181 to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`).
187 - ``all_device_types[CEC_MAX_LOG_ADDRS]``
189 - CEC 2.0 specific: the bit mask of all device types. See
190 :ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0
191 ``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave
192 this field to 0, or fill it in according to the CEC 2.0 guidelines to
193 give the CEC framework more information about the device type, even
194 though the framework won't use it directly in the CEC message.
200 - ``features[CEC_MAX_LOG_ADDRS][12]``
202 - Features for each logical address. It is used in the CEC 2.0
203 ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the
204 RC Profile and the Device Features. For CEC 1.4 you can either leave
205 this field to all 0, or fill it in according to the CEC 2.0 guidelines to
206 give the CEC framework more information about the device type, even
207 though the framework won't use it directly in the CEC message.
209 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
213 .. flat-table:: CEC Versions
219 - .. _`CEC-OP-CEC-VERSION-1-3A`:
221 - ``CEC_OP_CEC_VERSION_1_3A``
225 - CEC version according to the HDMI 1.3a standard.
227 - .. _`CEC-OP-CEC-VERSION-1-4B`:
229 - ``CEC_OP_CEC_VERSION_1_4B``
233 - CEC version according to the HDMI 1.4b standard.
235 - .. _`CEC-OP-CEC-VERSION-2-0`:
237 - ``CEC_OP_CEC_VERSION_2_0``
241 - CEC version according to the HDMI 2.0 standard.
244 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
246 .. _cec-prim-dev-types:
248 .. flat-table:: CEC Primary Device Types
254 - .. _`CEC-OP-PRIM-DEVTYPE-TV`:
256 - ``CEC_OP_PRIM_DEVTYPE_TV``
262 - .. _`CEC-OP-PRIM-DEVTYPE-RECORD`:
264 - ``CEC_OP_PRIM_DEVTYPE_RECORD``
268 - Use for a recording device.
270 - .. _`CEC-OP-PRIM-DEVTYPE-TUNER`:
272 - ``CEC_OP_PRIM_DEVTYPE_TUNER``
276 - Use for a device with a tuner.
278 - .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`:
280 - ``CEC_OP_PRIM_DEVTYPE_PLAYBACK``
284 - Use for a playback device.
286 - .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`:
288 - ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM``
292 - Use for an audio system (e.g. an audio/video receiver).
294 - .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`:
296 - ``CEC_OP_PRIM_DEVTYPE_SWITCH``
300 - Use for a CEC switch.
302 - .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`:
304 - ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC``
308 - Use for a video processor device.
311 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
313 .. _cec-log-addr-types:
315 .. flat-table:: CEC Logical Address Types
321 - .. _`CEC-LOG-ADDR-TYPE-TV`:
323 - ``CEC_LOG_ADDR_TYPE_TV``
329 - .. _`CEC-LOG-ADDR-TYPE-RECORD`:
331 - ``CEC_LOG_ADDR_TYPE_RECORD``
335 - Use for a recording device.
337 - .. _`CEC-LOG-ADDR-TYPE-TUNER`:
339 - ``CEC_LOG_ADDR_TYPE_TUNER``
343 - Use for a tuner device.
345 - .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`:
347 - ``CEC_LOG_ADDR_TYPE_PLAYBACK``
351 - Use for a playback device.
353 - .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`:
355 - ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM``
359 - Use for an audio system device.
361 - .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`:
363 - ``CEC_LOG_ADDR_TYPE_SPECIFIC``
367 - Use for a second TV or for a video processor device.
369 - .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`:
371 - ``CEC_LOG_ADDR_TYPE_UNREGISTERED``
375 - Use this if you just want to remain unregistered. Used for pure
376 CEC switches or CDC-only devices (CDC: Capability Discovery and
381 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.7cm}|
383 .. _cec-all-dev-types-flags:
385 .. flat-table:: CEC All Device Types Flags
391 - .. _`CEC-OP-ALL-DEVTYPE-TV`:
393 - ``CEC_OP_ALL_DEVTYPE_TV``
397 - This supports the TV type.
399 - .. _`CEC-OP-ALL-DEVTYPE-RECORD`:
401 - ``CEC_OP_ALL_DEVTYPE_RECORD``
405 - This supports the Recording type.
407 - .. _`CEC-OP-ALL-DEVTYPE-TUNER`:
409 - ``CEC_OP_ALL_DEVTYPE_TUNER``
413 - This supports the Tuner type.
415 - .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`:
417 - ``CEC_OP_ALL_DEVTYPE_PLAYBACK``
421 - This supports the Playback type.
423 - .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`:
425 - ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM``
429 - This supports the Audio System type.
431 - .. _`CEC-OP-ALL-DEVTYPE-SWITCH`:
433 - ``CEC_OP_ALL_DEVTYPE_SWITCH``
437 - This supports the CEC Switch or Video Processing type.
444 On success 0 is returned, on error -1 and the ``errno`` variable is set
445 appropriately. The generic error codes are described at the
446 :ref:`Generic Error Codes <gen-errors>` chapter.