API for USB Type-C Alternate Mode drivers

USB Type-C Alternate Mode 버스와 장치 결합

Alternate Mode는 USB Type-C 및 USB Power Delivery specification에 정의된 Vendor Defined Message(VDM)를 사용해 partner와 통신해야 합니다. 이 통신은 SVID(Standard or Vendor ID)마다 다르므로 각 Alternate Mode에는 전용 driver가 필요합니다.

USB Type-C bus는 발견된 partner Alternate Mode의 SVID와 mode number를 기준으로 알맞은 driver를 bind합니다.

`USB Type-C Connector Class`는 port가 지원하는 Alternate Mode마다 device를 만들고, partner가 지원하는 Alternate Mode마다 별도 device를 만듭니다. Alternate Mode driver는 partner Alternate Mode device에 bind되며, port Alternate Mode device는 port driver가 처리해야 합니다.

새 partner Alternate Mode device가 등록되면 bus는 같은 SVID와 mode를 가진, partner가 연결된 port의 Alternate Mode device에 이를 연결합니다. Port driver와 Alternate Mode driver 사이의 통신에도 동일한 API를 사용합니다.

Port Alternate Mode device는 partner와 Alternate Mode driver 사이의 proxy입니다. 따라서 port driver는 SVID-specific command를 Alternate Mode driver에서 partner로, partner에서 Alternate Mode driver로 전달하면 됩니다. Port driver가 SVID-specific 통신을 직접 구현할 필요는 없지만, partner 쪽 driver와 마찬가지로 port Alternate Mode device의 operation callback은 제공해야 합니다.

API for USB Type-C Alternate Mode drivers
=========================================

Introduction
------------

Alternate modes require communication with the partner using Vendor Defined
Messages (VDM) as defined in USB Type-C and USB Power Delivery Specifications.
The communication is SVID (Standard or Vendor ID) specific, i.e. specific for
every alternate mode, so every alternate mode will need a custom driver.

USB Type-C bus allows binding a driver to the discovered partner alternate
modes by using the SVID and the mode number.

:ref:`USB Type-C Connector Class <typec>` provides a device for every alternate
mode a port supports, and separate device for every alternate mode the partner
supports. The drivers for the alternate modes are bound to the partner alternate
mode devices, and the port alternate mode devices must be handled by the port
drivers.

When a new partner alternate mode device is registered, it is linked to the
alternate mode device of the port that the partner is attached to, that has
matching SVID and mode. Communication between the port driver and alternate mode
driver will happen using the same API.

The port alternate mode devices are used as a proxy between the partner and the
alternate mode drivers, so the port drivers are only expected to pass the SVID
specific commands from the alternate mode drivers to the partner, and from the
partners to the alternate mode drivers. No direct SVID specific communication is
needed from the port drivers, but the port drivers need to provide the operation
callbacks for the port alternate mode devices, just like the alternate mode
drivers need to provide them for the partner alternate mode devices.

Mode 진입, VDM 전달과 connector 상태 전이

기본적으로 Alternate Mode에 진입할 책임은 Alternate Mode driver에 있습니다. 진입 결정을 userspace에 맡길 수도 있으며 자세한 interface는 `Documentation/ABI/testing/sysfs-class-typec`에 설명되어 있습니다. Port driver는 임의로 어떤 mode에도 진입해서는 안 됩니다.

Operation callback vector에서 가장 중요한 callback은 `->vdm`입니다. Partner가 보낸 모든 SVID-specific command를 Alternate Mode driver에 전달하며, port driver의 경우 반대 방향 command도 전달합니다. Driver들은 `typec_altmode_vdm()`으로 서로 SVID-specific command를 보냅니다.

SVID-specific command 교환 결과 connector pin을 재구성해야 한다면 Alternate Mode driver는 `typec_altmode_notify()`로 bus에 알려야 합니다. 이 함수에는 협상된 SVID-specific pin configuration 값을 parameter로 전달하고, bus driver는 그 값을 mux state로 사용해 connector 뒤의 mux를 설정합니다.

SVID-specific pin configuration 값은 반드시 `TYPEC_STATE_MODAL`부터 시작해야 합니다. USB Type-C specification이 정의한 기본 connector 상태 `TYPEC_STATE_USB`와 `TYPEC_STATE_SAFE`는 bus가 가능한 첫 state 값으로 예약합니다.

Alternate Mode에 진입할 때 bus는 specification에 따라 Enter Mode 또는 Exit Mode command를 보내기 전에 connector를 `TYPEC_STATE_SAFE`로 옮깁니다. Mode를 빠져나온 뒤에는 connector를 `TYPEC_STATE_USB`로 되돌립니다.

Usage:
------

General
~~~~~~~

By default, the alternate mode drivers are responsible for entering the mode.
It is also possible to leave the decision about entering the mode to the user
space (See Documentation/ABI/testing/sysfs-class-typec). Port drivers should not
enter any modes on their own.

``->vdm`` is the most important callback in the operation callbacks vector. It
will be used to deliver all the SVID specific commands from the partner to the
alternate mode driver, and vice versa in case of port drivers. The drivers send
the SVID specific commands to each other using :c:func:`typec_altmode_vdm()`.

