USB Type-C connector class

USB Type-C Connector Class의 목적

Type-C class는 system의 USB Type-C port를 userspace에 통일된 방식으로 설명하기 위한 class입니다. 가능한 한 많은 platform에서 재사용할 수 있도록 userspace interface 구현 외의 기능은 제공하지 않도록 설계되었습니다.

Platform은 보유한 모든 USB Type-C port를 class에 등록해야 합니다. 보통 USB Type-C 또는 PD PHY driver가 등록하지만 UCSI 같은 firmware interface driver, USB PD controller driver, Thunderbolt3 controller driver가 맡을 수도 있습니다. 이 문서는 port를 class에 등록하는 component를 `port driver`라고 부릅니다.

Class는 capability를 표시할 뿐 아니라 port driver가 지원할 때 port, partner, cable plug의 role과 Alternate Mode를 userspace가 제어할 수 있게 합니다.

이 문서에는 port driver용 API가 정리되어 있고, 각 userspace attribute는 `Documentation/ABI/testing/sysfs-class-typec`에 설명되어 있습니다.

.. _typec:

USB Type-C connector class
==========================

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

The typec class is meant for describing the USB Type-C ports in a system to the
user space in unified fashion. The class is designed to provide nothing else
except the user space interface implementation in hope that it can be utilized
on as many platforms as possible.

The platforms are expected to register every USB Type-C port they have with the
class. In a normal case the registration will be done by a USB Type-C or PD PHY
driver, but it may be a driver for firmware interface such as UCSI, driver for
USB PD controller or even driver for Thunderbolt3 controller. This document
considers the component registering the USB Type-C ports with the class as "port
driver".

On top of showing the capabilities, the class also offer user space control over
the roles and alternate modes of ports, partners and cable plugs when the port
driver is capable of supporting those features.

The class provides an API for the port drivers described in this document. The
attributes are described in Documentation/ABI/testing/sysfs-class-typec.

Sysfs device hierarchy와 Alternate Mode 제어

각 port는 `/sys/class/typec/` 아래 독립 device로 표시됩니다. 첫 port는 `port0`, 다음 port는 `port1`처럼 순서대로 이름을 얻습니다.

Partner가 연결되면 partner도 독립 device로 나타나며 parent는 항상 연결된 port입니다. 예를 들어 `port0`의 partner는 `port0-partner`, 전체 경로는 `/sys/class/typec/port0/port0-partner/`입니다.

Cable과 두 plug도 선택적으로 독립 device로 표시할 수 있습니다. `port0`에 연결된 cable은 `port0-cable`, SOP Prime 쪽 plug는 `port0-plug0`, SOP Double Prime 쪽 plug는 `port0-plug1`입니다. Cable의 parent는 port이고 plug의 parent는 cable입니다.

Port, partner 또는 cable plug가 Alternate Mode를 지원하면 지원하는 각 Alternate Mode SVID마다 설명 device가 생깁니다. 이 Alternate Mode device 자체는 typec class에 직접 attach되지 않고, 자신을 지원하는 device를 parent로 둡니다.

각 SVID가 지원하는 mode는 Alternate Mode device 아래 `mode<index>` group으로 나타납니다. 예를 들어 `/sys/class/typec/port0/<alternate mode>/mode1/`이며, group의 `active` attribute로 mode 진입과 종료를 요청합니다.

User space interface
--------------------
Every port will be presented as its own device under /sys/class/typec/. The
first port will be named "port0", the second "port1" and so on.

When connected, the partner will be presented also as its own device under
/sys/class/typec/. The parent of the partner device will always be the port it
is attached to. The partner attached to port "port0" will be named
"port0-partner". Full path to the device would be
/sys/class/typec/port0/port0-partner/.

The cable and the two plugs on it may also be optionally presented as their own
devices under /sys/class/typec/. The cable attached to the port "port0" port
will be named port0-cable and the plug on the SOP Prime end (see USB Power
Delivery Specification ch. 2.4) will be named "port0-plug0" and on the SOP
Double Prime end "port0-plug1". The parent of a cable will always be the port,
and the parent of the cable plugs will always be the cable.

