USB Type-C 备用模式驱动程序的 API

简介

备用模式需要使用 USB Type-C 和 USB 供电规范中定义的供应商定义消息 (VDM) 与合作伙伴进行通信。通信是特定于 SVID（标准或供应商 ID）的，即对于每个备用模式都是特定的，因此每个备用模式都需要自定义驱动程序。

USB Type-C 总线允许通过使用 SVID 和模式号将驱动程序绑定到发现的合作伙伴备用模式。

USB Type-C 连接器类为端口支持的每个备用模式提供一个设备，并为合作伙伴支持的每个备用模式提供单独的设备。备用模式的驱动程序绑定到合作伙伴备用模式设备，端口备用模式设备必须由端口驱动程序处理。

当注册新的合作伙伴备用模式设备时，它会链接到合作伙伴所连接端口的备用模式设备，该设备具有匹配的 SVID 和模式。端口驱动程序和备用模式驱动程序之间的通信将使用相同的 API 进行。

端口备用模式设备用作合作伙伴和备用模式驱动程序之间的代理，因此端口驱动程序仅需要将来自备用模式驱动程序的 SVID 特定命令传递给合作伙伴，以及从合作伙伴传递给备用模式驱动程序。端口驱动程序不需要直接的 SVID 特定通信，但是端口驱动程序需要为端口备用模式设备提供操作回调，就像备用模式驱动程序需要为合作伙伴备用模式设备提供操作回调一样。

用法：

常规

默认情况下，备用模式驱动程序负责进入模式。也可以将进入模式的决定留给用户空间（请参阅 Documentation/ABI/testing/sysfs-class-typec）。端口驱动程序不应自行进入任何模式。

->vdm 是操作回调向量中最重要的回调。它将用于将来自合作伙伴的所有 SVID 特定命令传递给备用模式驱动程序，反之亦然（对于端口驱动程序）。驱动程序使用 typec_altmode_vdm() 相互发送 SVID 特定命令。

如果使用 SVID 特定命令与合作伙伴通信导致需要重新配置连接器上的引脚，则备用模式驱动程序需要使用 typec_altmode_notify() 通知总线。驱动程序将协商的 SVID 特定引脚配置值作为参数传递给该函数。然后，总线驱动程序将使用该值作为多路复用器的状态值来配置连接器后面的多路复用器。

注意：SVID 特定引脚配置值必须始终从 TYPEC_STATE_MODAL 开始。USB Type-C 规范为连接器定义了两个默认状态：TYPEC_STATE_USB 和 TYPEC_STATE_SAFE。这些值由总线保留为状态的第一个可能值。进入备用模式后，总线会将连接器置于 TYPEC_STATE_SAFE 状态，然后再发送 USB Type-C 规范中定义的 Enter 或 Exit Mode 命令，并在退出模式后将连接器恢复为 TYPEC_STATE_USB 状态。

SVID 特定引脚配置的工作定义示例可能如下所示

enum {
    ALTMODEX_CONF_A = TYPEC_STATE_MODAL,
    ALTMODEX_CONF_B,
    ...
};

还可以使用辅助宏 TYPEC_MODAL_STATE()

#define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0);
#define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1);

电缆插头备用模式

备用模式驱动程序不绑定到电缆插头备用模式设备，仅绑定到合作伙伴备用模式设备。如果备用模式支持或需要响应 SOP Prime，并且可以选择响应 SOP Double Prime 消息的电缆，则该备用模式的驱动程序必须使用 typec_altmode_get_plug() 请求电缆插头备用模式的句柄，并接管其控制权。

驱动程序 API

备用模式结构

struct typec_altmode_ops

备用模式特定操作向量

定义:

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

平台和备用模式之间的通信通道

activate

用于 Enter/Exit Mode 的用户回调

struct typec_altmode_driver

USB Type-C 备用模式设备驱动程序

定义:

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

SVID 的空终止数组

probe

用于设备绑定的回调

remove

用于设备取消绑定的回调

driver

设备驱动程序模型驱动程序

