Documentation/media/uapi/cec/cec-ioc-adap-g-phys-addr.rst

   1 .. -*- coding: utf-8; mode: rst -*-
   2
   3 .. _CEC_ADAP_PHYS_ADDR:
   4 .. _CEC_ADAP_G_PHYS_ADDR:
   5 .. _CEC_ADAP_S_PHYS_ADDR:
   6
   7 ****************************************************
   8 ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR
   9 ****************************************************
  10
  11 Name
  12 ====
  13
  14 CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
  15
  16
  17 Synopsis
  18 ========
  19
  20 .. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp )
  21     :name: CEC_ADAP_G_PHYS_ADDR
  22
  23 .. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp )
  24     :name: CEC_ADAP_S_PHYS_ADDR
  25
  26 Arguments
  27 =========
  28
  29 ``fd``
  30     File descriptor returned by :c:func:`open() <cec-open>`.
  31
  32 ``argp``
  33     Pointer to the CEC address.
  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 physical address applications call
  44 :ref:`ioctl CEC_ADAP_G_PHYS_ADDR <CEC_ADAP_G_PHYS_ADDR>` with a pointer to a __u16 where the
  45 driver stores the physical address.
  46
  47 To set a new physical address applications store the physical address in
  48 a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` with a pointer to
  49 this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` is only available if
  50 ``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned
  51 otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can only be called
  52 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 an existing physical address use ``CEC_PHYS_ADDR_INVALID``.
  56 The adapter will go to the unconfigured state.
  57
  58 If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`),
  59 then this ioctl will block until all
  60 requested logical addresses have been claimed. If the file descriptor is in non-blocking mode
  61 then it will 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 physical address
  64 changes.
  65
  66 The physical address is a 16-bit number where each group of 4 bits
  67 represent a digit of the physical address a.b.c.d where the most
  68 significant 4 bits represent 'a'. The CEC root device (usually the TV)
  69 has address 0.0.0.0. Every device that is hooked up to an input of the
  70 TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in
  71 turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep
  72 is supported. The physical address a device shall use is stored in the
  73 EDID of the sink.
  74
  75 For example, the EDID for each HDMI input of the TV will have a
  76 different physical address of the form a.0.0.0 that the sources will
  77 read out and use as their physical address.
  78
  79
  80 Return Value
  81 ============
  82
  83 On success 0 is returned, on error -1 and the ``errno`` variable is set
  84 appropriately. The generic error codes are described at the
  85 :ref:`Generic Error Codes <gen-errors>` chapter.