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