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

   1 .. Permission is granted to copy, distribute and/or modify this
   2 .. document under the terms of the GNU Free Documentation License,
   3 .. Version 1.1 or any later version published by the Free Software
   4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
   5 .. and no Back-Cover Texts. A copy of the license is included at
   6 .. Documentation/media/uapi/fdl-appendix.rst.
   7 ..
   8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
   9
  10 .. _CEC_ADAP_PHYS_ADDR:
  11 .. _CEC_ADAP_G_PHYS_ADDR:
  12 .. _CEC_ADAP_S_PHYS_ADDR:
  13
  14 ****************************************************
  15 ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR
  16 ****************************************************
  17
  18 Name
  19 ====
  20
  21 CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
  22
  23
  24 Synopsis
  25 ========
  26
  27 .. c:function:: int ioctl( int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp )
  28     :name: CEC_ADAP_G_PHYS_ADDR
  29
  30 .. c:function:: int ioctl( int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp )
  31     :name: CEC_ADAP_S_PHYS_ADDR
  32
  33 Arguments
  34 =========
  35
  36 ``fd``
  37     File descriptor returned by :c:func:`open() <cec-open>`.
  38
  39 ``argp``
  40     Pointer to the CEC address.
  41
  42 Description
  43 ===========
  44
  45 To query the current physical address applications call
  46 :ref:`ioctl CEC_ADAP_G_PHYS_ADDR <CEC_ADAP_G_PHYS_ADDR>` with a pointer to a __u16 where the
  47 driver stores the physical address.
  48
  49 To set a new physical address applications store the physical address in
  50 a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` with a pointer to
  51 this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` is only available if
  52 ``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned
  53 otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can only be called
  54 by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
  55 the ``EBUSY`` error code will be returned.
  56
  57 To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``.
  58 The adapter will go to the unconfigured state.
  59
  60 If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`),
  61 then this ioctl will block until all
  62 requested logical addresses have been claimed. If the file descriptor is in non-blocking mode
  63 then it will not wait for the logical addresses to be claimed, instead it just returns 0.
  64
  65 A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the physical address
  66 changes.
  67
  68 The physical address is a 16-bit number where each group of 4 bits
  69 represent a digit of the physical address a.b.c.d where the most
  70 significant 4 bits represent 'a'. The CEC root device (usually the TV)
  71 has address 0.0.0.0. Every device that is hooked up to an input of the
  72 TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in
  73 turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep
  74 is supported. The physical address a device shall use is stored in the
  75 EDID of the sink.
  76
  77 For example, the EDID for each HDMI input of the TV will have a
  78 different physical address of the form a.0.0.0 that the sources will
  79 read out and use as their physical address.
  80
  81
  82 Return Value
  83 ============
  84
  85 On success 0 is returned, on error -1 and the ``errno`` variable is set
  86 appropriately. The generic error codes are described at the
  87 :ref:`Generic Error Codes <gen-errors>` chapter.
  88
  89 The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can return the following
  90 error codes:
  91
  92 ENOTTY
  93     The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported.
  94
  95 EBUSY
  96     Another filehandle is in exclusive follower or initiator mode, or the filehandle
  97     is in mode ``CEC_MODE_NO_INITIATOR``.
  98
  99 EINVAL
 100     The physical address is malformed.