USB Type-C 连接器类¶

简介¶

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

平台应将它们拥有的每个 USB Type-C 端口注册到该类。在正常情况下，注册将由 USB Type-C 或 PD PHY 驱动程序完成，但也可能是固件接口（例如 UCSI）的驱动程序、USB PD 控制器的驱动程序，甚至是 Thunderbolt3 控制器的驱动程序。本文将向该类注册 USB Type-C 端口的组件视为“端口驱动程序”。

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

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

用户空间接口¶

每个端口都将作为其自己的设备出现在 /sys/class/typec/ 下。第一个端口将命名为“port0”，第二个端口命名为“port1”，依此类推。

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

电缆及其上的两个插头也可以选择性地作为它们自己的设备出现在 /sys/class/typec/ 下。连接到端口“port0”的电缆将命名为 port0-cable，SOP Prime 端（参见 USB Power Delivery 规范第 2.4 章）上的插头将命名为“port0-plug0”，SOP Double Prime 端上的插头将命名为“port0-plug1”。电缆的父设备始终是端口，电缆插头的父设备始终是电缆。

如果端口、合作伙伴或电缆插头支持备用模式，则每个支持的备用模式 SVID 都将拥有自己的设备来描述它们。请注意，备用模式设备不会连接到 typec 类。备用模式的父设备将是支持它的设备，因此例如 port0-partner 的备用模式将出现在 /sys/class/typec/port0-partner/ 下。每个支持的模式都将在备用模式设备下拥有自己的组，命名为“mode<index>”，例如 /sys/class/typec/port0/<alternate mode>/mode1/。进入/退出模式的请求可以使用该组中的“active”属性文件完成。

驱动程序 API¶

注册端口¶

端口驱动程序将使用 struct typec_capability 数据结构描述它们控制的每个 Type-C 端口，并使用以下 API 注册它们

struct typec_port *typec_register_port(struct device *parent, const struct typec_capability *cap)¶: 注册 USB Type-C 端口

参数

struct device *parent: 父设备
const struct typec_capability *cap: 端口的描述

描述

为 cap 中描述的 USB Type-C 端口注册设备。

成功时返回端口的句柄，失败时返回 ERR_PTR。

void typec_unregister_port(struct typec_port *port)¶: 注销 USB Type-C 端口

参数

struct typec_port *port: 要注销的端口

描述

注销使用 typec_register_port() 创建的设备。

注册端口时，struct typec_capability 中的 prefer_role 成员值得特别注意。如果要注册的端口没有初始角色偏好，这意味着该端口默认不执行 Try.SNK 或 Try.SRC，则该成员必须具有值 TYPEC_NO_PREFERRED_ROLE。否则，如果端口默认执行 Try.SNK，则该成员必须具有值 TYPEC_DEVICE，而使用 Try.SRC 时，该值必须为 TYPEC_HOST。

注册合作伙伴¶

成功连接合作伙伴后，端口驱动程序需要向该类注册合作伙伴。有关合作伙伴的详细信息需要在 struct typec_partner_desc 中描述。该类在注册期间复制合作伙伴的详细信息。该类提供了以下 API 用于注册/注销合作伙伴。

struct typec_partner *typec_register_partner(struct typec_port *port, struct typec_partner_desc *desc)¶: 注册 USB Type-C 合作伙伴

参数

struct typec_port *port: 合作伙伴连接到的 USB Type-C 端口
struct typec_partner_desc *desc: 合作伙伴的描述

描述

为 desc 中描述的 USB Type-C 合作伙伴注册设备。

成功时返回合作伙伴的句柄，失败时返回 ERR_PTR。

void typec_unregister_partner(struct typec_partner *partner)¶: 注销 USB Type-C 合作伙伴

参数

struct typec_partner *partner: 要注销的合作伙伴

描述

注销使用 typec_register_partner() 创建的设备。

如果注册成功，该类将提供 struct typec_partner 的句柄，否则提供 NULL。

