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

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