cec-ioc-adap-g-log-addrs.rst (12308B)
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**************************************************** 9ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS 10**************************************************** 11 12Name 13==== 14 15CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses 16 17Synopsis 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 28Arguments 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 37Description 38=========== 39 40To 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 42struct :c:type:`cec_log_addrs` where the driver stores the logical addresses. 43 44To set new logical addresses, applications fill in 45struct :c:type:`cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` 46with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` 47is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is 48returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` 49can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not 50the ``EBUSY`` error code will be returned. 51 52To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields 53will 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 55values (CEC version 2.0, no vendor ID and an empty OSD name). 56 57If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`), 58then this ioctl will block until all requested logical 59addresses have been claimed. If the file descriptor is in non-blocking mode then it will 60not wait for the logical addresses to be claimed, instead it just returns 0. 61 62A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the 63logical addresses are claimed or cleared. 64 65Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when 66logical 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 348Return Value 349============ 350 351On success 0 is returned, on error -1 and the ``errno`` variable is set 352appropriately. The generic error codes are described at the 353:ref:`Generic Error Codes <gen-errors>` chapter. 354 355The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` can return the following 356error codes: 357 358ENOTTY 359 The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported. 360 361EBUSY 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 366EINVAL 367 The contents of struct :c:type:`cec_log_addrs` is invalid.