If the communication with the partner using the SVID specific commands results
in need to reconfigure the pins on the connector, the alternate mode driver
needs to notify the bus using :c:func:`typec_altmode_notify()`. The driver
passes the negotiated SVID specific pin configuration value to the function as
parameter. The bus driver will then configure the mux behind the connector using
that value as the state value for the mux.

NOTE: The SVID specific pin configuration values must always start from
``TYPEC_STATE_MODAL``. USB Type-C specification defines two default states for
the connector: ``TYPEC_STATE_USB`` and ``TYPEC_STATE_SAFE``. These values are
reserved by the bus as the first possible values for the state. When the
alternate mode is entered, the bus will put the connector into
``TYPEC_STATE_SAFE`` before sending Enter or Exit Mode command as defined in USB
Type-C Specification, and also put the connector back to ``TYPEC_STATE_USB``
after the mode has been exited.

Modal pin 정의와 cable plug Alternate Mode

SVID-specific pin configuration은 첫 enum 값을 `TYPEC_STATE_MODAL`로 지정하고 이후 값을 연속해서 배치할 수 있습니다. 이렇게 하면 `ALTMODEX_CONF_A`, `ALTMODEX_CONF_B` 같은 mode별 state가 bus의 기본 USB·SAFE state와 충돌하지 않습니다.

같은 정의를 helper macro `TYPEC_MODAL_STATE()`로 작성할 수도 있습니다. Index `0`은 첫 modal state, index `1`은 다음 modal state를 뜻합니다. 원문의 enum과 macro 정의는 아래 영어 원문 block에 그대로 보존되어 있습니다.

Alternate Mode driver는 cable plug Alternate Mode device에 직접 bind되지 않고 partner Alternate Mode device에만 bind됩니다.

Alternate Mode가 SOP Prime message에 응답하는 cable을 지원하거나 요구하고, 선택적으로 SOP Double Prime message까지 사용한다면 해당 driver가 `typec_altmode_get_plug()`으로 cable plug Alternate Mode handle을 요청해 제어권을 넘겨받아야 합니다.

An example of working definitions for SVID specific pin configurations would
look like this::

    enum {
        ALTMODEX_CONF_A = TYPEC_STATE_MODAL,
        ALTMODEX_CONF_B,
        ...
    };

Helper macro ``TYPEC_MODAL_STATE()`` can also be used::

#define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0);
#define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1);

Cable plug alternate modes
~~~~~~~~~~~~~~~~~~~~~~~~~~

The alternate mode drivers are not bound to cable plug alternate mode devices,
only to the partner alternate mode devices. If the alternate mode supports, or
requires, a cable that responds to SOP Prime, and optionally SOP Double Prime
messages, the driver for that alternate mode must request handle to the cable
plug alternate modes using :c:func:`typec_altmode_get_plug()`, and take over
their control.

Alternate Mode driver 구조와 operation API

Driver API는 `include/linux/usb/typec_altmode.h`의 `typec_altmode_driver`와 `typec_altmode_ops` 구조를 kernel-doc으로 제공합니다. 전자는 Alternate Mode driver를, 후자는 mode 동작 callback 집합을 나타냅니다.

Alternate Mode driver의 등록과 해제에는 같은 header의 `typec_altmode_register_driver`와 `typec_altmode_unregister_driver`를 사용합니다.

`drivers/usb/typec/bus.c`는 mode 진입·종료를 위한 `typec_altmode_enter`와 `typec_altmode_exit`, Attention 전달용 `typec_altmode_attention`, VDM 교환용 `typec_altmode_vdm`, mux state 통지용 `typec_altmode_notify`를 제공합니다.

Driver API
----------

Alternate mode structs
~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: include/linux/usb/typec_altmode.h
   :functions: typec_altmode_driver typec_altmode_ops

Alternate mode driver registering/unregistering
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: include/linux/usb/typec_altmode.h
   :functions: typec_altmode_register_driver typec_altmode_unregister_driver

Alternate mode driver operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/usb/typec/bus.c
   :functions: typec_altmode_enter typec_altmode_exit typec_altmode_attention typec_altmode_vdm typec_altmode_notify

Port driver와 cable plug API

Port driver는 `drivers/usb/typec/bus.c`의 `typec_match_altmode`를 사용해 주어진 SVID와 mode에 맞는 Alternate Mode를 찾습니다.

Cable plug Alternate Mode를 제어하는 driver는 `typec_altmode_get_plug`으로 handle을 얻고, 사용을 마치면 `typec_altmode_put_plug`으로 reference를 반환합니다.

따라서 port 쪽 matching과 cable plug 쪽 get·put lifecycle을 분리해 관리해야 하며, partner Alternate Mode driver가 필요한 cable plug만 명시적으로 인계받는 구조입니다.

API for the port drivers
~~~~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/usb/typec/bus.c
   :functions: typec_match_altmode

Cable Plug operations
~~~~~~~~~~~~~~~~~~~~~

.. kernel-doc:: drivers/usb/typec/bus.c
   :functions: typec_altmode_get_plug typec_altmode_put_plug