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