If the port, partner or cable plug supports Alternate Modes, every supported
Alternate Mode SVID will have their own device describing them. Note that the
Alternate Mode devices will not be attached to the typec class. The parent of an
alternate mode will be the device that supports it, so for example an alternate
mode of port0-partner will be presented under /sys/class/typec/port0-partner/.
Every mode that is supported will have its own group under the Alternate Mode
device named "mode<index>", for example /sys/class/typec/port0/<alternate
mode>/mode1/. The requests for entering/exiting a mode can be done with "active"
attribute file in that group.

Port와 partner 등록 API

Port driver는 제어하는 각 Type-C port를 `struct typec_capability`로 설명하고 `typec_register_port`로 등록합니다. 제거할 때는 `typec_unregister_port`를 사용합니다.

`typec_capability.prefer_role`은 초기 role preference를 정확히 표현해야 합니다. 기본적으로 Try.SNK나 Try.SRC를 수행하지 않으면 `TYPEC_NO_PREFERRED_ROLE`, Try.SNK를 기본 수행하면 `TYPEC_DEVICE`, Try.SRC를 기본 수행하면 `TYPEC_HOST`입니다.

Partner 연결이 성공하면 port driver는 partner 정보를 `struct typec_partner_desc`에 채워 class에 등록해야 합니다. Class는 등록 시 descriptor 내용을 복사하며 `typec_register_partner`와 `typec_unregister_partner`를 제공합니다.

Partner 등록에 성공하면 `struct typec_partner` handle이 반환되고 실패하면 `NULL`이 반환됩니다.

Partner가 USB Power Delivery를 지원하고 port driver가 Discover Identity 결과를 표시할 수 있다면 descriptor에 `struct usb_pd_identity` handle을 포함해야 합니다. Class는 partner device 아래 identity sysfs directory를 만들고, 이후 `typec_partner_set_identity`로 Discover Identity 결과를 보고할 수 있습니다.

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

Registering the ports
~~~~~~~~~~~~~~~~~~~~~

The port drivers will describe every Type-C port they control with struct
typec_capability data structure, and register them with the following API:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_register_port typec_unregister_port

When registering the ports, the prefer_role member in struct typec_capability
deserves special notice. If the port that is being registered does not have
initial role preference, which means the port does not execute Try.SNK or
Try.SRC by default, the member must have value TYPEC_NO_PREFERRED_ROLE.
Otherwise if the port executes Try.SNK by default, the member must have value
TYPEC_DEVICE, and with Try.SRC the value must be TYPEC_HOST.

Registering Partners
~~~~~~~~~~~~~~~~~~~~

After successful connection of a partner, the port driver needs to register the
partner with the class. Details about the partner need to be described in struct
typec_partner_desc. The class copies the details of the partner during
registration. The class offers the following API for registering/unregistering
partners.

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_register_partner typec_unregister_partner

The class will provide a handle to struct typec_partner if the registration was
successful, or NULL.

If the partner is USB Power Delivery capable, and the port driver is able to
show the result of Discover Identity command, the partner descriptor structure
should include handle to struct usb_pd_identity instance. The class will then
create a sysfs directory for the identity under the partner device. The result
of Discover Identity command can then be reported with the following API:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_partner_set_identity

Cable과 plug 등록 및 identity 보고

USB Power Delivery Structured VDM `Discover Identity`를 지원하는 cable이 성공적으로 연결되면 port driver는 cable과 하나 또는 두 개의 plug를 등록해야 합니다. Plug 수는 cable에 CC Double Prime controller가 있는지에 따라 결정됩니다.

SOP Prime 통신은 가능하지만 SOP Double Prime 통신은 불가능한 cable에는 plug를 하나만 등록합니다. SOP 통신의 자세한 규칙은 최신 USB Power Delivery specification의 해당 chapter를 참고해야 합니다.

Cable을 먼저 등록한 다음 cable plug를 등록하며, plug device의 parent는 cable입니다. Cable 정보는 `struct typec_cable_desc`, plug 정보는 `struct typec_plug_desc`로 설명하고 class는 등록 시 내용을 복사합니다.

Lifecycle API는 `typec_register_cable`, `typec_unregister_cable`, `typec_register_plug`, `typec_unregister_plug`입니다. 성공하면 `struct typec_cable` 또는 `struct typec_plug` handle을 반환하고 실패하면 `NULL`을 반환합니다.

