ioctls CEC_G_MODE와 CEC_S_MODE

이름, 선언과 인자

이 문서는 CEC namespace의 `CEC_G_MODE`와 `CEC_S_MODE` ioctl을 정의합니다. 두 ioctl은 CEC adapter를 배타적으로 사용할 수 있는 filehandle mode를 각각 조회하거나 설정합니다.

조회 호출 형식은 `int ioctl(int fd, CEC_G_MODE, __u32 *argp)`이고 설정 호출은 같은 인자에서 request만 `CEC_S_MODE`로 바뀝니다.

`fd`는 `open()`이 반환한 file descriptor이며, `argp`는 조회하거나 설정할 32-bit CEC mode를 가리키는 pointer입니다.

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

.. _CEC_MODE:
.. _CEC_G_MODE:
.. _CEC_S_MODE:

********************************
ioctls CEC_G_MODE and CEC_S_MODE
********************************

CEC_G_MODE, CEC_S_MODE - Get or set exclusive use of the CEC adapter

Synopsis
========

.. c:macro:: CEC_G_MODE

``int ioctl(int fd, CEC_G_MODE, __u32 *argp)``

.. c:macro:: CEC_S_MODE

``int ioctl(int fd, CEC_S_MODE, __u32 *argp)``

Arguments
=========

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

``argp``
    Pointer to CEC mode.

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

Initiator·follower 역할과 message 전달

기본적으로 모든 filehandle이 `CEC_TRANSMIT`을 사용할 수 있지만, 여러 응용 프로그램이 서로 간섭하지 않도록 CEC adapter에 대한 exclusive access가 필요할 수 있습니다. `CEC_S_MODE`는 filehandle을 initiator와 follower 중 하나 또는 둘 다로 만들며, 선택한 mode에 따라 각 역할은 exclusive가 될 수 있습니다.

initiator는 다른 CEC device에 명령하는 message를 시작하는 filehandle이고, follower는 CEC adapter로 전송된 message를 받아 처리하는 filehandle입니다. 한 filehandle이 두 역할을 모두 맡을 수도 있고 서로 다른 두 filehandle이 나누어 맡을 수도 있습니다.

수신 message가 앞서 전송한 message의 reply라면 reply를 기다리던 filehandle로 돌려보내며 CEC framework도 그 message를 처리합니다.

reply가 아니면 framework가 먼저 처리합니다. follower가 없고 framework도 처리하지 못했다면 message를 버리고 initiator에 Feature Abort를 보냅니다. follower가 있으면 follower의 queue로 전달하며 follower는 `CEC_RECEIVE`로 dequeue한 뒤 올바른 처리를 결정해야 합니다.

CEC framework는 follower가 달리 요청하지 않는 한 core message를 처리합니다. follower가 passthrough mode를 켜면 대부분의 core message를 처리하지 않고 넘기므로 follower가 직접 구현해야 합니다. 다만 passthrough와 관계없이 core가 항상 처리하는 일부 message가 있으며 뒤의 `cec-core-processing` 표가 이를 구분합니다.

exclusive initiator가 없으면 어떤 CEC filehandle도 `CEC_TRANSMIT`을 호출할 수 있습니다. exclusive initiator가 있으면 그 initiator만 호출할 수 있지만 follower는 항상 `CEC_TRANSMIT`을 호출할 수 있습니다.

By default any filehandle can use :ref:`CEC_TRANSMIT`, but in order to prevent
applications from stepping on each others toes it must be possible to
obtain exclusive access to the CEC adapter. This ioctl sets the
filehandle to initiator and/or follower mode which can be exclusive
depending on the chosen mode. The initiator is the filehandle that is
used to initiate messages, i.e. it commands other CEC devices. The
follower is the filehandle that receives messages sent to the CEC
adapter and processes them. The same filehandle can be both initiator
and follower, or this role can be taken by two different filehandles.

When a CEC message is received, then the CEC framework will decide how
it will be processed. If the message is a reply to an earlier
transmitted message, then the reply is sent back to the filehandle that
is waiting for it. In addition the CEC framework will process it.

