0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: CEC
0003
0004 .. _CEC_ADAP_LOG_ADDRS:
0005 .. _CEC_ADAP_G_LOG_ADDRS:
0006 .. _CEC_ADAP_S_LOG_ADDRS:
0007
0008 ****************************************************
0009 ioctls CEC_ADAP_G_LOG_ADDRS and CEC_ADAP_S_LOG_ADDRS
0010 ****************************************************
0011
0012 Name
0013 ====
0014
0015 CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS - Get or set the logical addresses
0016
0017 Synopsis
0018 ========
0019
0020 .. c:macro:: CEC_ADAP_G_LOG_ADDRS
0021
0022 ``int ioctl(int fd, CEC_ADAP_G_LOG_ADDRS, struct cec_log_addrs *argp)``
0023
0024 .. c:macro:: CEC_ADAP_S_LOG_ADDRS
0025
0026 ``int ioctl(int fd, CEC_ADAP_S_LOG_ADDRS, struct cec_log_addrs *argp)``
0027
0028 Arguments
0029 =========
0030
0031 ``fd``
0032 File descriptor returned by :c:func:`open()`.
0033
0034 ``argp``
0035 Pointer to struct :c:type:`cec_log_addrs`.
0036
0037 Description
0038 ===========
0039
0040 To query the current CEC logical addresses, applications call
0041 :ref:`ioctl CEC_ADAP_G_LOG_ADDRS <CEC_ADAP_G_LOG_ADDRS>` with a pointer to a
0042 struct :c:type:`cec_log_addrs` where the driver stores the logical addresses.
0043
0044 To set new logical addresses, applications fill in
0045 struct :c:type:`cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
0046 with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
0047 is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is
0048 returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
0049 can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
0050 the ``EBUSY`` error code will be returned.
0051
0052 To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields
0053 will be ignored in that case. The adapter will go to the unconfigured state and the
0054 ``cec_version``, ``vendor_id`` and ``osd_name`` fields are all reset to their default
0055 values (CEC version 2.0, no vendor ID and an empty OSD name).
0056
0057 If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`),
0058 then this ioctl will block until all requested logical
0059 addresses have been claimed. If the file descriptor is in non-blocking mode then it will
0060 not wait for the logical addresses to be claimed, instead it just returns 0.
0061
0062 A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the
0063 logical addresses are claimed or cleared.
0064
0065 Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when
0066 logical address types are already defined will return with error ``EBUSY``.
0067
0068 .. c:type:: cec_log_addrs
0069
0070 .. tabularcolumns:: |p{1.0cm}|p{8.0cm}|p{8.0cm}|
0071
0072 .. cssclass:: longtable
0073
0074 .. flat-table:: struct cec_log_addrs
0075 :header-rows: 0
0076 :stub-columns: 0
0077 :widths: 1 1 16
0078
0079 * - __u8
0080 - ``log_addr[CEC_MAX_LOG_ADDRS]``
0081 - The actual logical addresses that were claimed. This is set by the
0082 driver. If no logical address could be claimed, then it is set to
0083 ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then
0084 ``log_addr[0]`` is set to 0xf and all others to
0085 ``CEC_LOG_ADDR_INVALID``.
0086 * - __u16
0087 - ``log_addr_mask``
0088 - The bitmask of all logical addresses this adapter has claimed. If
0089 this adapter is Unregistered then ``log_addr_mask`` sets bit 15
0090 and clears all other bits. If this adapter is not configured at
0091 all, then ``log_addr_mask`` is set to 0. Set by the driver.
0092 * - __u8
0093 - ``cec_version``
0094 - The CEC version that this adapter shall use. See
0095 :ref:`cec-versions`. Used to implement the
0096 ``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages.
0097 Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC
0098 framework.
0099 * - __u8
0100 - ``num_log_addrs``
0101 - Number of logical addresses to set up. Must be ≤
0102 ``available_log_addrs`` as returned by
0103 :ref:`CEC_ADAP_G_CAPS`. All arrays in
0104 this structure are only filled up to index
0105 ``available_log_addrs``-1. The remaining array elements will be
0106 ignored. Note that the CEC 2.0 standard allows for a maximum of 2
0107 logical addresses, although some hardware has support for more.
0108 ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual
0109 number of logical addresses it could claim, which may be less than
0110 what was requested. If this field is set to 0, then the CEC
0111 adapter shall clear all claimed logical addresses and all other
0112 fields will be ignored.
0113 * - __u32
0114 - ``vendor_id``
0115 - The vendor ID is a 24-bit number that identifies the specific
0116 vendor or entity. Based on this ID vendor specific commands may be
0117 defined. If you do not want a vendor ID then set it to
0118 ``CEC_VENDOR_ID_NONE``.
0119 * - __u32
0120 - ``flags``
0121 - Flags. See :ref:`cec-log-addrs-flags` for a list of available flags.
0122 * - char
0123 - ``osd_name[15]``
0124 - The On-Screen Display name as is returned by the
0125 ``CEC_MSG_SET_OSD_NAME`` message.
0126 * - __u8
0127 - ``primary_device_type[CEC_MAX_LOG_ADDRS]``
0128 - Primary device type for each logical address. See
0129 :ref:`cec-prim-dev-types` for possible types.
0130 * - __u8
0131 - ``log_addr_type[CEC_MAX_LOG_ADDRS]``
0132 - Logical address types. See :ref:`cec-log-addr-types` for
0133 possible types. The driver will update this with the actual
0134 logical address type that it claimed (e.g. it may have to fallback
0135 to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`).
0136 * - __u8
0137 - ``all_device_types[CEC_MAX_LOG_ADDRS]``
0138 - CEC 2.0 specific: the bit mask of all device types. See
0139 :ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0
0140 ``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave
0141 this field to 0, or fill it in according to the CEC 2.0 guidelines to
0142 give the CEC framework more information about the device type, even
0143 though the framework won't use it directly in the CEC message.
0144 * - __u8
0145 - ``features[CEC_MAX_LOG_ADDRS][12]``
0146 - Features for each logical address. It is used in the CEC 2.0
0147 ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the
0148 RC Profile and the Device Features. For CEC 1.4 you can either leave
0149 this field to all 0, or fill it in according to the CEC 2.0 guidelines to
0150 give the CEC framework more information about the device type, even
0151 though the framework won't use it directly in the CEC message.
0152
0153 .. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}|
0154
0155 .. _cec-log-addrs-flags:
0156
0157 .. flat-table:: Flags for struct cec_log_addrs
0158 :header-rows: 0
0159 :stub-columns: 0
0160 :widths: 3 1 4
0161
0162 * .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`:
0163
0164 - ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK``
0165 - 1
0166 - By default if no logical address of the requested type can be claimed, then
0167 it will go back to the unconfigured state. If this flag is set, then it will
0168 fallback to the Unregistered logical address. Note that if the Unregistered
0169 logical address was explicitly requested, then this flag has no effect.
0170 * .. _`CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU`:
0171
0172 - ``CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU``
0173 - 2
0174 - By default the ``CEC_MSG_USER_CONTROL_PRESSED`` and ``CEC_MSG_USER_CONTROL_RELEASED``
0175 messages are only passed on to the follower(s), if any. If this flag is set,
0176 then these messages are also passed on to the remote control input subsystem
0177 and will appear as keystrokes. This features needs to be enabled explicitly.
0178 If CEC is used to enter e.g. passwords, then you may not want to enable this
0179 to avoid trivial snooping of the keystrokes.
0180 * .. _`CEC-LOG-ADDRS-FL-CDC-ONLY`:
0181
0182 - ``CEC_LOG_ADDRS_FL_CDC_ONLY``
0183 - 4
0184 - If this flag is set, then the device is CDC-Only. CDC-Only CEC devices
0185 are CEC devices that can only handle CDC messages.
0186
0187 All other messages are ignored.
0188
0189 .. tabularcolumns:: |p{7.8cm}|p{1.0cm}|p{8.5cm}|
0190
0191 .. _cec-versions:
0192
0193 .. flat-table:: CEC Versions
0194 :header-rows: 0
0195 :stub-columns: 0
0196 :widths: 3 1 4
0197
0198 * .. _`CEC-OP-CEC-VERSION-1-3A`:
0199
0200 - ``CEC_OP_CEC_VERSION_1_3A``
0201 - 4
0202 - CEC version according to the HDMI 1.3a standard.
0203 * .. _`CEC-OP-CEC-VERSION-1-4B`:
0204
0205 - ``CEC_OP_CEC_VERSION_1_4B``
0206 - 5
0207 - CEC version according to the HDMI 1.4b standard.
0208 * .. _`CEC-OP-CEC-VERSION-2-0`:
0209
0210 - ``CEC_OP_CEC_VERSION_2_0``
0211 - 6
0212 - CEC version according to the HDMI 2.0 standard.
0213
0214 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0215
0216 .. _cec-prim-dev-types:
0217
0218 .. flat-table:: CEC Primary Device Types
0219 :header-rows: 0
0220 :stub-columns: 0
0221 :widths: 3 1 4
0222
0223 * .. _`CEC-OP-PRIM-DEVTYPE-TV`:
0224
0225 - ``CEC_OP_PRIM_DEVTYPE_TV``
0226 - 0
0227 - Use for a TV.
0228 * .. _`CEC-OP-PRIM-DEVTYPE-RECORD`:
0229
0230 - ``CEC_OP_PRIM_DEVTYPE_RECORD``
0231 - 1
0232 - Use for a recording device.
0233 * .. _`CEC-OP-PRIM-DEVTYPE-TUNER`:
0234
0235 - ``CEC_OP_PRIM_DEVTYPE_TUNER``
0236 - 3
0237 - Use for a device with a tuner.
0238 * .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`:
0239
0240 - ``CEC_OP_PRIM_DEVTYPE_PLAYBACK``
0241 - 4
0242 - Use for a playback device.
0243 * .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`:
0244
0245 - ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM``
0246 - 5
0247 - Use for an audio system (e.g. an audio/video receiver).
0248 * .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`:
0249
0250 - ``CEC_OP_PRIM_DEVTYPE_SWITCH``
0251 - 6
0252 - Use for a CEC switch.
0253 * .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`:
0254
0255 - ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC``
0256 - 7
0257 - Use for a video processor device.
0258
0259 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0260
0261 .. _cec-log-addr-types:
0262
0263 .. flat-table:: CEC Logical Address Types
0264 :header-rows: 0
0265 :stub-columns: 0
0266 :widths: 3 1 16
0267
0268 * .. _`CEC-LOG-ADDR-TYPE-TV`:
0269
0270 - ``CEC_LOG_ADDR_TYPE_TV``
0271 - 0
0272 - Use for a TV.
0273 * .. _`CEC-LOG-ADDR-TYPE-RECORD`:
0274
0275 - ``CEC_LOG_ADDR_TYPE_RECORD``
0276 - 1
0277 - Use for a recording device.
0278 * .. _`CEC-LOG-ADDR-TYPE-TUNER`:
0279
0280 - ``CEC_LOG_ADDR_TYPE_TUNER``
0281 - 2
0282 - Use for a tuner device.
0283 * .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`:
0284
0285 - ``CEC_LOG_ADDR_TYPE_PLAYBACK``
0286 - 3
0287 - Use for a playback device.
0288 * .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`:
0289
0290 - ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM``
0291 - 4
0292 - Use for an audio system device.
0293 * .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`:
0294
0295 - ``CEC_LOG_ADDR_TYPE_SPECIFIC``
0296 - 5
0297 - Use for a second TV or for a video processor device.
0298 * .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`:
0299
0300 - ``CEC_LOG_ADDR_TYPE_UNREGISTERED``
0301 - 6
0302 - Use this if you just want to remain unregistered. Used for pure
0303 CEC switches or CDC-only devices (CDC: Capability Discovery and
0304 Control).
0305
0306
0307 .. tabularcolumns:: |p{6.6cm}|p{2.2cm}|p{8.5cm}|
0308
0309 .. _cec-all-dev-types-flags:
0310
0311 .. flat-table:: CEC All Device Types Flags
0312 :header-rows: 0
0313 :stub-columns: 0
0314 :widths: 3 1 4
0315
0316 * .. _`CEC-OP-ALL-DEVTYPE-TV`:
0317
0318 - ``CEC_OP_ALL_DEVTYPE_TV``
0319 - 0x80
0320 - This supports the TV type.
0321 * .. _`CEC-OP-ALL-DEVTYPE-RECORD`:
0322
0323 - ``CEC_OP_ALL_DEVTYPE_RECORD``
0324 - 0x40
0325 - This supports the Recording type.
0326 * .. _`CEC-OP-ALL-DEVTYPE-TUNER`:
0327
0328 - ``CEC_OP_ALL_DEVTYPE_TUNER``
0329 - 0x20
0330 - This supports the Tuner type.
0331 * .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`:
0332
0333 - ``CEC_OP_ALL_DEVTYPE_PLAYBACK``
0334 - 0x10
0335 - This supports the Playback type.
0336 * .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`:
0337
0338 - ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM``
0339 - 0x08
0340 - This supports the Audio System type.
0341 * .. _`CEC-OP-ALL-DEVTYPE-SWITCH`:
0342
0343 - ``CEC_OP_ALL_DEVTYPE_SWITCH``
0344 - 0x04
0345 - This supports the CEC Switch or Video Processing type.
0346
0347
0348 Return Value
0349 ============
0350
0351 On success 0 is returned, on error -1 and the ``errno`` variable is set
0352 appropriately. The generic error codes are described at the
0353 :ref:`Generic Error Codes <gen-errors>` chapter.
0354
0355 The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` can return the following
0356 error codes:
0357
0358 ENOTTY
0359 The ``CEC_CAP_LOG_ADDRS`` capability wasn't set, so this ioctl is not supported.
0360
0361 EBUSY
0362 The CEC adapter is currently configuring itself, or it is already configured and
0363 ``num_log_addrs`` is non-zero, or another filehandle is in exclusive follower or
0364 initiator mode, or the filehandle is in mode ``CEC_MODE_NO_INITIATOR``.
0365
0366 EINVAL
0367 The contents of struct :c:type:`cec_log_addrs` is invalid.