Cable이 USB Power Delivery를 지원하고 Discover Identity 결과를 표시할 수 있다면 cable descriptor에 `struct usb_pd_identity` handle을 포함합니다. Class는 cable device 아래 identity sysfs directory를 만들며 `typec_cable_set_identity`로 결과를 보고합니다.

Registering Cables
~~~~~~~~~~~~~~~~~~

After successful connection of a cable that supports USB Power Delivery
Structured VDM "Discover Identity", the port driver needs to register the cable
and one or two plugs, depending if there is CC Double Prime controller present
in the cable or not. So a cable capable of SOP Prime communication, but not SOP
Double Prime communication, should only have one plug registered. For more
information about SOP communication, please read chapter about it from the
latest USB Power Delivery specification.

The plugs are represented as their own devices. The cable is registered first,
followed by registration of the cable plugs. The cable will be the parent device
for the plugs. Details about the cable need to be described in struct
typec_cable_desc and about a plug in struct typec_plug_desc. The class copies
the details during registration. The class offers the following API for
registering/unregistering cables and their plugs:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_register_cable typec_unregister_cable typec_register_plug typec_unregister_plug

The class will provide a handle to struct typec_cable and struct typec_plug if
the registration is successful, or NULL if it isn't.

If the cable is USB Power Delivery capable, and the port driver is able to show
the result of Discover Identity command, the cable descriptor structure should
include handle to struct usb_pd_identity instance. The class will then create a
sysfs directory for the identity under the cable device. The result of Discover
Identity command can then be reported with the following API:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_cable_set_identity

Role과 power mode 변경 통지

Partner가 role change를 수행했거나 partner 또는 cable 연결 중 default role이 바뀌면 port driver는 변경된 상태를 Type-C class에 보고해야 합니다.

Data role은 `typec_set_data_role`, power role은 `typec_set_pwr_role`, VCONN role은 `typec_set_vconn_role`, power operation mode는 `typec_set_pwr_opmode`로 갱신합니다.

Notifications
~~~~~~~~~~~~~

When the partner has executed a role change, or when the default roles change
during connection of a partner or cable, the port driver must use the following
APIs to report it to the class:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role typec_set_pwr_opmode

Port·partner·plug Alternate Mode 등록

USB Type-C port, partner, cable plug는 Alternate Mode를 지원할 수 있습니다. 각 Alternate Mode에는 USB-IF가 부여한 Standard ID 또는 vendor ID인 SVID가 있고, SVID 하나는 1개에서 6개의 mode를 지원할 수 있습니다.

SVID의 개별 mode는 `struct typec_mode_desc`로 설명하고, 지원되는 전체 mode의 container는 `struct typec_altmode_desc`입니다.

Port는 지원하는 SVID마다 `typec_port_register_altmode`를 호출합니다. Partner 또는 cable plug가 USB Power Delivery Structured VDM Discover SVIDs message에 SVID 목록으로 응답하면 각 SVID를 모두 등록해야 합니다.

Partner는 `typec_partner_register_altmode`, cable plug는 `typec_plug_register_altmode`를 사용합니다. 대상별 등록 함수는 다르지만 성공하면 모두 `struct typec_altmode` handle을 반환하고 실패하면 `NULL`을 반환합니다.

등록 해제에는 공통 `typec_unregister_altmode`를 사용합니다. Partner 또는 cable plug가 mode에 진입하거나 빠져나오면 port driver는 `typec_altmode_update_active`로 class에 active 상태를 알려야 합니다.

Alternate Modes
~~~~~~~~~~~~~~~

USB Type-C ports, partners and cable plugs may support Alternate Modes. Each
Alternate Mode will have identifier called SVID, which is either a Standard ID
given by USB-IF or vendor ID, and each supported SVID can have 1 - 6 modes. The
class provides struct typec_mode_desc for describing individual mode of a SVID,
and struct typec_altmode_desc which is a container for all the supported modes.

Ports that support Alternate Modes need to register each SVID they support with
the following API:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_port_register_altmode

