ioctl CEC_DQEVENT

이름, 선언과 인자

`CEC_DQEVENT`는 CEC 비동기 event 하나를 queue에서 꺼내는 ioctl입니다.

함수 형태는 `int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)`입니다. `fd`는 `open()`이 반환한 descriptor이고 `argp`는 event 결과 구조체 pointer입니다.

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

.. _CEC_DQEVENT:

*****************
ioctl CEC_DQEVENT
*****************

Name
====

CEC_DQEVENT - Dequeue a CEC event

Synopsis
========

.. c:macro:: CEC_DQEVENT

``int ioctl(int fd, CEC_DQEVENT, struct cec_event *argp)``

Arguments
=========

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

``argp``

비동기 queue와 overwrite 보장

CEC device는 비동기 event를 보낼 수 있고 응용 프로그램은 `CEC_DQEVENT`로 이를 가져옵니다.

descriptor가 nonblocking mode이고 pending event가 없으면 -1을 반환하며 `errno`를 `EAGAIN`으로 설정합니다.

내부 event queue는 filehandle별이면서 event type별입니다. queue에 공간이 없으면 마지막 event를 새 event로 덮어씁니다.

따라서 중간 결과는 버릴 수 있지만 가장 최신 event는 항상 얻을 수 있습니다.

같은 값을 가진 event 두 개를 연속으로 읽을 수도 있습니다. 예를 들어 같은 state의 `CEC_EVENT_STATE_CHANGE` 두 개 사이에서 중간 state change가 유실됐을 수 있지만, 두 event 사이에 실제 state가 변경됐음은 보장됩니다.

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

CEC devices can send asynchronous events. These can be retrieved by
calling :c:func:`CEC_DQEVENT`. If the file descriptor is in
non-blocking mode and no event is pending, then it will return -1 and
set errno to the ``EAGAIN`` error code.

