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/userspace-api/media/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****************************************************
15ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR
16****************************************************
17
18Name
19====
20
21CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address
22
23
24Synopsis
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
33Arguments
34=========
35
36``fd``
37    File descriptor returned by :c:func:`open() <cec-open>`.
38
39``argp``
40    Pointer to the CEC address.
41
42Description
43===========
44
45To 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
47driver stores the physical address.
48
49To set a new physical address applications store the physical address in
50a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` with a pointer to
51this 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
53otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can only be called
54by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
55the ``EBUSY`` error code will be returned.
56
57To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``.
58The adapter will go to the unconfigured state.
59
60If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`),
61then this ioctl will block until all
62requested logical addresses have been claimed. If the file descriptor is in non-blocking mode
63then it will not wait for the logical addresses to be claimed, instead it just returns 0.
64
65A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the physical address
66changes.
67
68The physical address is a 16-bit number where each group of 4 bits
69represent a digit of the physical address a.b.c.d where the most
70significant 4 bits represent 'a'. The CEC root device (usually the TV)
71has address 0.0.0.0. Every device that is hooked up to an input of the
72TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in
73turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep
74is supported. The physical address a device shall use is stored in the
75EDID of the sink.
76
77For example, the EDID for each HDMI input of the TV will have a
78different physical address of the form a.0.0.0 that the sources will
79read out and use as their physical address.
80
81
82Return Value
83============
84
85On success 0 is returned, on error -1 and the ``errno`` variable is set
86appropriately. The generic error codes are described at the
87:ref:`Generic Error Codes <gen-errors>` chapter.
88
89The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can return the following
90error codes:
91
92ENOTTY
93    The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported.
94
95EBUSY
96    Another filehandle is in exclusive follower or initiator mode, or the filehandle
97    is in mode ``CEC_MODE_NO_INITIATOR``.
98
99EINVAL
100    The physical address is malformed.
101