Linux内核USB总线--设备控制器驱动框架分析_usb_function_register

正文

1.概述

如下图所示，USB控制器可以呈现出两种不同的状态。USB控制器作为Host时，称为USB主机控制器，使用USB主机控制器驱动。USB控制器作为Device时，称为USB设备控制器，使用UDC（usb device controller）驱动。本节只分析USB控制器作为Device时的驱动框架。

USB控制器作为Device时，驱动框架可分为5层。最上层的是Gadget Function驱动，代表了具体设备的驱动，如大容量存储设备驱动（U盘、移动硬盘等）、通讯类设备驱动（USB串口、USB虚拟网卡等）、UAC驱动（USB麦克风、USB声卡等USB音频类设备）。接下来是Gadget Funcation API层，该层是一个抽象层，向上和向下提供统一的API，屏蔽了差异，提高了驱动的兼容性。Composite层是一个可选的中间层，可通过一种配置或多种配置高效的支持多种功能的设备，简化了USB复合设备驱动的开发。目前最流行的是使用基于Composite和configfs实现的USB gadget configfs，可在用户空间灵活的配置USB设备。UDC驱动直接访问硬件，控制USB设备与USB主机之间的通信。USB设备控制器通过USB线缆连接USB主机控制器，负责USB数据的发送和接收。

2.Gadget Function驱动

Linux内核的USB Gadget Function驱动都在drivers/usb/gadget/function/目录下，有通讯设备类（Communication Device Class）驱动（f_acm.c、f_ecm、f_serial.c等）、USB音频设备类驱动（f_uac1.c、f_uac2.c、u_audio.c）、大容量存储设备驱动（f_mass_storage.c）、USB视频设备类驱动（f_uvc.c）等。

Gadget Function驱动的入口使用usb_function_driver数据结构描述，驱动需要实现alloc_inst和alloc_func函数。alloc_inst创建usb_function_instance数据结构并初始化。alloc_func创建usb_function并初始化，重点是设置里面的回调函数，通常情况下，不直接使用usb_function数据结构，而是嵌入到驱动的数据结构中使用。Composite驱动会通过Gadget Function API回调alloc_inst和alloc_func函数。usb_function了描述Gadget Function驱动，Gadget Function驱动的重点是实现这些回调函数。

[include/linux/usb/composite.h]
struct usb_function_driver {
    const char *name;
    struct module *mod;
    struct list_head list;
    // 创建usb_function_instance并初始化
    struct usb_function_instance *(*alloc_inst)(void);
    // 创建usb_function并初始化
    struct usb_function *(*alloc_func)(struct usb_function_instance *inst);
};
struct usb_function {  // 描述了一个gadget Function驱动
    const char			*name;  // gadget Function驱动名称
    struct usb_gadget_strings	**strings;  // 字符串表，由bind分配和控制请求提供的语言IDs
    struct usb_descriptor_header	**fs_descriptors; // full speed描述符
    struct usb_descriptor_header	**hs_descriptors; // high speed描述符
    struct usb_descriptor_header	**ss_descriptors; // super speed描述符
    struct usb_configuration	*config;  // usb_add_function函数添加的配置
    // 驱动的bind回调函数，分配驱动所需的资源，如配置、端点、I/O缓冲区等
    int	(*bind)(struct usb_configuration *, struct usb_function *);
    // 释放bind分配的资源
    void (*unbind)(struct usb_configuration *, struct usb_function *);
    void (*free_func)(struct usb_function *f);  // 释放usb_function
    // 设置可选的配置，有时候驱动可能有多个配置，需要使用set_alt进行切换
    int (*set_alt)(struct usb_function *, unsigned interface, unsigned alt);
    // 获取当前的设置的可选配置，如果没有多个配置，则默认使用配置0，则返回0
    int (*get_alt)(struct usb_function *, unsigned interface);
    // disable gadget function驱动，主机复位、主机重新配置gadget、断开连接时使用
    void (*disable)(struct usb_function *);
    // 用于特殊接口的控制请求
    int	(*setup)(struct usb_function *, const struct usb_ctrlrequest *);
    // 测试某些设备类请求能否被处理
    bool (*req_match)(struct usb_function *, const struct usb_ctrlrequest *);
    void (*suspend)(struct usb_function *);
    void (*resume)(struct usb_function *);
    /* USB 3.0 additions */
    // 向GetStatus请求返回当前gadget Function驱动的状态
    int (*get_status)(struct usb_function *);  
    // 当接收到SetFeature(FUNCTION_SUSPEND)时，回调该函数
    int (*func_suspend)(struct usb_function *, u8 suspend_opt);
    /* private: internals */
    struct list_head		list;
    DECLARE_BITMAP(endpoints, 32);  // 端点位图
    const struct usb_function_instance *fi;
    unsigned int		bind_deactivated:1;
};