The internal event queues are per-filehandle and per-event type. If
there is no more room in a queue then the last event is overwritten with
the new one. This means that intermediate results can be thrown away but
that the latest event is always available. This also means that is it
possible to read two successive events that have the same value (e.g.
two :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>` events with
the same state). In that case the intermediate state changes were lost but
it is guaranteed that the state did change in between the two events.

struct cec_event_state_change

`phys_addr`는 현재 physical address이며 유효한 주소가 없으면 `CEC_PHYS_ADDR_INVALID`입니다.

`log_addr_mask`는 현재 claim한 logical address 집합입니다. claim한 address가 없거나 `phys_addr`가 invalid이면 0입니다.

bit 15, 즉 `1 << CEC_LOG_ADDR_UNREGISTERED`가 설정되면 device가 unregistered logical address를 가진 것이며 다른 bit는 모두 0입니다.

`have_conn_info`가 0이 아니면 HDMI connector 정보를 사용할 수 있습니다. 이 필드는 `CEC_CAP_CONNECTOR_INFO` capability가 있을 때만 유효합니다.

capability가 있는데 `have_conn_info`가 0이면 HDMI driver가 아직 device를 configure 중이거나 HDMI device가 unbind되어 connector device가 instantiate되지 않은 상태입니다.

.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.2cm}|

.. c:type:: cec_event_state_change

.. flat-table:: struct cec_event_state_change
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 8

    * - __u16
      - ``phys_addr``
      - The current physical address. This is ``CEC_PHYS_ADDR_INVALID`` if no
        valid physical address is set.
    * - __u16
      - ``log_addr_mask``
      - The current set of claimed logical addresses. This is 0 if no logical
        addresses are claimed or if ``phys_addr`` is ``CEC_PHYS_ADDR_INVALID``.
	If bit 15 is set (``1 << CEC_LOG_ADDR_UNREGISTERED``) then this device
	has the unregistered logical address. In that case all other bits are 0.
    * - __u16
      - ``have_conn_info``
      - If non-zero, then HDMI connector information is available.
        This field is only valid if ``CEC_CAP_CONNECTOR_INFO`` is set. If that
        capability is set and ``have_conn_info`` is zero, then that indicates
        that the HDMI connector device is not instantiated, either because
        the HDMI driver is still configuring the device or because the HDMI
        device was unbound.

struct cec_event_lost_msgs

`lost_msgs`는 filehandle을 연 뒤 또는 이 filehandle에서 마지막으로 해당 event를 dequeue한 뒤 유실된 message 수입니다.

message queue가 가득 찬 상태에서 새 message가 오면 가장 오래된 message를 버려 공간을 만듭니다.

내부 queue 크기는 최근 2초 동안 받은 모든 message를 저장하도록 보장합니다. CEC specification은 1초 안에 reply해야 한다고 요구하므로 이 크기는 충분합니다.

.. c:type:: cec_event_lost_msgs

.. tabularcolumns:: |p{1.0cm}|p{2.0cm}|p{14.3cm}|

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

    * - __u32
      - ``lost_msgs``
      - Set to the number of lost messages since the filehandle was opened
	or since the last time this event was dequeued for this
	filehandle. The messages lost are the oldest messages. So when a
	new message arrives and there is no more room, then the oldest
	message is discarded to make room for the new one. The internal
	size of the message queue guarantees that all messages received in
	the last two seconds will be stored. Since messages should be
	replied to within a second according to the CEC specification,
	this is more than enough.

struct cec_event

`ts`는 nanosecond 단위 event timestamp이며 `CLOCK_MONOTONIC` clock에서 가져옵니다. 사용자 공간은 `clock_gettime()`으로 같은 clock에 접근할 수 있습니다.

`event`는 CEC event type이고 `flags`는 event flag입니다.

anonymous union의 `state_change` member는 `CEC_EVENT_STATE_CHANGE`가 보낸 새 adapter state를 담습니다.

`lost_msgs` member는 `CEC_EVENT_LOST_MSGS`가 보낸 유실 message 수를 담습니다.

.. tabularcolumns:: |p{1.0cm}|p{4.4cm}|p{2.5cm}|p{9.2cm}|

.. c:type:: cec_event

.. flat-table:: struct cec_event
    :header-rows:  0
    :stub-columns: 0
    :widths:       1 1 8

    * - __u64
      - ``ts``
      - Timestamp of the event in ns.

	The timestamp has been taken from the ``CLOCK_MONOTONIC`` clock.

	To access the same clock from userspace use :c:func:`clock_gettime`.
    * - __u32
      - ``event``
      - The CEC event type, see :ref:`cec-events`.
    * - __u32
      - ``flags``
      - Event flags, see :ref:`cec-event-flags`.
    * - union {
      - (anonymous)
    * - struct cec_event_state_change
      - ``state_change``
      - The new adapter state as sent by the :ref:`CEC_EVENT_STATE_CHANGE <CEC-EVENT-STATE-CHANGE>`
	event.
    * - struct cec_event_lost_msgs
      - ``lost_msgs``
      - The number of lost messages as sent by the :ref:`CEC_EVENT_LOST_MSGS <CEC-EVENT-LOST-MSGS>`
	event.
    * - }
      -

State, lost-message와 CEC pin event

`CEC_EVENT_STATE_CHANGE` 값은 1이며 CEC adapter state가 바뀔 때 생성됩니다. `open()` 시점에도 해당 filehandle에 현재 adapter state를 담은 초기 event를 생성합니다.

`CEC_EVENT_LOST_MSGS` 값은 2이며 응용 프로그램이 CEC message를 충분히 빨리 dequeue하지 않아 하나 이상 유실됐을 때 생성됩니다.

`CEC_EVENT_PIN_CEC_LOW` 값은 3이며 CEC pin이 high voltage에서 low voltage로 바뀔 때 생성됩니다.

`CEC_EVENT_PIN_CEC_HIGH` 값은 4이며 CEC pin이 low에서 high로 바뀔 때 생성됩니다. 두 CEC pin event는 `CEC_CAP_MONITOR_PIN` capability가 있는 adapter에만 적용됩니다.

.. tabularcolumns:: |p{5.6cm}|p{0.9cm}|p{10.8cm}|

.. _cec-events:

.. flat-table:: CEC Events Types
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 16

    * .. _`CEC-EVENT-STATE-CHANGE`:

      - ``CEC_EVENT_STATE_CHANGE``
      - 1
      - Generated when the CEC Adapter's state changes. When open() is
	called an initial event will be generated for that filehandle with
	the CEC Adapter's state at that time.
    * .. _`CEC-EVENT-LOST-MSGS`:

      - ``CEC_EVENT_LOST_MSGS``
      - 2
      - Generated if one or more CEC messages were lost because the
	application didn't dequeue CEC messages fast enough.
    * .. _`CEC-EVENT-PIN-CEC-LOW`:

      - ``CEC_EVENT_PIN_CEC_LOW``
      - 3
      - Generated if the CEC pin goes from a high voltage to a low voltage.
        Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
	capability set.
    * .. _`CEC-EVENT-PIN-CEC-HIGH`:

      - ``CEC_EVENT_PIN_CEC_HIGH``
      - 4
      - Generated if the CEC pin goes from a low voltage to a high voltage.
        Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
	capability set.

HPD와 5V pin event

`CEC_EVENT_PIN_HPD_LOW` 값은 5이며 HPD pin이 high에서 low로 바뀔 때 생성됩니다. `CEC_CAP_MONITOR_PIN`이 필요하고 `open()` 때 HPD가 low이면 초기 event도 생성합니다.

`CEC_EVENT_PIN_HPD_HIGH` 값은 원문에서 6으로 정의하며 HPD pin이 low에서 high로 바뀔 때 생성됩니다. `open()` 때 HPD가 high이면 초기 event를 생성합니다.

`CEC_EVENT_PIN_5V_LOW` 값도 원문에서 6으로 기재되어 있으며 5V pin이 high에서 low로 바뀔 때 생성됩니다. 원문의 numeric value를 그대로 보존합니다.

`CEC_EVENT_PIN_5V_HIGH` 값은 7이며 5V pin이 low에서 high로 바뀔 때 생성됩니다.

두 5V event도 `CEC_CAP_MONITOR_PIN`이 필요하며 `open()` 시 실제 5V pin 상태에 맞는 초기 event를 만들 수 있습니다.

    * .. _`CEC-EVENT-PIN-HPD-LOW`:

      - ``CEC_EVENT_PIN_HPD_LOW``
      - 5
      - Generated if the HPD pin goes from a high voltage to a low voltage.
	Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
	capability set. When open() is called, the HPD pin can be read and
	if the HPD is low, then an initial event will be generated for that
	filehandle.
    * .. _`CEC-EVENT-PIN-HPD-HIGH`:

      - ``CEC_EVENT_PIN_HPD_HIGH``
      - 6
      - Generated if the HPD pin goes from a low voltage to a high voltage.
	Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
	capability set. When open() is called, the HPD pin can be read and
	if the HPD is high, then an initial event will be generated for that
	filehandle.
    * .. _`CEC-EVENT-PIN-5V-LOW`:

      - ``CEC_EVENT_PIN_5V_LOW``
      - 6
      - Generated if the 5V pin goes from a high voltage to a low voltage.
	Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
	capability set. When open() is called, the 5V pin can be read and
	if the 5V is low, then an initial event will be generated for that
	filehandle.
    * .. _`CEC-EVENT-PIN-5V-HIGH`:

      - ``CEC_EVENT_PIN_5V_HIGH``
      - 7
      - Generated if the 5V pin goes from a low voltage to a high voltage.
	Only applies to adapters that have the ``CEC_CAP_MONITOR_PIN``
	capability set. When open() is called, the 5V pin can be read and
	if the 5V is high, then an initial event will be generated for that
	filehandle.

CEC event flag

`CEC_EVENT_FL_INITIAL_STATE` 값은 1이며 device를 열 때 생성되는 초기 event에 설정됩니다. 응용 프로그램은 이 flag로 `open()` 시점의 CEC adapter 초기 상태를 알 수 있습니다.

`CEC_EVENT_FL_DROPPED_EVENTS` 값은 2이며 해당 event type의 event 하나 이상이 drop됐을 때 설정됩니다. 응용 프로그램이 event 발생 속도를 따라가지 못한다는 신호입니다.

.. tabularcolumns:: |p{6.0cm}|p{0.6cm}|p{10.7cm}|

.. _cec-event-flags:

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

    * .. _`CEC-EVENT-FL-INITIAL-STATE`:

      - ``CEC_EVENT_FL_INITIAL_STATE``
      - 1
      - Set for the initial events that are generated when the device is
	opened. See the table above for which events do this. This allows
	applications to learn the initial state of the CEC adapter at
	open() time.
    * .. _`CEC-EVENT-FL-DROPPED-EVENTS`:

      - ``CEC_EVENT_FL_DROPPED_EVENTS``
      - 2
      - Set if one or more events of the given event type have been dropped.
        This is an indication that the application cannot keep up.

반환값과 오류

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

`EAGAIN`은 nonblocking filehandle에 pending event가 없을 때 반환합니다.

`ERESTARTSYS`는 blocking mode에서 event를 기다리는 동안 Ctrl-C 같은 interrupt가 도착했음을 뜻합니다.

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_DQEVENT <CEC_DQEVENT>` can return the following
error codes:

EAGAIN
    This is returned when the filehandle is in non-blocking mode and there
    are no pending events.

ERESTARTSYS
    An interrupt (e.g. Ctrl-C) arrived while in blocking mode waiting for
    events to arrive.