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