USB Type-C connector class

介绍

https://www.kernel.org/doc/html/v4.15/driver-api/usb/typec.html

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.

typec 类旨在以统一的方式向用户空间描述系统中的 USB Type-C 端口。 该类旨在提供用户空间的接口实现，希望它可以在尽可能多的平台上使用。

平台应该将他们的每一个USB Type-C端口使用USB Type-C connector class这个类注册进系统，在正常情况下，注册将由 USB Type-C 或 PD PHY 的驱动程序完成，但是也有可能是UCSI 等固件接口驱动程序、USB PD 控制器驱动程序甚至 Thunderbolt3 控制器驱动程序。所以本文将上面任意一种驱动使用 USB Type-C connector class 注册USB Type-C 端口的驱动程序称为“port driver（端口驱动）”

除了上面显示的这些功能之外，该类还提供对端口、合作伙伴和电缆插头的角色和替代模式的用户空间控制。（如果端口驱动程序能够支持这些功能）

该类为本文档中描述的端口驱动程序提供了一个 API。 属性在文档/ABI/testing/sysfs-class-typec 中描述。

用户空间接口

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”, for example /sys/class/typec/port0//mode1/. The requests for entering/exiting a mode can be done with “active” attribute file in that group.

每个端口都将在 /sys/class/typec/ 下显示。 第一个端口将命名为“port0”，第二个为“port1”，依此类推。

连接后，合作伙伴也将在 /sys/class/typec/ 下显示。 伙伴设备的父设备将始终是它所连接的端口。 连接到端口“port0”的伙伴将被命名为“port0-partner”。 设备的完整路径是 /sys/class/typec/port0/port0-partner/。

cable和其上的两个插头也可以选择在 /sys/class/typec/ 下显示。 连接到端口“port0”端口的cable将命名为 port0-cable，SOP Prime 端（请参阅 USB 供电规范第 2.4 章）上的插头将命名为“port0-plug0”，SOP Double Prime 端上的插头将命名为“ port0-plug1”。 cable的父级始终是端口，cable插头的父级始终是cable。

如果port, partner 或者 cable plug支持Alternate Modes，则每个受支持的Alternate Mode SVID 都有自己的设备来描述它们。 请注意， Alternate Mode设备不会附加到 typec 类。 Alternate Mode的父级将是支持它的设备，因此例如 port0-partner 的 Alternate Mode将显示在 /sys/class/typec/port0-partner/ 下。 支持的每种模式在名为“mode”的 Alternate Mode设备下都有自己的组，例如 /sys/class/typec/port0//mode1/。 进入/退出模式的请求可以通过该组中的“active”属性文件来完成。

驱动程序接口

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

port drivers应该使用一个typec_capability 结构体去描述每一个它所控制的Type-C port，然后用下面的API去注册：

//Register a USB Type-C Port
struct typec_port * (struct device * parent, const struct typec_capability * captypec_register_port)

//Unregister a USB Type-C Port
void typec_unregister_port(struct typec_port * 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.
在注册端口时，struct typec_capability 中的 preferred_role 成员需要特别注意。 如果正在注册的端口没有初始角色首选项，即端口默认不执行 Try.SNK 或 Try.SRC，则该成员必须赋值 TYPEC_NO_PREFERRED_ROLE。 否则，如果端口默认执行Try.SNK，则该成员的值必须为TYPEC_DEVICE，而Try.SRC 的值必须为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.
partner连接成功后，端口驱动程序需要向该类注册partner。 关于partner的详细信息需要在struct typec_partner_desc 中填充描述。 typec类会在注册期间复制partner的详细信息。 该类提供以下用于注册/取消注册partner的 API。

//Register a USB Type-C Partner
struct typec_partner * (struct typec_port * port, struct typec_partner_desc * desctypec_register_partner)

//Unregister a USB Type-C Partner
void typec_unregister_partner(struct typec_partner * partner)

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:
如果partner 具有 USB 供电能力，并且端口驱动程序能够显示 Discover Identity 命令的结果，则partner 描述符结构应包含结构体 usb_pd_identity 实例的句柄。 然后，该类将为partner 的identity 创建一个 sysfs 目录。 然后可以使用以下 API 报告 Discover Identity 命令的结果：

//Report result from Discover Identity command
int typec_partner_set_identity(struct typec_partner * partner)

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:
当partner 执行了角色更改，或者当partner 或线缆连接期间默认角色发生更改时，端口驱动程序必须使用以下 API 将其报告给类：

//Report data role change
void typec_set_data_role(struct typec_port * port, enum typec_data_role role)

//Report power role change
void typec_set_pwr_role(struct typec_port * port, enum typec_role role)

//Report VCONN source change
void typec_set_vconn_role(struct typec_port * port, enum typec_role role)

//Report changed power operation mode
void typec_set_pwr_opmode(struct typec_port * port, enum typec_pwr_opmode opmode)