0001 .. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
0002 .. c:namespace:: CEC
0003
0004 .. _CEC_ADAP_PHYS_ADDR:
0005 .. _CEC_ADAP_G_PHYS_ADDR:
0006 .. _CEC_ADAP_S_PHYS_ADDR:
0007
0008 ****************************************************
0009 ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR
0010 ****************************************************
0011
0012 Name
0013 ====
0014
0015 CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
0016
0017 Synopsis
0018 ========
0019
0020 .. c:macro:: CEC_ADAP_G_PHYS_ADDR
0021
0022 ``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)``
0023
0024 .. c:macro:: CEC_ADAP_S_PHYS_ADDR
0025
0026 ``int ioctl(int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp)``
0027
0028 Arguments
0029 =========
0030
0031 ``fd``
0032 File descriptor returned by :c:func:`open()`.
0033
0034 ``argp``
0035 Pointer to the CEC address.
0036
0037 Description
0038 ===========
0039
0040 To query the current physical address applications call
0041 :ref:`ioctl CEC_ADAP_G_PHYS_ADDR <CEC_ADAP_G_PHYS_ADDR>` with a pointer to a __u16 where the
0042 driver stores the physical address.
0043
0044 To set a new physical address applications store the physical address in
0045 a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` with a pointer to
0046 this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` is only available if
0047 ``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned
0048 otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can only be called
0049 by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
0050 the ``EBUSY`` error code will be returned.
0051
0052 To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``.
0053 The adapter will go to the unconfigured state.
0054
0055 If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`),
0056 then this ioctl will block until all
0057 requested logical addresses have been claimed. If the file descriptor is in non-blocking mode
0058 then it will not wait for the logical addresses to be claimed, instead it just returns 0.
0059
0060 A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the physical address
0061 changes.
0062
0063 The physical address is a 16-bit number where each group of 4 bits
0064 represent a digit of the physical address a.b.c.d where the most
0065 significant 4 bits represent 'a'. The CEC root device (usually the TV)
0066 has address 0.0.0.0. Every device that is hooked up to an input of the
0067 TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in
0068 turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep
0069 is supported. The physical address a device shall use is stored in the
0070 EDID of the sink.
0071
0072 For example, the EDID for each HDMI input of the TV will have a
0073 different physical address of the form a.0.0.0 that the sources will
0074 read out and use as their physical address.
0075
0076 Return Value
0077 ============
0078
0079 On success 0 is returned, on error -1 and the ``errno`` variable is set
0080 appropriately. The generic error codes are described at the
0081 :ref:`Generic Error Codes <gen-errors>` chapter.
0082
0083 The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can return the following
0084 error codes:
0085
0086 ENOTTY
0087 The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported.
0088
0089 EBUSY
0090 Another filehandle is in exclusive follower or initiator mode, or the filehandle
0091 is in mode ``CEC_MODE_NO_INITIATOR``.
0092
0093 EINVAL
0094 The physical address is malformed.