如果合作伙伴支持 USB Power Delivery，并且端口驱动程序能够显示 Discover Identity 命令的结果，则合作伙伴描述符结构应包括 struct usb_pd_identity 实例的句柄。然后，该类将在合作伙伴设备下创建一个 sysfs 目录用于标识。Discover Identity 命令的结果可以使用以下 API 报告

int typec_partner_set_identity(struct typec_partner *partner)¶: 报告 Discover Identity 命令的结果

参数

struct typec_partner *partner: 合作伙伴更新的标识值

描述

此例程用于报告 Discover Identity USB Power Delivery 命令的结果已可用。

注册电缆¶

成功连接支持 USB Power Delivery 结构化 VDM “Discover Identity”的电缆后，端口驱动程序需要注册电缆和一个或两个插头，具体取决于电缆中是否存在 CC Double Prime 控制器。因此，能够进行 SOP Prime 通信但不能进行 SOP Double Prime 通信的电缆应仅注册一个插头。有关 SOP 通信的更多信息，请阅读最新 USB Power Delivery 规范中的相关章节。

插头表示为它们自己的设备。首先注册电缆，然后注册电缆插头。电缆将是插头的父设备。有关电缆的详细信息需要在 struct typec_cable_desc 中描述，有关插头的详细信息需要在 struct typec_plug_desc 中描述。该类在注册期间复制详细信息。该类提供了以下 API 用于注册/注销电缆及其插头

struct typec_plug *typec_register_plug(struct typec_cable *cable, struct typec_plug_desc *desc)¶: 注册 USB Type-C 电缆插头

参数

struct typec_cable *cable: 带有插头的 USB Type-C 电缆
struct typec_plug_desc *desc: 电缆插头的描述

描述

为 desc 中描述的 USB Type-C 电缆插头注册设备。USB Type-C 电缆插头表示带有电子元件的插头，它可以响应 USB Power Delivery SOP Prime 或 SOP Double Prime 数据包。

成功时返回电缆插头的句柄，失败时返回 ERR_PTR。

void typec_unregister_plug(struct typec_plug *plug)¶: 注销 USB Type-C 电缆插头

参数

struct typec_plug *plug: 要注销的电缆插头

描述

注销使用 typec_register_plug() 创建的设备。

struct typec_cable *typec_register_cable(struct typec_port *port, struct typec_cable_desc *desc)¶: 注册 USB Type-C 电缆

参数

struct typec_port *port: 电缆连接到的 USB Type-C 端口
struct typec_cable_desc *desc: 电缆的描述

描述

为 desc 中描述的 USB Type-C 电缆注册设备。电缆将是可选电缆插头设备的父设备。

成功时返回电缆的句柄，失败时返回 ERR_PTR。

void typec_unregister_cable(struct typec_cable *cable)¶: 注销 USB Type-C 电缆

参数

struct typec_cable *cable: struct typec_cable *cable

描述

要注销的电缆

如果注册成功，该类将提供 struct typec_cable 和 struct typec_plug 的句柄，否则提供 NULL。

如果电缆支持 USB Power Delivery，并且端口驱动程序能够显示 Discover Identity 命令的结果，则电缆描述符结构应包括 struct usb_pd_identity 实例的句柄。然后，该类将在电缆设备下创建一个 sysfs 目录用于标识。Discover Identity 命令的结果可以使用以下 API 报告

int typec_cable_set_identity(struct typec_cable *cable)¶: 报告 Discover Identity 命令的结果

参数

struct typec_cable *cable: 电缆更新的标识值

描述

此例程用于报告 Discover Identity USB Power Delivery 命令的结果已可用。

通知¶

当合作伙伴执行角色更改时，或者在连接合作伙伴或电缆期间默认角色更改时，端口驱动程序必须使用以下 API 将其报告给该类

void typec_set_data_role(struct typec_port *port, enum typec_data_role role)¶: 报告数据角色更改

参数

struct typec_port *port: 发生角色更改的 USB Type-C 端口
enum typec_data_role role: 新的数据角色

描述

端口驱动程序使用此例程报告数据角色更改。

