ioctl CEC_ADAP_G_CAPS

이름, 선언과 인자

`CEC_ADAP_G_CAPS`는 CEC device capability를 조회하는 ioctl입니다. 모든 CEC device가 반드시 지원해야 하는 기본 request입니다.

함수 형태는 `int ioctl(int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp)`입니다. `fd`는 `open()`이 반환한 file descriptor이고 `argp`는 결과를 받을 `struct cec_caps` pointer입니다.

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

.. _CEC_ADAP_G_CAPS:

*********************
ioctl CEC_ADAP_G_CAPS
*********************

Name
====

CEC_ADAP_G_CAPS - Query device capabilities

Synopsis
========

.. c:macro:: CEC_ADAP_G_CAPS

``int ioctl(int fd, CEC_ADAP_G_CAPS, struct cec_caps *argp)``

Arguments
=========

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

``argp``

조회 동작

응용 프로그램은 device 정보를 조회하기 위해 `struct cec_caps` pointer로 이 ioctl을 호출합니다.

driver가 구조체를 채워 응용 프로그램에 반환합니다. 원문은 이 ioctl이 실패하지 않는다고 명시합니다.

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

All cec devices must support :ref:`ioctl CEC_ADAP_G_CAPS <CEC_ADAP_G_CAPS>`. To query
device information, applications call the ioctl with a pointer to a
struct :c:type:`cec_caps`. The driver fills the structure and
returns the information to the application. The ioctl never fails.

.. tabularcolumns:: |p{1.2cm}|p{2.5cm}|p{13.6cm}|

.. c:type:: cec_caps

struct cec_caps

`driver[32]`는 CEC adapter driver 이름이고 `name[32]`은 이 CEC adapter의 이름입니다. `driver`와 `name`의 조합은 고유해야 합니다.

`available_log_addrs`는 설정할 수 있는 logical address의 최대 개수입니다. `capabilities`는 adapter capability bit 집합입니다.

`version`은 CEC Framework API version이며 `KERNEL_VERSION()` macro 형식으로 저장됩니다.

.. flat-table:: struct cec_caps
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 16

    * - char
      - ``driver[32]``
      - The name of the cec adapter driver.
    * - char
      - ``name[32]``
      - The name of this CEC adapter. The combination ``driver`` and
	``name`` must be unique.
    * - __u32
      - ``available_log_addrs``
      - The maximum number of logical addresses that can be configured.
    * - __u32
      - ``capabilities``
      - The capabilities of the CEC adapter, see
	:ref:`cec-capabilities`.
    * - __u32
      - ``version``
      - CEC Framework API version, formatted with the ``KERNEL_VERSION()``
	macro.

물리·논리 주소와 전송 capability

`CEC_CAP_PHYS_ADDR` 값은 `0x00000001`입니다. 설정되어 있으면 사용자 공간이 `CEC_ADAP_S_PHYS_ADDR`로 physical address를 구성해야 합니다.

이 bit가 없으면 kernel이 HDMI receiver의 EDID를 설정하거나 HDMI transmitter의 EDID를 읽을 때 physical address를 설정합니다.

`CEC_CAP_LOG_ADDRS` 값은 `0x00000002`입니다. 설정되어 있으면 사용자 공간이 `CEC_ADAP_S_LOG_ADDRS`로 logical address를 구성해야 하며, 없으면 kernel이 이미 구성합니다.

`CEC_CAP_TRANSMIT` 값은 `0x00000004`입니다. 설정되어 있으면 사용자 공간이 `CEC_TRANSMIT`으로 CEC message를 전송할 수 있습니다.

message 전송은 follower가 되기 위한 전제이므로 이 bit는 사용자 공간 follower 지원도 함축합니다. bit가 없으면 kernel이 모든 CEC 전송과 수신 message 처리를 담당합니다.

.. tabularcolumns:: |p{4.4cm}|p{2.5cm}|p{10.4cm}|

.. _cec-capabilities:

