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