void typec_set_pwr_role(struct typec_port *port, enum typec_role role)¶: 报告电源角色更改

参数

struct typec_port *port: 发生角色更改的 USB Type-C 端口
enum typec_role role: 新的数据角色

描述

端口驱动程序使用此例程报告电源角色更改。

void typec_set_vconn_role(struct typec_port *port, enum typec_role role)¶: 报告 VCONN 源更改

参数

struct typec_port *port: VCONN 角色已更改的 USB Type-C 端口
enum typec_role role: 当 port 提供 VCONN 时为源，否则为接收器

描述

端口驱动程序使用此例程报告 VCONN 源是否已更改。

void typec_set_pwr_opmode(struct typec_port *port, enum typec_pwr_opmode opmode)¶: 报告更改的电源操作模式

参数

struct typec_port *port: 模式已更改的 USB Type-C 端口
enum typec_pwr_opmode opmode: 新的电源操作模式

描述

端口驱动程序使用此例程报告 port 中更改的电源操作模式。这些模式是 USB（默认）、1.5A、3.0A（如 USB Type-C 规范中所定义）以及“USB Power Delivery”（当使用 USB Power Delivery 规范中定义的方法协商功率级别时）。

备用模式¶

USB Type-C 端口、合作伙伴和电缆插头可能支持备用模式。每个备用模式都有一个称为 SVID 的标识符，它是 USB-IF 提供的标准 ID 或供应商 ID，并且每个支持的 SVID 可以具有 1 到 6 个模式。该类提供了 struct typec_mode_desc 用于描述 SVID 的各个模式，并提供了 struct typec_altmode_desc 作为所有支持模式的容器。

支持备用模式的端口需要使用以下 API 注册它们支持的每个 SVID

struct typec_altmode *typec_port_register_altmode(struct typec_port *port, const struct typec_altmode_desc *desc)¶: 注册 USB Type-C 端口备用模式

参数

struct typec_port *port: 支持备用模式的 USB Type-C 端口
const struct typec_altmode_desc *desc: 备用模式的描述

描述

此例程用于注册 port 能够支持的备用模式。

成功时返回备用模式的句柄，失败时返回 ERR_PTR。

如果合作伙伴或电缆插头提供 SVID 列表作为对 USB Power Delivery 结构化 VDM Discover SVIDs 消息的响应，则需要注册每个 SVID。

合作伙伴的 API

struct typec_altmode *typec_partner_register_altmode(struct typec_partner *partner, const struct typec_altmode_desc *desc)¶: 注册 USB Type-C 合作伙伴备用模式

参数

struct typec_partner *partner: 支持备用模式的 USB Type-C 合作伙伴
const struct typec_altmode_desc *desc: 备用模式的描述

描述

此例程用于单独注册 partner 在响应 Discover SVIDs 命令时列出的每个备用模式。在 desc 中的数组中需要列出 SVID 在响应 Discover Modes 命令时列出的模式。

成功时返回备用模式的句柄，失败时返回 ERR_PTR。

电缆插头的 API

struct typec_altmode *typec_plug_register_altmode(struct typec_plug *plug, const struct typec_altmode_desc *desc)¶: 注册 USB Type-C 电缆插头备用模式

参数

struct typec_plug *plug: 支持备用模式的 USB Type-C 电缆插头
const struct typec_altmode_desc *desc: 备用模式的描述

描述

此例程用于单独注册 plug 在响应 Discover SVIDs 命令时列出的每个备用模式。在 desc 中的数组中需要列出插头在响应 Discover Modes 命令时列出的 SVID 的模式。

成功时返回备用模式的句柄，失败时返回 ERR_PTR。

因此，端口、合作伙伴和电缆插头将使用它们自己的函数注册备用模式，但注册将始终成功时返回 struct typec_altmode 的句柄，否则返回 NULL。注销将使用相同的函数进行

void typec_unregister_altmode(struct typec_altmode *adev)¶: 注销备用模式

参数

struct typec_altmode *adev: 要注销的备用模式

描述