.. flat-table:: CEC Capabilities Flags
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 8

    * .. _`CEC-CAP-PHYS-ADDR`:

      - ``CEC_CAP_PHYS_ADDR``
      - 0x00000001
      - Userspace has to configure the physical address by calling
	:ref:`ioctl CEC_ADAP_S_PHYS_ADDR <CEC_ADAP_S_PHYS_ADDR>`. If
	this capability isn't set, then setting the physical address is
	handled by the kernel whenever the EDID is set (for an HDMI
	receiver) or read (for an HDMI transmitter).
    * .. _`CEC-CAP-LOG-ADDRS`:

      - ``CEC_CAP_LOG_ADDRS``
      - 0x00000002
      - Userspace has to configure the logical addresses by calling
	:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`. If
	this capability isn't set, then the kernel will have configured
	this.
    * .. _`CEC-CAP-TRANSMIT`:

      - ``CEC_CAP_TRANSMIT``
      - 0x00000004
      - Userspace can transmit CEC messages by calling
	:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. This implies that
	userspace can be a follower as well, since being able to transmit
	messages is a prerequisite of becoming a follower. If this
	capability isn't set, then the kernel will handle all CEC
	transmits and process all CEC messages it receives.

Passthrough, remote control과 monitoring

`CEC_CAP_PASSTHROUGH` 값은 `0x00000008`이며 사용자 공간이 `CEC_S_MODE` ioctl로 passthrough mode를 사용할 수 있음을 뜻합니다.

`CEC_CAP_RC` 값은 `0x00000010`이며 adapter가 remote control protocol을 지원함을 뜻합니다.

`CEC_CAP_MONITOR_ALL` 값은 `0x00000020`입니다. CEC hardware가 directed message와 broadcast message뿐 아니라 모든 message를 monitor할 수 있습니다.

`CEC_CAP_NEEDS_HPD` 값은 `0x00000040`입니다. HDMI Hotplug Detect pin이 high일 때만 CEC hardware가 활성화됩니다.

standby mode에서 HPD를 low로 내리면서 CEC bus는 유지하는 display는 이 hardware에서 CEC로 깨울 수 없습니다.

    * .. _`CEC-CAP-PASSTHROUGH`:

      - ``CEC_CAP_PASSTHROUGH``
      - 0x00000008
      - Userspace can use the passthrough mode by calling
	:ref:`ioctl CEC_S_MODE <CEC_S_MODE>`.
    * .. _`CEC-CAP-RC`:

      - ``CEC_CAP_RC``
      - 0x00000010
      - This adapter supports the remote control protocol.
    * .. _`CEC-CAP-MONITOR-ALL`:

      - ``CEC_CAP_MONITOR_ALL``
      - 0x00000020
      - The CEC hardware can monitor all messages, not just directed and
	broadcast messages.
    * .. _`CEC-CAP-NEEDS-HPD`:

      - ``CEC_CAP_NEEDS_HPD``
      - 0x00000040
      - The CEC hardware is only active if the HDMI Hotplug Detect pin is
        high. This makes it impossible to use CEC to wake up displays that
	set the HPD pin low when in standby mode, but keep the CEC bus
	alive.

Pin, connector와 vendor reply capability

`CEC_CAP_MONITOR_PIN` 값은 `0x00000080`입니다. CEC hardware가 CEC pin의 low-to-high 및 high-to-low voltage 변화를 monitor할 수 있습니다.

pin monitoring mode에서는 응용 프로그램이 `CEC_EVENT_PIN_CEC_LOW`와 `CEC_EVENT_PIN_CEC_HIGH` event를 받습니다.

`CEC_CAP_CONNECTOR_INFO` 값은 `0x00000100`이며 설정되어 있을 때 `CEC_ADAP_G_CONNECTOR_INFO`를 사용할 수 있습니다.

`CEC_CAP_REPLY_VENDOR_ID` 값은 `0x00000200`이며 설정되어 있을 때 `CEC_MSG_FL_REPLY_VENDOR_ID` message flag를 사용할 수 있습니다.

    * .. _`CEC-CAP-MONITOR-PIN`:

      - ``CEC_CAP_MONITOR_PIN``
      - 0x00000080
      - The CEC hardware can monitor CEC pin changes from low to high voltage
        and vice versa. When in pin monitoring mode the application will
	receive ``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events.
    * .. _`CEC-CAP-CONNECTOR-INFO`:

      - ``CEC_CAP_CONNECTOR_INFO``
      - 0x00000100
      - If this capability is set, then :ref:`CEC_ADAP_G_CONNECTOR_INFO` can
        be used.
    * .. _`CEC-CAP-REPLY-VENDOR-ID`:

      - ``CEC_CAP_REPLY_VENDOR_ID``
      - 0x00000200
      - If this capability is set, then
        :ref:`CEC_MSG_FL_REPLY_VENDOR_ID <cec-msg-flags>` can be used.

반환값

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

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.