If the message is not a reply, then the CEC framework will process it
first. If there is no follower, then the message is just discarded and a
feature abort is sent back to the initiator if the framework couldn't
process it. If there is a follower, then the message is passed on to the
follower who will use :ref:`ioctl CEC_RECEIVE <CEC_RECEIVE>` to dequeue
the new message. The framework expects the follower to make the right
decisions.

The CEC framework will process core messages unless requested otherwise
by the follower. The follower can enable the passthrough mode. In that
case, the CEC framework will pass on most core messages without
processing them and the follower will have to implement those messages.
There are some messages that the core will always process, regardless of
the passthrough mode. See :ref:`cec-core-processing` for details.

If there is no initiator, then any CEC filehandle can use
:ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`. If there is an exclusive
initiator then only that initiator can call
:ref:`CEC_TRANSMIT`. The follower can of course
always call :ref:`ioctl CEC_TRANSMIT <CEC_TRANSMIT>`.

Initiator mode

initiator mode는 하위 4 bit에 들어가며 `CEC_MODE_NO_INITIATOR`, `CEC_MODE_INITIATOR`, `CEC_MODE_EXCL_INITIATOR` 세 값을 사용합니다.

`CEC_MODE_NO_INITIATOR`(0x0)는 initiator가 아니므로 CEC message를 전송하거나 CEC adapter의 다른 설정을 바꿀 수 없습니다.

`CEC_MODE_INITIATOR`(0x1)는 device를 열 때의 기본값입니다. exclusive initiator가 없는 동안 CEC message를 전송하고 adapter를 변경할 수 있습니다.

`CEC_MODE_EXCL_INITIATOR`(0x2)는 이 file descriptor 하나만 message를 전송하고 adapter를 변경하게 합니다. 다른 descriptor가 이미 exclusive initiator라면 새 요청은 `EBUSY`로 실패합니다.

Available initiator modes are:

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

.. _cec-mode-initiator_e:

.. flat-table:: Initiator Modes
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 16

    * .. _`CEC-MODE-NO-INITIATOR`:

      - ``CEC_MODE_NO_INITIATOR``
      - 0x0
      - This is not an initiator, i.e. it cannot transmit CEC messages or
	make any other changes to the CEC adapter.
    * .. _`CEC-MODE-INITIATOR`:

      - ``CEC_MODE_INITIATOR``
      - 0x1
      - This is an initiator (the default when the device is opened) and
	it can transmit CEC messages and make changes to the CEC adapter,
	unless there is an exclusive initiator.
    * .. _`CEC-MODE-EXCL-INITIATOR`:

      - ``CEC_MODE_EXCL_INITIATOR``
      - 0x2
      - This is an exclusive initiator and this file descriptor is the
	only one that can transmit CEC messages and make changes to the
	CEC adapter. If someone else is already the exclusive initiator
	then an attempt to become one will return the ``EBUSY`` error code
	error.

Follower와 passthrough mode

follower mode는 상위 nibble에 들어갑니다. device를 열 때 기본값인 `CEC_MODE_NO_FOLLOWER`(0x00)는 follower가 아닙니다.

`CEC_MODE_FOLLOWER`(0x10)는 exclusive follower가 없을 때 CEC message를 받습니다. `CEC_CAP_TRANSMIT` capability가 없거나 initiator mode로 `CEC_MODE_NO_INITIATOR`를 지정했다면 follower가 될 수 없고 `EINVAL`을 반환합니다.

`CEC_MODE_EXCL_FOLLOWER`(0x20)는 이 file descriptor만 처리할 CEC message를 받게 합니다. 다른 exclusive follower가 있으면 `EBUSY`이며, capability와 initiator 조합에 대한 `EINVAL` 조건은 일반 follower와 같습니다.

`CEC_MODE_EXCL_FOLLOWER_PASSTHRU`(0x30)는 exclusive follower에 passthrough를 더합니다. 이 descriptor만 message를 받고, 대부분의 core message를 CEC framework 대신 직접 처리합니다. 기존 exclusive follower가 있으면 `EBUSY`, `CEC_CAP_TRANSMIT`이 없거나 `CEC_MODE_NO_INITIATOR`와 결합하면 `EINVAL`입니다.

Available follower modes are:

.. tabularcolumns:: |p{6.6cm}|p{0.9cm}|p{9.8cm}|

.. _cec-mode-follower_e:

.. cssclass:: longtable

.. flat-table:: Follower Modes
    :header-rows:  0
    :stub-columns: 0
    :widths:       3 1 16

    * .. _`CEC-MODE-NO-FOLLOWER`:

      - ``CEC_MODE_NO_FOLLOWER``
      - 0x00
      - This is not a follower (the default when the device is opened).
    * .. _`CEC-MODE-FOLLOWER`:

      - ``CEC_MODE_FOLLOWER``
      - 0x10
      - This is a follower and it will receive CEC messages unless there
	is an exclusive follower. You cannot become a follower if
	:ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
	was specified, the ``EINVAL`` error code is returned in that case.
    * .. _`CEC-MODE-EXCL-FOLLOWER`:

      - ``CEC_MODE_EXCL_FOLLOWER``
      - 0x20
      - This is an exclusive follower and only this file descriptor will
	receive CEC messages for processing. If someone else is already
	the exclusive follower then an attempt to become one will return
	the ``EBUSY`` error code. You cannot become a follower if
	:ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>` is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`
	was specified, the ``EINVAL`` error code is returned in that case.
    * .. _`CEC-MODE-EXCL-FOLLOWER-PASSTHRU`:

      - ``CEC_MODE_EXCL_FOLLOWER_PASSTHRU``
      - 0x30
      - This is an exclusive follower and only this file descriptor will
	receive CEC messages for processing. In addition it will put the
	CEC device into passthrough mode, allowing the exclusive follower
	to handle most core messages instead of relying on the CEC
	framework for that. If someone else is already the exclusive
	follower then an attempt to become one will return the ``EBUSY`` error
	code. You cannot become a follower if :ref:`CEC_CAP_TRANSMIT <CEC-CAP-TRANSMIT>`
	is not set or if :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>` was specified,
	the ``EINVAL`` error code is returned in that case.

