USB Type-C 连接器类¶

简介¶

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

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

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

该类为此文档中描述的端口驱动程序提供了一个 API。属性在 Documentation/ABI/testing/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 电源传输规范第 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 电源传输能力，并且端口驱动程序能够显示 Discover Identity 命令的结果，则合作伙伴描述符结构应包含 struct usb_pd_identity 实例的句柄。然后，该类将在合作伙伴设备下为身份创建一个 sysfs 目录。然后可以使用以下 API 报告 Discover Identity 命令的结果

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

参数

struct typec_partner *partner: 合作伙伴更新的身份值

描述

此例程用于报告 Discover Identity USB 电源传输命令的结果已变为可用。

注册电缆¶

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

插头表示为它们自己的设备。首先注册电缆，然后注册电缆插头。电缆将是插头的父设备。有关电缆的详细信息需要在 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: 要注销的电缆

描述

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

如果注册成功，该类将提供一个指向 struct typec_cable 和 struct typec_plug 的句柄，否则返回 NULL。

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

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

参数

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

描述

此例程用于报告 Discover Identity USB 电源传输命令的结果已变为可用。

通知¶

当伙伴执行角色更改时，或者当伙伴或电缆连接期间默认角色发生变化时，端口驱动程序必须使用以下 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 时为 Source，否则为 Sink

描述

端口驱动程序使用此例程报告 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 命令时列出的每个备用模式。响应 Discover Modes 命令时列出的 SVID 的模式需要在 **desc** 中的数组中列出。

成功时返回备用模式的句柄，失败时返回 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 命令而列出的每个备用模式。插头为响应 Discover Modes 命令而列出的 SVID 的模式需要在 desc 中的数组中列出。

成功时返回备用模式的句柄，失败时返回 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

描述

如果伙伴或电缆插头成功执行进入/退出模式命令，驱动程序将使用此例程报告模式的更新状态。

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

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() 注册的多路复用器。

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

注册端口时，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¶

注册端口¶

注册合作伙伴¶

注册电缆¶

通知¶

备用模式¶

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