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 .. cpp:function:: int ioctl( int fd, int request, struct cec_log_addrs *argp )
  21
  22
  23 Arguments
  24 =========
  25
  26 ``fd``
  27     File descriptor returned by :ref:`open() <cec-func-open>`.
  28
  29 ``request``
  30     CEC_ADAP_G_LOG_ADDRS, CEC_ADAP_S_LOG_ADDRS
  31
  32 ``argp``
  33
  34
  35 Description
  36 ===========
  37
  38 .. note:: This documents the proposed CEC API. This API is not yet finalized
  39    and is currently only available as a staging kernel module.
  40
  41 To query the current CEC logical addresses, applications call
  42 :ref:`ioctl CEC_ADAP_G_LOG_ADDRS <CEC_ADAP_G_LOG_ADDRS>` with a pointer to a
  43 :c:type:`struct cec_log_addrs` where the driver stores the logical addresses.
  44
  45 To set new logical addresses, applications fill in
  46 :c:type:`struct cec_log_addrs` and call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
  47 with a pointer to this struct. The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
  48 is only available if ``CEC_CAP_LOG_ADDRS`` is set (the ``ENOTTY`` error code is
  49 returned otherwise). The :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`
  50 can only be called by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
  51 the ``EBUSY`` error code will be returned.
  52
  53 To clear existing logical addresses set ``num_log_addrs`` to 0. All other fields
  54 will be ignored in that case. The adapter will go to the unconfigured state.
  55
  56 If the physical address is valid (see :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`),
  57 then this ioctl will block until all requested logical
  58 addresses have been claimed. If the file descriptor is in non-blocking mode then it will
  59 not wait for the logical addresses to be claimed, instead it just returns 0.
  60
  61 A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the
  62 logical addresses are claimed or cleared.
  63
  64 Attempting to call :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>` when
  65 logical address types are already defined will return with error ``EBUSY``.
  66
  67
  68 .. _cec-log-addrs:
  69
  70 .. flat-table:: struct cec_log_addrs
  71     :header-rows:  0
  72     :stub-columns: 0
  73     :widths:       1 1 16
  74
  75
  76     -  .. row 1
  77
  78        -  __u8
  79
  80        -  ``log_addr[CEC_MAX_LOG_ADDRS]``
  81
  82        -  The actual logical addresses that were claimed. This is set by the
  83           driver. If no logical address could be claimed, then it is set to
  84           ``CEC_LOG_ADDR_INVALID``. If this adapter is Unregistered, then
  85           ``log_addr[0]`` is set to 0xf and all others to
  86           ``CEC_LOG_ADDR_INVALID``.
  87
  88     -  .. row 2
  89
  90        -  __u16
  91
  92        -  ``log_addr_mask``
  93
  94        -  The bitmask of all logical addresses this adapter has claimed. If
  95           this adapter is Unregistered then ``log_addr_mask`` sets bit 15
  96           and clears all other bits. If this adapter is not configured at
  97           all, then ``log_addr_mask`` is set to 0. Set by the driver.
  98
  99     -  .. row 3
 100
 101        -  __u8
 102
 103        -  ``cec_version``
 104
 105        -  The CEC version that this adapter shall use. See
 106           :ref:`cec-versions`. Used to implement the
 107           ``CEC_MSG_CEC_VERSION`` and ``CEC_MSG_REPORT_FEATURES`` messages.
 108           Note that :ref:`CEC_OP_CEC_VERSION_1_3A <CEC-OP-CEC-VERSION-1-3A>` is not allowed by the CEC
 109           framework.
 110
 111     -  .. row 4
 112
 113        -  __u8
 114
 115        -  ``num_log_addrs``
 116
 117        -  Number of logical addresses to set up. Must be ≤
 118           ``available_log_addrs`` as returned by
 119           :ref:`CEC_ADAP_G_CAPS`. All arrays in
 120           this structure are only filled up to index
 121           ``available_log_addrs``-1. The remaining array elements will be
 122           ignored. Note that the CEC 2.0 standard allows for a maximum of 2
 123           logical addresses, although some hardware has support for more.
 124           ``CEC_MAX_LOG_ADDRS`` is 4. The driver will return the actual
 125           number of logical addresses it could claim, which may be less than
 126           what was requested. If this field is set to 0, then the CEC
 127           adapter shall clear all claimed logical addresses and all other
 128           fields will be ignored.
 129
 130     -  .. row 5
 131
 132        -  __u32
 133
 134        -  ``vendor_id``
 135
 136        -  The vendor ID is a 24-bit number that identifies the specific
 137           vendor or entity. Based on this ID vendor specific commands may be
 138           defined. If you do not want a vendor ID then set it to
 139           ``CEC_VENDOR_ID_NONE``.
 140
 141     -  .. row 6
 142
 143        -  __u32
 144
 145        -  ``flags``
 146
 147        -  Flags. See :ref:`cec-log-addrs-flags` for a list of available flags.
 148
 149     -  .. row 7
 150
 151        -  char
 152
 153        -  ``osd_name[15]``
 154
 155        -  The On-Screen Display name as is returned by the
 156           ``CEC_MSG_SET_OSD_NAME`` message.
 157
 158     -  .. row 8
 159
 160        -  __u8
 161
 162        -  ``primary_device_type[CEC_MAX_LOG_ADDRS]``
 163
 164        -  Primary device type for each logical address. See
 165           :ref:`cec-prim-dev-types` for possible types.
 166
 167     -  .. row 9
 168
 169        -  __u8
 170
 171        -  ``log_addr_type[CEC_MAX_LOG_ADDRS]``
 172
 173        -  Logical address types. See :ref:`cec-log-addr-types` for
 174           possible types. The driver will update this with the actual
 175           logical address type that it claimed (e.g. it may have to fallback
 176           to :ref:`CEC_LOG_ADDR_TYPE_UNREGISTERED <CEC-LOG-ADDR-TYPE-UNREGISTERED>`).
 177
 178     -  .. row 10
 179
 180        -  __u8
 181
 182        -  ``all_device_types[CEC_MAX_LOG_ADDRS]``
 183
 184        -  CEC 2.0 specific: the bit mask of all device types. See
 185           :ref:`cec-all-dev-types-flags`. It is used in the CEC 2.0
 186           ``CEC_MSG_REPORT_FEATURES`` message. For CEC 1.4 you can either leave
 187           this field to 0, or fill it in according to the CEC 2.0 guidelines to
 188           give the CEC framework more information about the device type, even
 189           though the framework won't use it directly in the CEC message.
 190
 191     -  .. row 11
 192
 193        -  __u8
 194
 195        -  ``features[CEC_MAX_LOG_ADDRS][12]``
 196
 197        -  Features for each logical address. It is used in the CEC 2.0
 198           ``CEC_MSG_REPORT_FEATURES`` message. The 12 bytes include both the
 199           RC Profile and the Device Features. For CEC 1.4 you can either leave
 200           this field to all 0, or fill it in according to the CEC 2.0 guidelines to
 201           give the CEC framework more information about the device type, even
 202           though the framework won't use it directly in the CEC message.
 203
 204 .. _cec-log-addrs-flags:
 205
 206 .. flat-table:: Flags for struct cec_log_addrs
 207     :header-rows:  0
 208     :stub-columns: 0
 209     :widths:       3 1 4
 210
 211
 212     -  .. _`CEC-LOG-ADDRS-FL-ALLOW-UNREG-FALLBACK`:
 213
 214        -  ``CEC_LOG_ADDRS_FL_ALLOW_UNREG_FALLBACK``
 215
 216        -  1
 217
 218        -  By default if no logical address of the requested type can be claimed, then
 219           it will go back to the unconfigured state. If this flag is set, then it will
 220           fallback to the Unregistered logical address. Note that if the Unregistered
 221           logical address was explicitly requested, then this flag has no effect.
 222
 223 .. _cec-versions:
 224
 225 .. flat-table:: CEC Versions
 226     :header-rows:  0
 227     :stub-columns: 0
 228     :widths:       3 1 4
 229
 230
 231     -  .. _`CEC-OP-CEC-VERSION-1-3A`:
 232
 233        -  ``CEC_OP_CEC_VERSION_1_3A``
 234
 235        -  4
 236
 237        -  CEC version according to the HDMI 1.3a standard.
 238
 239     -  .. _`CEC-OP-CEC-VERSION-1-4B`:
 240
 241        -  ``CEC_OP_CEC_VERSION_1_4B``
 242
 243        -  5
 244
 245        -  CEC version according to the HDMI 1.4b standard.
 246
 247     -  .. _`CEC-OP-CEC-VERSION-2-0`:
 248
 249        -  ``CEC_OP_CEC_VERSION_2_0``
 250
 251        -  6
 252
 253        -  CEC version according to the HDMI 2.0 standard.
 254
 255
 256
 257 .. _cec-prim-dev-types:
 258
 259 .. flat-table:: CEC Primary Device Types
 260     :header-rows:  0
 261     :stub-columns: 0
 262     :widths:       3 1 4
 263
 264
 265     -  .. _`CEC-OP-PRIM-DEVTYPE-TV`:
 266
 267        -  ``CEC_OP_PRIM_DEVTYPE_TV``
 268
 269        -  0
 270
 271        -  Use for a TV.
 272
 273     -  .. _`CEC-OP-PRIM-DEVTYPE-RECORD`:
 274
 275        -  ``CEC_OP_PRIM_DEVTYPE_RECORD``
 276
 277        -  1
 278
 279        -  Use for a recording device.
 280
 281     -  .. _`CEC-OP-PRIM-DEVTYPE-TUNER`:
 282
 283        -  ``CEC_OP_PRIM_DEVTYPE_TUNER``
 284
 285        -  3
 286
 287        -  Use for a device with a tuner.
 288
 289     -  .. _`CEC-OP-PRIM-DEVTYPE-PLAYBACK`:
 290
 291        -  ``CEC_OP_PRIM_DEVTYPE_PLAYBACK``
 292
 293        -  4
 294
 295        -  Use for a playback device.
 296
 297     -  .. _`CEC-OP-PRIM-DEVTYPE-AUDIOSYSTEM`:
 298
 299        -  ``CEC_OP_PRIM_DEVTYPE_AUDIOSYSTEM``
 300
 301        -  5
 302
 303        -  Use for an audio system (e.g. an audio/video receiver).
 304
 305     -  .. _`CEC-OP-PRIM-DEVTYPE-SWITCH`:
 306
 307        -  ``CEC_OP_PRIM_DEVTYPE_SWITCH``
 308
 309        -  6
 310
 311        -  Use for a CEC switch.
 312
 313     -  .. _`CEC-OP-PRIM-DEVTYPE-VIDEOPROC`:
 314
 315        -  ``CEC_OP_PRIM_DEVTYPE_VIDEOPROC``
 316
 317        -  7
 318
 319        -  Use for a video processor device.
 320
 321
 322
 323 .. _cec-log-addr-types:
 324
 325 .. flat-table:: CEC Logical Address Types
 326     :header-rows:  0
 327     :stub-columns: 0
 328     :widths:       3 1 16
 329
 330
 331     -  .. _`CEC-LOG-ADDR-TYPE-TV`:
 332
 333        -  ``CEC_LOG_ADDR_TYPE_TV``
 334
 335        -  0
 336
 337        -  Use for a TV.
 338
 339     -  .. _`CEC-LOG-ADDR-TYPE-RECORD`:
 340
 341        -  ``CEC_LOG_ADDR_TYPE_RECORD``
 342
 343        -  1
 344
 345        -  Use for a recording device.
 346
 347     -  .. _`CEC-LOG-ADDR-TYPE-TUNER`:
 348
 349        -  ``CEC_LOG_ADDR_TYPE_TUNER``
 350
 351        -  2
 352
 353        -  Use for a tuner device.
 354
 355     -  .. _`CEC-LOG-ADDR-TYPE-PLAYBACK`:
 356
 357        -  ``CEC_LOG_ADDR_TYPE_PLAYBACK``
 358
 359        -  3
 360
 361        -  Use for a playback device.
 362
 363     -  .. _`CEC-LOG-ADDR-TYPE-AUDIOSYSTEM`:
 364
 365        -  ``CEC_LOG_ADDR_TYPE_AUDIOSYSTEM``
 366
 367        -  4
 368
 369        -  Use for an audio system device.
 370
 371     -  .. _`CEC-LOG-ADDR-TYPE-SPECIFIC`:
 372
 373        -  ``CEC_LOG_ADDR_TYPE_SPECIFIC``
 374
 375        -  5
 376
 377        -  Use for a second TV or for a video processor device.
 378
 379     -  .. _`CEC-LOG-ADDR-TYPE-UNREGISTERED`:
 380
 381        -  ``CEC_LOG_ADDR_TYPE_UNREGISTERED``
 382
 383        -  6
 384
 385        -  Use this if you just want to remain unregistered. Used for pure
 386           CEC switches or CDC-only devices (CDC: Capability Discovery and
 387           Control).
 388
 389
 390
 391 .. _cec-all-dev-types-flags:
 392
 393 .. flat-table:: CEC All Device Types Flags
 394     :header-rows:  0
 395     :stub-columns: 0
 396     :widths:       3 1 4
 397
 398
 399     -  .. _`CEC-OP-ALL-DEVTYPE-TV`:
 400
 401        -  ``CEC_OP_ALL_DEVTYPE_TV``
 402
 403        -  0x80
 404
 405        -  This supports the TV type.
 406
 407     -  .. _`CEC-OP-ALL-DEVTYPE-RECORD`:
 408
 409        -  ``CEC_OP_ALL_DEVTYPE_RECORD``
 410
 411        -  0x40
 412
 413        -  This supports the Recording type.
 414
 415     -  .. _`CEC-OP-ALL-DEVTYPE-TUNER`:
 416
 417        -  ``CEC_OP_ALL_DEVTYPE_TUNER``
 418
 419        -  0x20
 420
 421        -  This supports the Tuner type.
 422
 423     -  .. _`CEC-OP-ALL-DEVTYPE-PLAYBACK`:
 424
 425        -  ``CEC_OP_ALL_DEVTYPE_PLAYBACK``
 426
 427        -  0x10
 428
 429        -  This supports the Playback type.
 430
 431     -  .. _`CEC-OP-ALL-DEVTYPE-AUDIOSYSTEM`:
 432
 433        -  ``CEC_OP_ALL_DEVTYPE_AUDIOSYSTEM``
 434
 435        -  0x08
 436
 437        -  This supports the Audio System type.
 438
 439     -  .. _`CEC-OP-ALL-DEVTYPE-SWITCH`:
 440
 441        -  ``CEC_OP_ALL_DEVTYPE_SWITCH``
 442
 443        -  0x04
 444
 445        -  This supports the CEC Switch or Video Processing type.
 446
 447
 448
 449 Return Value
 450 ============
 451
 452 On success 0 is returned, on error -1 and the ``errno`` variable is set
 453 appropriately. The generic error codes are described at the
 454 :ref:`Generic Error Codes <gen-errors>` chapter.
 455