ioctl CEC_ADAP_G_PHYS_ADDR와 CEC_ADAP_S_PHYS_ADDR

이름, 선언과 인자

`CEC_ADAP_G_PHYS_ADDR`와 `CEC_ADAP_S_PHYS_ADDR`는 CEC adapter의 physical address를 각각 가져오고 설정하는 ioctl입니다.

조회 함수 형태는 `int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)`이고 설정은 request만 `CEC_ADAP_S_PHYS_ADDR`로 바뀝니다.

`fd`는 `open()`이 반환한 file descriptor이고 `argp`는 16-bit CEC address를 가리키는 pointer입니다.

.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
.. c:namespace:: CEC

.. _CEC_ADAP_PHYS_ADDR:
.. _CEC_ADAP_G_PHYS_ADDR:
.. _CEC_ADAP_S_PHYS_ADDR:

****************************************************
ioctls CEC_ADAP_G_PHYS_ADDR and CEC_ADAP_S_PHYS_ADDR
****************************************************

Name
====

CEC_ADAP_G_PHYS_ADDR, CEC_ADAP_S_PHYS_ADDR - Get or set the physical address

Synopsis
========

.. c:macro:: CEC_ADAP_G_PHYS_ADDR

``int ioctl(int fd, CEC_ADAP_G_PHYS_ADDR, __u16 *argp)``

.. c:macro:: CEC_ADAP_S_PHYS_ADDR

``int ioctl(int fd, CEC_ADAP_S_PHYS_ADDR, __u16 *argp)``

Arguments
=========

``fd``
    File descriptor returned by :c:func:`open()`.

``argp``
    Pointer to the CEC address.

조회·설정과 상태 변경

조회 시 응용 프로그램은 `__u16` pointer로 `CEC_ADAP_G_PHYS_ADDR`를 호출하고 driver가 현재 physical address를 저장합니다.

설정 시 응용 프로그램은 `__u16`에 새 address를 저장해 `CEC_ADAP_S_PHYS_ADDR`를 호출합니다. `CEC_CAP_PHYS_ADDR` capability가 없으면 `ENOTTY`를 반환합니다.

설정 ioctl은 initiator mode인 descriptor에서만 호출할 수 있으며 그렇지 않으면 `EBUSY`입니다.

기존 physical address를 지우려면 `CEC_PHYS_ADDR_INVALID`를 설정합니다. 그러면 adapter는 unconfigured state가 됩니다.

logical address type이 정의된 상태라면 설정 ioctl은 요청된 logical address를 모두 claim할 때까지 block합니다. nonblocking descriptor에서는 기다리지 않고 0을 반환합니다.

physical address가 변경되면 `CEC_EVENT_STATE_CHANGE` event를 보냅니다.

Description
===========

To query the current physical address applications call
:ref:`ioctl CEC_ADAP_G_PHYS_ADDR <CEC_ADAP_G_PHYS_ADDR>` with a pointer to a __u16 where the
driver stores the physical address.

To set a new physical address applications store the physical address in
a __u16 and call :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` with a pointer to
this integer. The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` is only available if
``CEC_CAP_PHYS_ADDR`` is set (the ``ENOTTY`` error code will be returned
otherwise). The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can only be called
by a file descriptor in initiator mode (see :ref:`CEC_S_MODE`), if not
the ``EBUSY`` error code will be returned.

To clear an existing physical address use ``CEC_PHYS_ADDR_INVALID``.
The adapter will go to the unconfigured state.

If logical address types have been defined (see :ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`),
then this ioctl will block until all
requested logical addresses have been claimed. If the file descriptor is in non-blocking mode
then it will not wait for the logical addresses to be claimed, instead it just returns 0.

A :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` event is sent when the physical address
changes.

16-bit physical address topology

CEC physical address는 16-bit 값이며 각 4-bit group이 `a.b.c.d`의 한 digit을 나타냅니다. 가장 높은 4 bit가 `a`입니다.

CEC root device, 보통 TV의 address는 `0.0.0.0`입니다. TV input에 직접 연결된 device는 `a.0.0.0`이며 `a`는 1 이상입니다.

그 아래 device는 `a.b.0.0`, 다음은 `a.b.c.0` 방식으로 계층을 표현하므로 최대 5개 device 깊이의 topology를 지원합니다.

device가 사용할 physical address는 sink의 EDID에 저장됩니다. 예를 들어 TV의 각 HDMI input EDID에는 서로 다른 `a.0.0.0` address가 들어 있고 source가 이를 읽어 자신의 address로 사용합니다.

The physical address is a 16-bit number where each group of 4 bits
represent a digit of the physical address a.b.c.d where the most
significant 4 bits represent 'a'. The CEC root device (usually the TV)
has address 0.0.0.0. Every device that is hooked up to an input of the
TV has address a.0.0.0 (where 'a' is ≥ 1), devices hooked up to those in
turn have addresses a.b.0.0, etc. So a topology of up to 5 devices deep
is supported. The physical address a device shall use is stored in the
EDID of the sink.

For example, the EDID for each HDMI input of the TV will have a
different physical address of the form a.0.0.0 that the sources will
read out and use as their physical address.

반환값과 오류

성공하면 0, 오류이면 -1을 반환하고 `errno`를 설정합니다. 일반 오류는 Generic Error Codes 장을 참조합니다.

`ENOTTY`는 `CEC_CAP_PHYS_ADDR` capability가 없어 설정 ioctl을 지원하지 않음을 뜻합니다.

`EBUSY`는 다른 filehandle이 exclusive follower 또는 initiator mode이거나 현재 filehandle이 `CEC_MODE_NO_INITIATOR`인 경우입니다.

`EINVAL`은 physical address 형식이 잘못됐음을 뜻합니다.

Return Value
============

On success 0 is returned, on error -1 and the ``errno`` variable is set
appropriately. The generic error codes are described at the
:ref:`Generic Error Codes <gen-errors>` chapter.

The :ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>` can return the following
error codes:

ENOTTY
    The ``CEC_CAP_PHYS_ADDR`` capability wasn't set, so this ioctl is not supported.

EBUSY
    Another filehandle is in exclusive follower or initiator mode, or the filehandle
    is in mode ``CEC_MODE_NO_INITIATOR``.

EINVAL
    The physical address is malformed.