Documentation/userspace-api/media/cec/cec-ioc-adap-g-log-addrs.rst

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