If a partner or cable plug provides a list of SVIDs as response to USB Power
Delivery Structured VDM Discover SVIDs message, each SVID needs to be
registered.

API for the partners:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_partner_register_altmode

API for the Cable Plugs:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_plug_register_altmode

So ports, partners and cable plugs will register the alternate modes with their
own functions, but the registration will always return a handle to struct
typec_altmode on success, or NULL. The unregistration will happen with the same
function:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_unregister_altmode

If a partner or cable plug enters or exits a mode, the port driver needs to
notify the class with the following API:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_altmode_update_active

Orientation switch와 mode mux

USB Type-C connector 뒤에는 하나 이상의 mux 또는 demux switch가 있을 수 있습니다. Plug를 어느 방향으로도 삽입할 수 있으므로 올바른 data pair를 USB controller에 연결하는 orientation switch가 필요합니다.

Alternate Mode나 Accessory Mode를 지원하면 connector pin을 USB가 아닌 다른 component로 보낼 mode mux도 필요합니다. Type-C Connector Class는 `typec_switch_register`, `typec_switch_unregister`, `typec_mux_register`, `typec_mux_unregister`로 이 switch들을 등록합니다.

대부분 같은 physical mux가 orientation과 mode를 모두 처리하지만 ownership이 다르므로 logical component는 항상 분리합니다. Port driver가 orientation을 담당하는 `switch`, Alternate Mode driver가 mode를 담당하는 `mux`를 제어합니다.

Port를 등록할 때 class는 해당 port의 mux와 switch를 모두 요청합니다. Port driver는 `typec_set_orientation`과 `typec_set_mode`로 이를 제어합니다.

Dual-role connector에는 data role switch도 있을 수 있지만 Type-C Connector Class는 이를 위한 별도 API를 제공하지 않습니다. Port driver는 USB Role Class API를 사용해야 합니다.

Multiplexer/DeMultiplexer Switches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

USB Type-C connectors may have one or more mux/demux switches behind them. Since
the plugs can be inserted right-side-up or upside-down, a switch is needed to
route the correct data pairs from the connector to the USB controllers. If
Alternate or Accessory Modes are supported, another switch is needed that can
route the pins on the connector to some other component besides USB. USB Type-C
Connector Class supplies an API for registering those switches.

.. kernel-doc:: drivers/usb/typec/mux.c
   :functions: typec_switch_register typec_switch_unregister typec_mux_register typec_mux_unregister

In most cases the same physical mux will handle both the orientation and mode.
However, as the port drivers will be responsible for the orientation, and the
alternate mode drivers for the mode, the two are always separated into their
own logical components: "mux" for the mode and "switch" for the orientation.

When a port is registered, USB Type-C Connector Class requests both the mux and
the switch for the port. The drivers can then use the following API for
controlling them:

.. kernel-doc:: drivers/usb/typec/class.c
   :functions: typec_set_orientation typec_set_mode

If the connector is dual-role capable, there may also be a switch for the data
role. USB Type-C Connector Class does not supply separate API for them. The
port drivers can use USB Role Class API with those.

Alternate Mode connector mux topology

Alternate Mode를 지원하는 connector의 data path는 먼저 orientation switch를 지나 올바른 pin pair를 선택하고, 다음 mode mux에서 Alternate Mode 경로와 USB Role 경로로 갈라집니다.

Alternate Mode branch는 해당 protocol component로 연결됩니다. USB Role branch는 현재 data role에 따라 USB Host 또는 USB Device controller로 다시 분기합니다.

원문의 ASCII 그림은 아래 구조화 흐름도로 같은 연결 관계를 재구성했으며, 영어 원문 block에는 원래 줄 배치도 그대로 보존했습니다.

Illustration of the muxes behind a connector that supports an alternate mode::

                     ------------------------
                     |       Connector      |
                     ------------------------
                            |         |
                     ------------------------
                      \     Orientation    /
                       --------------------
                                |
                       --------------------
                      /        Mode        \
                     ------------------------
                         /              \
      ------------------------        --------------------
      |       Alt Mode       |       /      USB Role      \
      ------------------------      ------------------------
                                         /            \
                     ------------------------      ------------------------
                     |       USB Host       |      |       USB Device     |
                     ------------------------      ------------------------