USB Type-C Alternate Mode 驱动程序的 API¶
简介¶
Alternate Mode 需要使用供应商定义消息 (VDM) 与伙伴通信,如 USB Type-C 和 USB Power Delivery 规范中所定义。该通信是 SVID(标准或供应商 ID)特定的,即对于每个 Alternate Mode 都是特定的,因此每个 Alternate Mode 都需要一个自定义驱动程序。
USB Type-C 总线允许通过使用 SVID 和模式编号将驱动程序绑定到已发现的伙伴 Alternate Mode。
USB Type-C 连接器类 为端口支持的每个 Alternate Mode 提供一个设备,并为伙伴支持的每个 Alternate Mode 提供单独的设备。Alternate Mode 的驱动程序绑定到伙伴 Alternate Mode 设备,并且端口 Alternate Mode 设备必须由端口驱动程序处理。
当注册新的伙伴 Alternate Mode 设备时,它会链接到伙伴所连接的端口的 Alternate Mode 设备,该设备具有匹配的 SVID 和模式。端口驱动程序和 Alternate Mode 驱动程序之间的通信将使用相同的 API 进行。
端口 Alternate Mode 设备用作伙伴和 Alternate Mode 驱动程序之间的代理,因此端口驱动程序仅需要将来自 Alternate Mode 驱动程序的 SVID 特定命令传递给伙伴,并将来自伙伴的 SVID 特定命令传递给 Alternate Mode 驱动程序。端口驱动程序不需要直接的 SVID 特定通信,但是端口驱动程序需要为端口 Alternate Mode 设备提供操作回调,就像 Alternate Mode 驱动程序需要为伙伴 Alternate Mode 设备提供操作回调一样。
用法:¶
常规¶
默认情况下,Alternate Mode 驱动程序负责进入模式。也可以将有关进入模式的决定留给用户空间(参见 ABI 文件测试/sysfs-class-typec)。端口驱动程序不应自行进入任何模式。
->vdm
是操作回调向量中最重要的回调。它将用于将来自伙伴的所有 SVID 特定命令传递给 Alternate Mode 驱动程序,反之亦然,对于端口驱动程序也是如此。驱动程序使用 typec_altmode_vdm()
相互发送 SVID 特定命令。
如果使用 SVID 特定命令与伙伴通信导致需要重新配置连接器上的引脚,则 Alternate Mode 驱动程序需要使用 typec_altmode_notify()
通知总线。驱动程序将协商的 SVID 特定引脚配置值作为参数传递给该函数。然后,总线驱动程序将使用该值作为 mux 的状态值来配置连接器后面的 mux。
注意:SVID 特定引脚配置值必须始终从 TYPEC_STATE_MODAL
开始。USB Type-C 规范为连接器定义了两个默认状态:TYPEC_STATE_USB
和 TYPEC_STATE_SAFE
。这些值由总线保留作为状态的第一个可能值。当进入 Alternate Mode 时,总线会将连接器置于 TYPEC_STATE_SAFE
,然后在发送 Enter 或 Exit Mode 命令之前,如 USB Type-C 规范中所定义,并在退出模式后将连接器恢复到 TYPEC_STATE_USB
。
SVID 特定引脚配置的工作定义示例如下
enum {
ALTMODEX_CONF_A = TYPEC_STATE_MODAL,
ALTMODEX_CONF_B,
...
};
Helper 宏 TYPEC_MODAL_STATE()
也可以使用
#define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0);
#define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1);
电缆插头 Alternate Mode¶
Alternate Mode 驱动程序不绑定到电缆插头 Alternate Mode 设备,而仅绑定到伙伴 Alternate Mode 设备。如果 Alternate Mode 支持或需要响应 SOP Prime,以及可选的 SOP Double Prime 消息的电缆,则该 Alternate Mode 的驱动程序必须使用 typec_altmode_get_plug()
请求处理电缆插头 Alternate Mode,并接管它们的控制。
驱动程序 API¶
Alternate Mode 结构体¶
-
struct typec_altmode_ops¶
Alternate Mode 特定操作向量
定义:
struct typec_altmode_ops {
int (*enter)(struct typec_altmode *altmode, u32 *vdo);
int (*exit)(struct typec_altmode *altmode);
void (*attention)(struct typec_altmode *altmode, u32 vdo);
int (*vdm)(struct typec_altmode *altmode, const u32 hdr, const u32 *vdo, int cnt);
int (*notify)(struct typec_altmode *altmode, unsigned long conf, void *data);
int (*activate)(struct typec_altmode *altmode, int activate);
};
成员
enter
要使用 Enter Mode 命令执行的操作
exit
要使用 Exit Mode 命令执行的操作
attention
Attention 命令的回调
vdm
SVID 特定命令的回调
notify
平台和 Alternate Mode 的通信通道
activate
Enter/Exit Mode 的用户回调
-
struct typec_altmode_driver¶
USB Type-C Alternate Mode 设备驱动程序
定义:
struct typec_altmode_driver {
const struct typec_device_id *id_table;
int (*probe)(struct typec_altmode *altmode);
void (*remove)(struct typec_altmode *altmode);
struct device_driver driver;
};
成员
id_table
以 NULL 结尾的 SVID 数组
probe
设备绑定的回调
remove
设备解除绑定的回调
driver
设备驱动程序模型驱动程序
描述
这些驱动程序将绑定到伙伴 Alternate Mode 设备。它们将处理所有 SVID 特定通信。
Alternate Mode 驱动程序注册/注销¶
-
typec_altmode_register_driver¶
typec_altmode_register_driver (drv)
注册 USB Type-C Alternate Mode 设备驱动程序
-
void typec_altmode_unregister_driver(struct typec_altmode_driver *drv)¶
注销 USB Type-C Alternate Mode 设备驱动程序
参数
struct typec_altmode_driver *drv
指向
struct typec_altmode_driver
的指针
描述
这些驱动程序将绑定到伙伴 Alternate Mode 设备。它们将处理所有 SVID 特定通信。
Alternate Mode 驱动程序操作¶
-
int typec_altmode_notify(struct typec_altmode *adev, unsigned long conf, void *data)¶
操作系统和 Alternate Mode 驱动程序之间的通信
参数
struct typec_altmode *adev
Alternate Mode 的句柄
unsigned long conf
Alternate Mode 特定配置值
void *data
Alternate Mode 特定数据
描述
此函数的主要目的是允许 Alternate Mode 驱动程序告知与伙伴协商了哪个引脚配置。然后,该信息将用于例如配置 mux。也可以向另一个方向通信,并且底层设备驱动程序也可以向 Alternate Mode 驱动程序发送通知。实际通信对于每个 SVID 都是特定的。
-
int typec_altmode_enter(struct typec_altmode *adev, u32 *vdo)¶
进入模式
参数
struct typec_altmode *adev
Alternate Mode
u32 *vdo
Enter Mode 命令的 VDO
描述
Alternate Mode 驱动程序使用此函数进入模式。端口驱动程序使用它来通知 Alternate Mode 驱动程序伙伴已启动 Enter Mode 命令。如果 Alternate Mode 不需要 VDO,则 vdo 必须为 NULL。
-
int typec_altmode_exit(struct typec_altmode *adev)¶
退出模式
参数
struct typec_altmode *adev
Alternate Mode
描述
adev 的伙伴已启动 Exit Mode 命令。
-
int typec_altmode_attention(struct typec_altmode *adev, u32 vdo)¶
Attention 命令
参数
struct typec_altmode *adev
Alternate Mode
u32 vdo
Attention 命令的 VDO
描述
通知 adev 的伙伴有关 Attention 命令。
-
int typec_altmode_vdm(struct typec_altmode *adev, const u32 header, const u32 *vdo, int count)¶
将供应商定义消息 (VDM) 发送到伙伴
参数
struct typec_altmode *adev
Alternate Mode 句柄
const u32 header
VDM 标头
const u32 *vdo
供应商定义数据对象数组
int count
数据对象数
描述
Alternate Mode 驱动程序使用此函数与伙伴进行 SVID 特定通信。端口驱动程序使用它将从伙伴收到的结构化 VDM 传递给 Alternate Mode 驱动程序。
端口驱动程序的 API¶
-
struct typec_altmode *typec_match_altmode(struct typec_altmode **altmodes, size_t n, u16 svid, u8 mode)¶
将 SVID 和模式匹配到 Alternate Mode 数组
参数
struct typec_altmode **altmodes
Alternate Mode 数组
size_t n
数组中的元素数,对于以 NULL 结尾的数组为 -1
u16 svid
要匹配的标准或供应商 ID
u8 mode
要匹配的模式
描述
返回指向 SVID 与 svid 匹配的 Alternate Mode 的指针,或者在未找到匹配项时返回 NULL。
电缆插头操作¶
-
struct typec_altmode *typec_altmode_get_plug(struct typec_altmode *adev, enum typec_plug_index index)¶
查找电缆插头 Alternate Mode
参数
struct typec_altmode *adev
伙伴 Alternate Mode 的句柄
enum typec_plug_index index
电缆插头索引
描述
增加电缆插头 Alternate Mode 设备的引用计数。返回电缆插头 Alternate Mode 的句柄,如果未找到,则返回 NULL。
-
void typec_altmode_put_plug(struct typec_altmode *plug)¶
减少电缆插头 Alternate Mode 引用计数
参数
struct typec_altmode *plug
电缆插头 Alternate Mode 的句柄