| 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. |