描述

这些驱动程序将绑定到合作伙伴备用模式设备。它们将处理所有 SVID 特定通信。

备用模式驱动程序注册/注销

typec_altmode_register_driver

typec_altmode_register_driver (drv)

注册 USB Type-C 备用模式设备驱动程序

参数

drv

指向 struct typec_altmode_driver 的指针

描述

这些驱动程序将绑定到合作伙伴备用模式设备。它们将处理所有 SVID 特定通信。

void typec_altmode_unregister_driver(struct typec_altmode_driver *drv)

注销 USB Type-C 备用模式设备驱动程序

参数

struct typec_altmode_driver *drv

指向 struct typec_altmode_driver 的指针

描述

这些驱动程序将绑定到合作伙伴备用模式设备。它们将处理所有 SVID 特定通信。

备用模式驱动程序操作

int typec_altmode_notify(struct typec_altmode *adev, unsigned long conf, void *data)

操作系统和备用模式驱动程序之间的通信

参数

struct typec_altmode *adev

备用模式的句柄

unsigned long conf

备用模式特定配置值

void *data

备用模式特定数据

描述

此函数的主要目的是允许备用模式驱动程序告知已与合作伙伴协商的引脚配置。然后，该信息将用于例如配置多路复用器。也可以进行其他方向的通信，并且低级设备驱动程序也可以向备用模式驱动程序发送通知。实际通信将特定于每个 SVID。

int typec_altmode_enter(struct typec_altmode *adev, u32 *vdo)

进入模式

参数

struct typec_altmode *adev

备用模式

u32 *vdo

用于 Enter Mode 命令的 VDO

描述

备用模式驱动程序使用此函数进入模式。端口驱动程序使用此函数通知备用模式驱动程序合作伙伴已启动 Enter Mode 命令。如果备用模式不需要 VDO，则 vdo 必须为 NULL。

int typec_altmode_exit(struct typec_altmode *adev)

退出模式

参数

struct typec_altmode *adev

备用模式

描述

adev 的合作伙伴已启动 Exit Mode 命令。

int typec_altmode_attention(struct typec_altmode *adev, u32 vdo)

注意命令

参数

struct typec_altmode *adev

备用模式

u32 vdo

注意命令的 VDO

描述

通知 adev 的合作伙伴关于注意命令。

int typec_altmode_vdm(struct typec_altmode *adev, const u32 header, const u32 *vdo, int count)

向合作伙伴发送厂商定义消息 (VDM)

参数

struct typec_altmode *adev

备用模式句柄

const u32 header

VDM 头部

const u32 *vdo

厂商定义数据对象数组

int count

数据对象数量

描述

备用模式驱动程序使用此函数与合作伙伴进行 SVID 特定通信。端口驱动程序使用它将从合作伙伴接收的结构化 VDM 传递给备用模式驱动程序。

端口驱动程序的 API

struct typec_altmode *typec_match_altmode(struct typec_altmode **altmodes, size_t n, u16 svid, u8 mode)

将 SVID 和模式匹配到备用模式数组

参数

struct typec_altmode **altmodes

备用模式数组

size_t n

数组中的元素数量，或 -1 表示以 NULL 结尾的数组

u16 svid

要匹配的标准或厂商 ID

u8 mode

要匹配的模式

描述

返回指向 SVID 与 svid 匹配的备用模式的指针，如果未找到匹配项，则返回 NULL。

电缆插头操作

struct typec_altmode *typec_altmode_get_plug(struct typec_altmode *adev, enum typec_plug_index index)

查找电缆插头备用模式

参数

struct typec_altmode *adev

合作伙伴备用模式的句柄

enum typec_plug_index index

电缆插头索引

描述

增加电缆插头备用模式设备的引用计数。返回电缆插头备用模式的句柄，如果未找到则返回 NULL。

void typec_altmode_put_plug(struct typec_altmode *plug)

减少电缆插头备用模式引用计数

参数

struct typec_altmode *plug

电缆插头备用模式的句柄