usb_function_driver通常使用DECLARE_USB_FUNCTION_INIT宏定义并初始化。将宏展开后，其定义了usb_function_driver结构体实例，主要设置alloc_inst和alloc_func成员，前置用于创建usb_function_instance，表示一个Gadget Function实例，后者用于创建usb_function并初始化。usb_function中的方法实现了具体的Gadget Function驱动。usb_function_register和usb_function_unregister函数完成usb_function_driver结构体的注册和注销。

[include/linux/usb/composite.h]
#define DECLARE_USB_FUNCTION_INIT(_name, _inst_alloc, _func_alloc)	\
    DECLARE_USB_FUNCTION(_name, _inst_alloc, _func_alloc)		\
    static int __init _name ## mod_init(void)			\
    {								\
        return usb_function_register(&_name ## usb_func);	\  // 注册UAC设备驱动
    }								\
    static void __exit _name ## mod_exit(void)			\
    {								\
        usb_function_unregister(&_name ## usb_func);		\  // 注销UAC设备驱动
    }								\
    module_init(_name ## mod_init);					\  // 模块初始化
    module_exit(_name ## mod_exit)                     // 模块卸载
 
#define DECLARE_USB_FUNCTION(_name, _inst_alloc, _func_alloc)		\
    // 定义UAC2.0的Gadget Function驱动，名称为uac2_usb_func
    static struct usb_function_driver _name ## usb_func = {		\
        .name = __stringify(_name),				\  // 驱动名称为uac2
        .mod  = THIS_MODULE,					\
        .alloc_inst = _inst_alloc,				\
        .alloc_func = _func_alloc,				\
    };								\
    MODULE_ALIAS("usbfunc:"__stringify(_name));

3.Gadget Function API

Gadget Funcation API是一个抽象层，上层的Gadget Function驱动使用Gadget Funcation API注册和注销，下层的Composite驱动使用Gadget Funcation API和Gadget Function驱动绑定和匹配。Gadget Function驱动需要实现usb_function_driver数据结构并向Gadget Funcation API层注册。

Gadget Function API的主要API如下。usb_function_register将注册的usb_function_driver挂到func_list链表中。usb_function_instance函数会遍历func_list链表，将参数name和usb_function_driver的name进行对比，若名称一致，则匹配成功，接着调用匹配成功的usb_function_driver中的alloc_inst回调函数获取usb_function_instance，然后将usb_function_driver的指针设置到usb_function_instance中，最后返回usb_function_instance的指针。usb_get_function函数通过回调alloc_func函数获取并初始化usb_function。其他API可参考源代码。

[drivers/usb/gadget/functions.c]
// 向Gadget Function API层注册Gadget Function驱动
int usb_function_register(struct usb_function_driver *newf)
// 注销Gadget Function驱动
void usb_function_unregister(struct usb_function_driver *fd)
// 从Gadget Function API层获取usb_function_instance
struct usb_function_instance *usb_get_function_instance(const char *name)
// 回调free_func_inst销毁usb_function_instance
void usb_put_function_instance(struct usb_function_instance *fi)
// 从Gadget Function API层获取usb_function_instance
struct usb_function *usb_get_function(struct usb_function_instance *fi)
// 回调free_func销毁usb_function
void usb_put_function(struct usb_function *f)

4.Composite层

USB Composite的核心数据结构为usb_composite_driver。Composite驱动必须实现设备描述符dev和bind回调函数。

Composite（复合）设备使用usb_composite_dev数据结构描述，该数据结构在Composite驱动注册的时候内核会在驱动bind函数调用之前自动创建，不需要驱动创建。

gadget指向dwc3结构体中的usb_gadget。req在Composite驱动注册的时候就提前分配好，用于响应主机发送的控制请求。config指向当前使用的usb配置。desc是当前设备的描述符，在Composite驱动注册的时候设置。driver指向对应的usb_composite_driver。usb_composite_driver结构体包含了usb_gadget_driver数据结构，用来表示usb设备驱动。

[include/linux/usb/composite.h]
struct usb_composite_driver {
    const char  *name;  // 驱动名称
    const struct usb_device_descriptor *dev;  // 设备描述符，必须定义
    struct usb_gadget_strings  **strings;
    enum usb_device_speed  max_speed;  // 设备支持的最大速度
    unsigned  needs_serial:1;
    // 用于分配整个设备共享的资源，使用usb_add_config添加配置，必须实现
    int  (*bind)(struct usb_composite_dev *cdev);  
    int  (*unbind)(struct usb_composite_dev *);       // 销毁资源
    void  (*disconnect)(struct usb_composite_dev *);  // 可选的驱动disconnect method
    /* global suspend hooks */
    void  (*suspend)(struct usb_composite_dev *);
    void  (*resume)(struct usb_composite_dev *);
    // composite驱动层提供了默认的实现，即composite_driver_template
    struct usb_gadget_driver  gadget_driver;  
};
struct usb_composite_dev {  // 复合设备
    // 只读，usb设备控制器的抽象，指向dwc3结构体中的usb_gadget
	struct usb_gadget		*gadget;  
	struct usb_request		*req;     // 用于响应控制请求，缓冲区提前分配好
	struct usb_request		*os_desc_req;  // 用于响应OS描述符，缓冲区提前分配
	struct usb_configuration	*config;  // 当前使用配置
    //  qwSignature part of the OS string
	u8		qw_sign[OS_STRING_QW_SIGN_LEN]; 
	u8		b_vendor_code; // bMS_VendorCode part of the OS string
	struct usb_configuration *os_desc_config;  // OS描述符使用的配置
	unsigned int			use_os_string:1;
	unsigned int			suspended:1;
	struct usb_device_descriptor desc; // 设备描述符
	struct list_head		configs;
	struct list_head		gstrings;
	struct usb_composite_driver	*driver;  // 指向Composite驱动
    ......
};

4.1.legacy

inux内核中直接使用Composite层的USB gadget legacy驱动大多都在drivers/usb/gadget/legacy/目录下，如USB音频设备驱动文件audio.c，USB虚拟以太网设备驱动文件ether.c，HID设备驱动文件hid.c。legacy驱动可以直接使用内核提供的module_usb_composite_driver宏，方便定义Composite驱动。参数为usb_composite_driver结构体。使用usb_composite_probe注册Composite驱动。使用usb_composite_unregister函数注销Composite驱动。

[include/linux/usb/composite.h]
#define module_usb_composite_driver(__usb_composite_driver) \
	module_driver(__usb_composite_driver, usb_composite_probe, \
		       usb_composite_unregister)
 
[include/linux/device.h]
#define module_driver(__driver, __register, __unregister, ...) \
static int __init __driver##_init(void) \  // 初始化函数
{ \
    return __register(&(__driver) , ##__VA_ARGS__); \
} \
module_init(__driver##_init); \
static void __exit __driver##_exit(void) \  // 注销函数
{ \
    __unregister(&(__driver) , ##__VA_ARGS__); \
} \
module_exit(__driver##_exit);

usb_composite_probe和usb_composite_unregister函数的定义如下。usb_composite_probe初始化复合设备驱动，usb_composite_unregister卸载复合设备驱动。

[include/linux/usb/composite.h]
/**
 * usb_composite_probe() - register a composite driver
 * @driver: the driver to register
 *
 * Context: single threaded during gadget setup
 *
 * This function is used to register drivers using the composite driver
 * framework.  The return value is zero, or a negative errno value.
 * Those values normally come from the driver's @bind method, which does
 * all the work of setting up the driver to match the hardware.
 *
 * On successful return, the gadget is ready to respond to requests from
 * the host, unless one of its components invokes usb_gadget_disconnect()
 * while it was binding.  That would usually be done in order to wait for
 * some userspace participation.
 */
int usb_composite_probe(struct usb_composite_driver *driver)
/**
 * usb_composite_unregister() - unregister a composite driver
 * @driver: the driver to unregister
 *
 * This function is used to unregister drivers using the composite
 * driver framework.
 */
void usb_composite_unregister(struct usb_composite_driver *driver)

内核在Composite驱动层实现了usb_gadget_driver，即composite_driver_template变量，所有复合设备都使用该数据结构，无需驱动实现。

Composite驱动使用usb_composite_probe注册时，内核会将composite_driver_template中的数据拷贝到usb_composite_driver的gadget_driver成员。

[drivers/usb/gadget/composite.c]
static const struct usb_gadget_driver composite_driver_template = {  // 内核实现的usb设备驱动
	.bind		= composite_bind,
	.unbind		= composite_unbind,
	.setup		= composite_setup,
	.reset		= composite_disconnect,
	.disconnect	= composite_disconnect,
	.suspend	= composite_suspend,
	.resume		= composite_resume,
	.driver	= {
		.owner		= THIS_MODULE,
	},
};

4.2.USB Gadget Configfs

Configfs是一种基于ram的文件系统，可以在用户空间直接控制内核对象，主要适用于内核对象有众多配置的模块，比如USB复合设备。Linux 3.11版本引入了USB Gadget Configfs。在用户层可以通过暴漏出来的API定义USB Gadget设备的任意功能和配置，极大的方便了USB复合设备的配置和使用。该部分内容后面将会详细介绍原理和使用方法。USB Gadget Configfs在drivers/usb/gadget/configfs.c文件中实现。

【文章福利】小编推荐自己的Linux内核技术交流群： 【977878001】整理一些个人觉得比较好得学习书籍、视频资料；进群私聊群管理领取 内核资料包（含视频教程、电子书、实战项目及代码）

内核资料直通车：Linux内核源码技术学习路线+视频教程代码资料

学习直通车：Linux内核源码/内存调优/文件系统/进程管理/设备驱动/网络协议栈

5.UDC驱动

5.1.函数接口

UDC驱动模块定义如下，内核初始化或模块加载时初始化，创建udc_class，设置uevent的回调函数为usb_udc_uevent。

[drivers/usb/gadget/udc/core.c]
static struct class *udc_class;
static int __init usb_udc_init(void)
{
	udc_class = class_create(THIS_MODULE, "udc");
    ......
    udc_class->dev_uevent = usb_udc_uevent;
    return 0;
}
subsys_initcall(usb_udc_init);
 
static void __exit usb_udc_exit(void)
{
	class_destroy(udc_class);
}
module_exit(usb_udc_exit);

使用usb_add_gadget_udc注册UDC驱动，首先分配一个usb_udc数据结构，初始化相关成员，最后将usb_udc挂到udc_list链表中，注册成功后UDC的状态为USB_STATE_NOTATTACHED。使用usb_del_gadget_udc删除UDC驱动，首先回调pullup断开连接，然后回调udc_stop停止USB设备控制器，最后从udc_list链表中删除usb_udc。

[drivers/usb/gadget/udc/core.c]
/**
 * usb_add_gadget_udc - adds a new gadget to the udc class driver list
 * @parent: the parent device to this udc. Usually the controller
 * driver's device.
 * @gadget: the gadget to be added to the list
 *
 * Returns zero on success, negative errno otherwise.
 */
int usb_add_gadget_udc(struct device *parent, struct usb_gadget *gadget)
/**
 * usb_del_gadget_udc - deletes @udc from udc_list
 * @gadget: the gadget to be removed.
 *
 * This, will call usb_gadget_unregister_driver() if
 * the @udc is still busy.
 */
void usb_del_gadget_udc(struct usb_gadget *gadget)

Composite驱动调用usb_gadget_probe_driver和UDC驱动匹配，首先遍历udc_list链表，若有usb_udc的driver成员为空，则表示匹配成功，接着Composite驱动和UDC驱动绑定，通过将Composite驱动的usb_composite_driver.gadget_driver的地址设置到usb_udc.driver成员中完成绑定，最后回调udc_start启动USB设备控制器。调用usb_gadget_unregister_driver解除Composite驱动和UDC驱动的绑定关系。

[drivers/usb/gadget/udc/core.c]
int usb_gadget_probe_driver(struct usb_gadget_driver *driver)
int usb_gadget_unregister_driver(struct usb_gadget_driver *driver)

UDC层还向USB devcie function驱动提供了一些的接口，用来开启和关闭USB设备控制器、使能和禁止端点、queues/dequeues I/O请求、分配和释放usb_request、匹配端点等。这些函数内部会调用具体的USB设备控制器的UDC驱动。RK3399平台上，就会调用dwc3实现的UDC驱动。至于具体内容，后面章节在分析dwc3的UDC驱动时会详细说明。

[drivers/usb/gadget/udc/core.c]
int usb_ep_enable(struct usb_ep *ep)   // 使能端点
int usb_ep_disable(struct usb_ep *ep)  // 禁止端点
int usb_ep_queue(struct usb_ep *ep, struct usb_request *req, gfp_t gfp_flags)  // queues usb_request 
int usb_ep_dequeue(struct usb_ep *ep, struct usb_request *req)  // dequeue usb_request
struct usb_request *usb_ep_alloc_request(struct usb_ep *ep, gfp_t gfp_flags)  // 分配usb_request 
void usb_ep_free_request(struct usb_ep *ep, struct usb_request *req)  // 释放usb_request 
// 根据描述符，匹配要使用的端点
int usb_gadget_ep_match_desc(struct usb_gadget *gadget, struct usb_ep *ep,
		struct usb_endpoint_descriptor *desc, struct usb_ss_ep_comp_descriptor *ep_comp)

5.2.数据结构

UDC驱动使用usb_udc数据结构描述，注册的所有usb_udc数据结构都会挂到udc_list链表上。UDC驱动的功能主要由成员gadget实现，即usb_gadget数据结构。struct usb_gadget_driver由composite层实现，用于连接USB Function驱动和UDC驱动。usb_gadget_ops是USB设备控制器的硬件操作函数，包含启动USB设备控制器、停止USB设备控制器、vbus电源等功能。ep0表示端点0，驱动注册时会提前分配好，用于响应控制请求。除端点0外，USB设备驱动还会使用其他的端点，这些端点数据结构挂到ep_list链表中。speed表示USB设备控制器当前的速度。max_speed表示USB设备控制器最大的速度。

[drivers/usb/gadget/udc/core.c]
static LIST_HEAD(udc_list);
struct usb_udc {  // 描述usb设备控制器
    // 指向Composite驱动中的usb_gadget_driver
	struct usb_gadget_driver *driver;
    // 实现udc驱动的结构体，包含usb设备控制器硬件操作函数
	struct usb_gadget		*gadget;  
	struct device			dev;
    // usb_udc结构体可以组成一个链表
	struct list_head		list;
	bool		vbus;  // 对于不关心vbus状态的udc，该值始终为true
};
[include/linux/usb/gadget.h]
struct usb_gadget {
    // 用于sysfs_notify的工作队列
	struct work_struct		work;
	struct usb_udc			*udc;  // 指向usb_udc
    // usb设备控制器硬件操作函数，不涉及io操作
	const struct usb_gadget_ops	*ops;  
	struct usb_ep *ep0;  // 端点0，用于响应控制读写请求
	struct list_head ep_list; // 该usb设备驱动所需的所有端点链表
	enum usb_device_speed speed;  // 当前连接usb主机的速度
	enum usb_device_speed max_speed;  // udc驱动支持的最大速度
	enum usb_device_state state;  // 当前的状态
	const char *name;  // udc驱动名称，用与确认控制器硬件类型
	struct device  dev;
	unsigned out_epnum;  // 最近使用的输出端点编号
	unsigned in_epnum;   // 最近使用的输入端点编号
	unsigned mA;         // 最近设置的mA值
	struct usb_otg_caps *otg_caps; // OTG的能力
	unsigned sg_supported:1;       // 是否支持聚合DMA
	unsigned is_otg:1;  // 是否支持OTG，支持OTG必须提供OTG描述符
	unsigned is_a_peripheral:1;    // 一般为false除非支持OTG
    // 输出端点的请求缓冲区大小按MaxPacketSize对齐
	unsigned quirk_ep_out_aligned_size:1;  
	unsigned is_selfpowered:1;  // 是否是自供电
	unsigned connected:1;       // 是否连接成功
	unsigned uvc_enabled:1;     // uvc功能是否使能
    ......
};
struct usb_gadget_driver {
	char *function;  // 描述usb_gadget_driver的字符串
	enum usb_device_speed	max_speed;  // 该驱动可处理的最大速度
    // 回调函数，可通过该函数绑定上层的gadget function驱动
	int	(*bind)(struct usb_gadget *gadget, struct usb_gadget_driver *driver);
	void (*unbind)(struct usb_gadget *);
    // 端点0控制请求调用，用于描述符和配置的管理，通常在中断中调用，不可睡眠
	int	(*setup)(struct usb_gadget *, const struct usb_ctrlrequest *);
    // 当主机断开时，所有传输停止后调用，可能会在中断中调用，不可睡眠
	void (*disconnect)(struct usb_gadget *);
	void (*suspend)(struct usb_gadget *);
	void (*resume)(struct usb_gadget *);
    // usb总线复位时调用，必须实现，在中断中调用
	void (*reset)(struct usb_gadget *);
	struct device_driver	driver;
};
struct usb_gadget_ops {  // usb设备控制器硬件操作函数，不涉及端点和io
	int	(*get_frame)(struct usb_gadget *);
	int	(*wakeup)(struct usb_gadget *);
	int	(*set_selfpowered) (struct usb_gadget *, int is_selfpowered);
	int	(*vbus_session) (struct usb_gadget *, int is_active);
	int	(*vbus_draw) (struct usb_gadget *, unsigned mA);
    // 下拉让usb主机感知到usb设备接入usb总线，usb主机会枚举usb设备
	int	(*pullup) (struct usb_gadget *, int is_on);  
	int	(*ioctl)(struct usb_gadget *, unsigned code, unsigned long param);
	void (*get_config_params)(struct usb_dcd_config_params *);
	int	(*udc_start)(struct usb_gadget *, struct usb_gadget_driver *); // 启动udc
	int	(*udc_stop)(struct usb_gadget *);  // 停止udc
    // 匹配usb端点
	struct usb_ep *(*match_ep)(struct usb_gadget *,
		struct usb_endpoint_descriptor *, struct usb_ss_ep_comp_descriptor *);
};