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¶

註冊埠¶

註冊合作伙伴¶

註冊電纜¶

通知¶

備用模式¶

多路複用器/解複用器開關¶