Pin monitor와 message monitor mode

`CEC_MODE_MONITOR_PIN`(0xd0)은 low-level CEC pin transition을 관찰합니다. `CEC_MODE_NO_INITIATOR`와만 결합할 수 있으며, 그렇지 않으면 `EINVAL`입니다. `CEC_CAP_MONITOR_PIN` capability도 필수이고 없으면 `EINVAL`입니다.

pin monitoring 중에는 `CEC_EVENT_PIN_CEC_LOW`와 `CEC_EVENT_PIN_CEC_HIGH` event로 CEC pin의 low/high 전이를 받을 수 있어 debugging에 유용합니다. 이 mode는 process가 `CAP_NET_ADMIN` capability를 가질 때만 허용되며, 없으면 `EPERM`입니다.

`CEC_MODE_MONITOR`(0xe0)은 해당 CEC device가 전송한 모든 message와 수신한 broadcast message 및 자기 logical address 대상 directed message를 보고합니다. `CEC_MODE_NO_INITIATOR`와만 결합할 수 있고 `CAP_NET_ADMIN`이 필요하며 위반 시 각각 `EINVAL`과 `EPERM`입니다.

`CEC_MODE_MONITOR_ALL`(0xf0)은 다른 CEC device를 대상으로 한 directed message까지 포함하여 adapter가 볼 수 있는 모든 송수신 message를 보고합니다. 모든 device가 이 기능을 지원하는 것은 아니며 `CEC_CAP_MONITOR_ALL`이 없으면 `EINVAL`입니다. 이 mode 역시 `CEC_MODE_NO_INITIATOR`와 `CAP_NET_ADMIN`이 필요합니다.

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

      - ``CEC_MODE_MONITOR_PIN``
      - 0xd0
      - Put the file descriptor into pin monitoring mode. Can only be used in
	combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
	otherwise the ``EINVAL`` error code will be returned.
	This mode requires that the :ref:`CEC_CAP_MONITOR_PIN <CEC-CAP-MONITOR-PIN>`
	capability is set, otherwise the ``EINVAL`` error code is returned.
	While in pin monitoring mode this file descriptor can receive the
	``CEC_EVENT_PIN_CEC_LOW`` and ``CEC_EVENT_PIN_CEC_HIGH`` events to see the
	low-level CEC pin transitions. This is very useful for debugging.
	This mode is only allowed if the process has the ``CAP_NET_ADMIN``
	capability. If that is not set, then the ``EPERM`` error code is returned.
    * .. _`CEC-MODE-MONITOR`:

      - ``CEC_MODE_MONITOR``
      - 0xe0
      - Put the file descriptor into monitor mode. Can only be used in
	combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`,
	otherwise the ``EINVAL`` error code will be returned.
	In monitor mode all messages this CEC
	device transmits and all messages it receives (both broadcast
	messages and directed messages for one its logical addresses) will
	be reported. This is very useful for debugging. This is only
	allowed if the process has the ``CAP_NET_ADMIN`` capability. If
	that is not set, then the ``EPERM`` error code is returned.
    * .. _`CEC-MODE-MONITOR-ALL`:

      - ``CEC_MODE_MONITOR_ALL``
      - 0xf0
      - Put the file descriptor into 'monitor all' mode. Can only be used
	in combination with :ref:`CEC_MODE_NO_INITIATOR <CEC-MODE-NO-INITIATOR>`, otherwise
	the ``EINVAL`` error code will be returned. In 'monitor all' mode all messages
	this CEC device transmits and all messages it receives, including
	directed messages for other CEC devices, will be reported. This is
	very useful for debugging, but not all devices support this. This
	mode requires that the :ref:`CEC_CAP_MONITOR_ALL <CEC-CAP-MONITOR-ALL>` capability is set,
	otherwise the ``EINVAL`` error code is returned. This is only allowed if
	the process has the ``CAP_NET_ADMIN`` capability. If that is not
	set, then the ``EPERM`` error code is returned.

Core가 처리하는 identity message

다음 표는 CEC framework의 core message 처리 규칙을 설명합니다. passthrough mode에서는 표시된 identity query를 core가 처리하지 않으므로 follower가 대신 응답해야 합니다.

`CEC_MSG_GET_CEC_VERSION`은 `CEC_ADAP_S_LOG_ADDRS`로 설정한 CEC version을 응답합니다. `CEC_MSG_GIVE_DEVICE_VENDOR_ID`는 같은 ioctl로 설정한 vendor ID를 응답합니다.

`CEC_MSG_ABORT`에는 specification에 따라 reason이 `Feature Refused`인 Feature Abort를 돌려줍니다.

`CEC_MSG_GIVE_PHYSICAL_ADDR`에는 현재 physical address를 보고하고, `CEC_MSG_GIVE_OSD_NAME`에는 `CEC_ADAP_S_LOG_ADDRS`로 설정한 현재 OSD name을 보고합니다.

이 다섯 message는 모두 passthrough mode에서 core가 아무 작업도 하지 않으며 follower가 처리해야 합니다.

Core message processing details:

.. tabularcolumns:: |p{6.6cm}|p{10.9cm}|

.. _cec-core-processing:

.. flat-table:: Core Message Processing
    :header-rows:  0
    :stub-columns: 0
    :widths: 1 8

    * .. _`CEC-MSG-GET-CEC-VERSION`:

      - ``CEC_MSG_GET_CEC_VERSION``
      - The core will return the CEC version that was set with
	:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
	except when in passthrough mode. In passthrough mode the core
	does nothing and this message has to be handled by a follower
	instead.
    * .. _`CEC-MSG-GIVE-DEVICE-VENDOR-ID`:

      - ``CEC_MSG_GIVE_DEVICE_VENDOR_ID``
      - The core will return the vendor ID that was set with
	:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
	except when in passthrough mode. In passthrough mode the core
	does nothing and this message has to be handled by a follower
	instead.
    * .. _`CEC-MSG-ABORT`:

      - ``CEC_MSG_ABORT``
      - The core will return a Feature Abort message with reason
        'Feature Refused' as per the specification, except when in
	passthrough mode. In passthrough mode the core does nothing
	and this message has to be handled by a follower instead.
    * .. _`CEC-MSG-GIVE-PHYSICAL-ADDR`:

      - ``CEC_MSG_GIVE_PHYSICAL_ADDR``
      - The core will report the current physical address, except when
        in passthrough mode. In passthrough mode the core does nothing
	and this message has to be handled by a follower instead.
    * .. _`CEC-MSG-GIVE-OSD-NAME`:

      - ``CEC_MSG_GIVE_OSD_NAME``
      - The core will report the current OSD name that was set with
	:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
	except when in passthrough mode. In passthrough mode the core
	does nothing and this message has to be handled by a follower
	instead.

Feature·remote-control·topology message

`CEC_MSG_GIVE_FEATURES`는 CEC version이 2.0보다 낮으면 아무 작업도 하지 않습니다. 2.0 이상이면 `CEC_ADAP_S_LOG_ADDRS`로 설정한 현재 features를 보고합니다. passthrough mode에서는 CEC version과 관계없이 core가 아무 작업도 하지 않으므로 follower가 처리해야 합니다.

`CEC_MSG_USER_CONTROL_PRESSED`는 `CEC_CAP_RC`와 `CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU`가 모두 설정된 경우 remote-control key press를 생성합니다. `CEC_MSG_USER_CONTROL_RELEASED`는 같은 조건에서 key release를 생성합니다.

두 user-control message는 core의 key event 생성 여부와 관계없이 항상 follower에게도 전달됩니다.

`CEC_MSG_REPORT_PHYSICAL_ADDR`을 받으면 CEC framework가 보고된 physical address를 기록한 뒤 follower에게 그대로 전달합니다.

    * .. _`CEC-MSG-GIVE-FEATURES`:

      - ``CEC_MSG_GIVE_FEATURES``
      - The core will do nothing if the CEC version is older than 2.0,
        otherwise it will report the current features that were set with
	:ref:`ioctl CEC_ADAP_S_LOG_ADDRS <CEC_ADAP_S_LOG_ADDRS>`,
	except when in passthrough mode. In passthrough mode the core
	does nothing (for any CEC version) and this message has to be handled
	by a follower instead.
    * .. _`CEC-MSG-USER-CONTROL-PRESSED`:

      - ``CEC_MSG_USER_CONTROL_PRESSED``
      - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
        :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
	is set, then generate a remote control key
	press. This message is always passed on to the follower(s).
    * .. _`CEC-MSG-USER-CONTROL-RELEASED`:

      - ``CEC_MSG_USER_CONTROL_RELEASED``
      - If :ref:`CEC_CAP_RC <CEC-CAP-RC>` is set and if
        :ref:`CEC_LOG_ADDRS_FL_ALLOW_RC_PASSTHRU <CEC-LOG-ADDRS-FL-ALLOW-RC-PASSTHRU>`
        is set, then generate a remote control key
	release. This message is always passed on to the follower(s).
    * .. _`CEC-MSG-REPORT-PHYSICAL-ADDR`:

      - ``CEC_MSG_REPORT_PHYSICAL_ADDR``
      - The CEC framework will make note of the reported physical address
	and then just pass the message on to the follower(s).

반환값과 오류

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

`CEC_S_MODE`에서 `EINVAL`은 요청한 mode가 유효하지 않음을 뜻하고, `EBUSY`는 다른 filehandle이 이미 exclusive follower 또는 exclusive initiator임을 뜻합니다.

원문 289–291행의 `EPERM` 설명은 monitor mode를 요청했지만 process가 `CAP_NET_ADMIN` capability를 ‘가지고 있다’고 적습니다. 이는 168–169행, 181–182행, 194–196행의 ‘capability가 없으면 EPERM’ 규칙과 반대입니다. 번역 본문은 원문 문장을 보존하며, 실제 동작을 판단할 때는 앞선 mode 설명과 kernel 구현을 함께 확인해야 합니다.

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

EINVAL
    The requested mode is invalid.

EPERM
    Monitor mode is requested, but the process does have the ``CAP_NET_ADMIN``
    capability.

EBUSY
    Someone else is already an exclusive follower or initiator.