368 lines · plain
1.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later2.. c:namespace:: CEC3 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_ADDRS10****************************************************11 12Name13====14 15CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses16 17Synopsis18========19 20.. c:macro:: CEC_ADAP_G_LOG_ADDRS21 22``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)``23 24.. c:macro:: CEC_ADAP_S_LOG_ADDRS25 26``int ioctl(int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp)``27 28Arguments29=========30 31``fd``32 File descriptor returned by :c:func:`open()`.33 34``argp``35 Pointer to struct :c:type:`cec_log_addrs`.36 37Description38===========39 40To query the current CEC logical addresses, applications call41:ref:`ioctl CEC_ADAP_G_LOG_ADDRS <CEC_ADAP_G_LOG_ADDRS>` with a pointer to a42struct :c:type:`cec_log_addrs` where the driver stores the logical addresses.43 44To set new logical addresses, applications fill in45struct :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 is48returned 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 not50the ``EBUSY`` error code will be returned.51 52To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields53will be ignored in that case. The adapter will go to the unconfigured state and the54``cec_version``, ``vendor_id`` and ``osd_name`` fields are all reset to their default55values (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 logical59addresses have been claimed. If the file descriptor is in non-blocking mode then it will60not 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 the63logical addresses are claimed or cleared.64 65Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when66logical address types are already defined will return with error ``EBUSY``.67 68.. c:type:: cec_log_addrs69 70.. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{8.0cm}|71 72.. cssclass:: longtable73 74.. flat-table:: struct cec_log_addrs75 :header-rows: 076 :stub-columns: 077 :widths: 1 1 1678 79 * - __u880 - ``log_addr[CEC_MAX_LOG_ADDRS]``81 - The actual logical addresses that were claimed. This is set by the82 driver. If no logical address could be claimed, then it is set to83 ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then84 ``log_addr[0]`` is set to 0xf and all others to85 ``CEC_LOG_ADDR_INVALID``.86 * - __u1687 - ``log_addr_mask``88 - The bitmask of all logical addresses this adapter has claimed. If89 this adapter is Unregistered then ``log_addr_mask`` sets bit 1590 and clears all other bits. If this adapter is not configured at91 all, then ``log_addr_mask`` is set to 0. Set by the driver.92 * - __u893 - ``cec_version``94 - The CEC version that this adapter shall use. See95 :ref:`cec-versions`. Used to implement the96 ``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 CEC98 framework.99 * - __u8100 - ``num_log_addrs``101 - Number of logical addresses to set up. Must be ≤102 ``available_log_addrs`` as returned by103 :ref:`CEC_ADAP_G_CAPS`. All arrays in104 this structure are only filled up to index105 ``available_log_addrs``-1. The remaining array elements will be106 ignored. Note that the CEC 2.0 standard allows for a maximum of 2107 logical addresses, although some hardware has support for more.108 ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual109 number of logical addresses it could claim, which may be less than110 what was requested. If this field is set to 0, then the CEC111 adapter shall clear all claimed logical addresses and all other112 fields will be ignored.113 * - __u32114 - ``vendor_id``115 - The vendor ID is a 24-bit number that identifies the specific116 vendor or entity. Based on this ID vendor specific commands may be117 defined. If you do not want a vendor ID then set it to118 ``CEC_VENDOR_ID_NONE``.119 * - __u32120 - ``flags``121 - Flags. See :ref:`cec-log-addrs-flags` for a list of available flags.122 * - char123 - ``osd_name[15]``124 - The On-Screen Display name as is returned by the125 ``CEC_MSG_SET_OSD_NAME`` message.126 * - __u8127 - ``primary_device_type[CEC_MAX_LOG_ADDRS]``128 - Primary device type for each logical address. See129 :ref:`cec-prim-dev-types` for possible types.130 * - __u8131 - ``log_addr_type[CEC_MAX_LOG_ADDRS]``132 - Logical address types. See :ref:`cec-log-addr-types` for133 possible types. The driver will update this with the actual134 logical address type that it claimed (e.g. it may have to fallback135 to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`).136 * - __u8137 - ``all_device_types[CEC_MAX_LOG_ADDRS]``138 - CEC 2.0 specific: the bit mask of all device types. See139 :ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0140 ``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave141 this field to 0, or fill it in according to the CEC 2.0 guidelines to142 give the CEC framework more information about the device type, even143 though the framework won't use it directly in the CEC message.144 * - __u8145 - ``features[CEC_MAX_LOG_ADDRS][12]``146 - Features for each logical address. It is used in the CEC 2.0147 ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the148 RC Profile and the Device Features. For CEC 1.4 you can either leave149 this field to all 0, or fill it in according to the CEC 2.0 guidelines to150 give the CEC framework more information about the device type, even151 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_addrs158 :header-rows: 0159 :stub-columns: 0160 :widths: 3 1 4161 162 * .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`:163 164 - ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK``165 - 1166 - By default if no logical address of the requested type can be claimed, then167 it will go back to the unconfigured state. If this flag is set, then it will168 fallback to the Unregistered logical address. Note that if the Unregistered169 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 - 2174 - 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 subsystem177 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 this179 to avoid trivial snooping of the keystrokes.180 * .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`:181 182 - ``CEC_LOG_ADDRS_FL_CDC_ONLY``183 - 4184 - If this flag is set, then the device is CDC-Only. CDC-Only CEC devices185 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 Versions194 :header-rows: 0195 :stub-columns: 0196 :widths: 3 1 4197 198 * .. _`CEC-OP-CEC-VERSION-1-3A`:199 200 - ``CEC_OP_CEC_VERSION_1_3A``201 - 4202 - 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 - 5207 - 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 - 6212 - 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 Types219 :header-rows: 0220 :stub-columns: 0221 :widths: 3 1 4222 223 * .. _`CEC-OP-PRIM-DEVTYPE-TV`:224 225 - ``CEC_OP_PRIM_DEVTYPE_TV``226 - 0227 - Use for a TV.228 * .. _`CEC-OP-PRIM-DEVTYPE-RECORD`:229 230 - ``CEC_OP_PRIM_DEVTYPE_RECORD``231 - 1232 - Use for a recording device.233 * .. _`CEC-OP-PRIM-DEVTYPE-TUNER`:234 235 - ``CEC_OP_PRIM_DEVTYPE_TUNER``236 - 3237 - Use for a device with a tuner.238 * .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`:239 240 - ``CEC_OP_PRIM_DEVTYPE_PLAYBACK``241 - 4242 - Use for a playback device.243 * .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`:244 245 - ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM``246 - 5247 - 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 - 6252 - Use for a CEC switch.253 * .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`:254 255 - ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC``256 - 7257 - 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 Types264 :header-rows: 0265 :stub-columns: 0266 :widths: 3 1 16267 268 * .. _`CEC-LOG-ADDR-TYPE-TV`:269 270 - ``CEC_LOG_ADDR_TYPE_TV``271 - 0272 - Use for a TV.273 * .. _`CEC-LOG-ADDR-TYPE-RECORD`:274 275 - ``CEC_LOG_ADDR_TYPE_RECORD``276 - 1277 - Use for a recording device.278 * .. _`CEC-LOG-ADDR-TYPE-TUNER`:279 280 - ``CEC_LOG_ADDR_TYPE_TUNER``281 - 2282 - Use for a tuner device.283 * .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`:284 285 - ``CEC_LOG_ADDR_TYPE_PLAYBACK``286 - 3287 - Use for a playback device.288 * .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`:289 290 - ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM``291 - 4292 - Use for an audio system device.293 * .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`:294 295 - ``CEC_LOG_ADDR_TYPE_SPECIFIC``296 - 5297 - 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 - 6302 - Use this if you just want to remain unregistered. Used for pure303 CEC switches or CDC-only devices (CDC: Capability Discovery and304 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 Flags312 :header-rows: 0313 :stub-columns: 0314 :widths: 3 1 4315 316 * .. _`CEC-OP-ALL-DEVTYPE-TV`:317 318 - ``CEC_OP_ALL_DEVTYPE_TV``319 - 0x80320 - This supports the TV type.321 * .. _`CEC-OP-ALL-DEVTYPE-RECORD`:322 323 - ``CEC_OP_ALL_DEVTYPE_RECORD``324 - 0x40325 - This supports the Recording type.326 * .. _`CEC-OP-ALL-DEVTYPE-TUNER`:327 328 - ``CEC_OP_ALL_DEVTYPE_TUNER``329 - 0x20330 - This supports the Tuner type.331 * .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`:332 333 - ``CEC_OP_ALL_DEVTYPE_PLAYBACK``334 - 0x10335 - This supports the Playback type.336 * .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`:337 338 - ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM``339 - 0x08340 - This supports the Audio System type.341 * .. _`CEC-OP-ALL-DEVTYPE-SWITCH`:342 343 - ``CEC_OP_ALL_DEVTYPE_SWITCH``344 - 0x04345 - This supports the CEC Switch or Video Processing type.346 347 348Return Value349============350 351On success 0 is returned, on error -1 and the ``errno`` variable is set352appropriately. The generic error codes are described at the353:ref:`Generic Error Codes <gen-errors>` chapter.354 355The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` can return the following356error codes:357 358ENOTTY359 The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported.360 361EBUSY362 The CEC adapter is currently configuring itself, or it is already configured and363 ``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or364 initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``.365 366EINVAL367 The contents of struct :c:type:`cec_log_addrs` is invalid.368