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

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