注销使用 typec_partner_register_altmode()、typec_plug_register_altmode() 或 typec_port_register_altmode() 创建的设备。

如果合作伙伴或电缆插头进入或退出模式，则端口驱动程序需要使用以下 API 通知该类

void typec_altmode_update_active(struct typec_altmode *adev, bool active)¶: 报告进入/退出模式

参数

struct typec_altmode *adev: 备用模式的句柄
bool active: 进入模式时为 True

描述

如果合作伙伴或电缆插头成功执行 Enter/Exit Mode 命令，则驱动程序使用此例程报告模式的更新状态。

多路复用器/解复用器开关¶

USB Type-C 连接器可能在其后有一个或多个多路复用/解复用开关。由于插头可以正向或反向插入，因此需要一个开关来将正确的数据对从连接器路由到 USB 控制器。如果支持备用模式或配件模式，则需要另一个开关，可以将连接器上的引脚路由到 USB 以外的其他组件。USB Type-C 连接器类提供了一个 API 来注册这些开关。

struct typec_switch_dev *typec_switch_register(struct device *parent, const struct typec_switch_desc *desc)¶: 注册 USB Type-C 方向开关

参数

struct device *parent: 父设备
const struct typec_switch_desc *desc: 方向开关描述

描述

此函数注册一个开关，该开关可用于根据 USB Type-C 连接器的电缆插头方向，将正确的数据对路由到 USB 控制器。USB Type-C 插头可以正向或反向插入。

void typec_switch_unregister(struct typec_switch_dev *sw_dev)¶: 注销 USB Type-C 方向开关

参数

struct typec_switch_dev *sw_dev: USB Type-C 方向开关

描述

注销使用 typec_switch_register() 注册的开关。

struct typec_mux_dev *typec_mux_register(struct device *parent, const struct typec_mux_desc *desc)¶: 注册多路复用器，路由 USB Type-C 引脚

参数

struct device *parent: 父设备
const struct typec_mux_desc *desc: 多路复用器描述

描述

当支持配件/备用模式时，USB Type-C 连接器可用于 USB 以外的备用操作模式。在某些模式下，需要重新配置连接器上的引脚。此函数注册多路复用器开关，以路由连接器上的引脚。

void typec_mux_unregister(struct typec_mux_dev *mux_dev)¶: 注销多路复用器开关

参数

struct typec_mux_dev *mux_dev: USB Type-C 连接器多路复用器/解复用器

描述

注销使用 typec_mux_register() 注册的多路复用器。

在大多数情况下，同一个物理多路复用器将处理方向和模式。但是，由于端口驱动程序将负责方向，而备用模式驱动程序将负责模式，因此两者始终分为各自的逻辑组件：“mux”用于模式，“switch”用于方向。

注册端口时，USB Type-C 连接器类会请求端口的多路复用器和开关。然后，驱动程序可以使用以下 API 来控制它们

int typec_set_orientation(struct typec_port *port, enum typec_orientation orientation)¶: 设置 USB Type-C 电缆插头方向

参数

struct typec_port *port: USB Type-C 端口
enum typec_orientation orientation: USB Type-C 电缆插头方向

描述

为 port 设置电缆插头方向。

int typec_set_mode(struct typec_port *port, int mode)¶: 设置 USB Type-C 连接器的操作模式

参数

struct typec_port *port: USB Type-C 连接器
int mode: 配件模式、USB 操作或安全状态

描述

为配件模式 mode 配置 port。此函数将配置 mode 所需的多路复用器。

如果连接器具有双重角色功能，则可能还有一个数据角色开关。USB Type-C 连接器类不提供单独的 API 来处理它们。端口驱动程序可以将 USB 角色类 API 与这些开关一起使用。

支持备用模式的连接器背后的多路复用器示意图

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

Linux 内核

目录

本页

USB Type-C 连接器类¶

简介¶

用户空间接口¶

驱动程序 API¶

注册端口¶

注册合作伙伴¶

注册电缆¶

通知¶

备用模式¶

多路复用器/解复用器开关¶