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