当前位置： 首页 > article >正文

USB 驱动开发 --- Gadget 驱动框架梳理(一)

article 2025/1/15 20:19:44

本文由 Linux 内核文档翻译与总结而来，个人学习笔记仅供参考。

Gadget 框架

在 USB 协议交互过程中，角色定义：

  • the device driver is the master (or “client driver”)

    Linux 内核中称为 HCD(Host Controller Driver)，负责与 USB 主机控制器硬件（通常是计算机的 USB 控制器）进行交互，管理 USB 数据传输。

  • the gadget driver is the slave (or “function driver”)

    Linux 内核中称为 UDC(USB Device Controller)，管理连接到 USB 设备端的硬件，处理设备端的数据传输、设备枚举和其他 USB 设备相关的操作。

在这里插入图片描述

USB Controller Driver(UDC 驱动)

  • <linux/usb/gadget.h> 定义的API中，对底层 USB 控制器端点硬件抽象成 endpoint (能够接收 IN/OUT 数据流)，通过回调与 Gadget Driver 交互。
  • Controller Driver 采用分时复用的方式进而可以对接任意数量的 Gadget Driver 交互；

Gadget Driver

对 USB Controller 的硬件抽象以支持 USB Function 开发，形式为各种调用接口。Gadget Driver 工作职责如下：

  • 响应 setup 请求， 由 ep0 负责的相关协议的应答也包含 calss 类别相关功能实现；
  • 响应 configuration、String 描述符；
  • (重新)设定 Configuration 和 Interface， 包含对端点的 使能与配置；
  • 报告 活动事件，例如：绑定到硬件、挂起/恢复、远程唤醒、断连等；
  • 管理 所有端点的 IN/OUT 收发；

Linux 社区并不鼓励通过这个方式添加如此多的专有驱动。

Upper Level

在 Gadget driver 之上可以连接到 Linux 内核的其他驱动或框架，通过绑定的形式与 Dadget 驱动完成数据的收发。可参考：

  • 用户空间，使用 gadgetfs 或 /dev 下相应节点操作；
  • 网络子系统，如：CDC Ethernet Model gadget 驱动；
  • 其他：Input 子系统(HID gadgets)、Sound 子系统(Aduio gadget)、文件系统(PTP gadget)等；

Additional Layers

可选的层，如：内核网络模块栈、用户应用、标准 POSIX 系统调用等。

Gadget API

在这里插入图片描述

数据结构

gadget driver 使用struct usb_gadget_driver包含自身信息之外还包含另外三种数据类型。理解这些数据类型和使用方法就算是掌握了API。

  • usb_gadget_driver dadget信息；

    //----> linux_5.10/include/linux/usb/gadget.h

struct usb_gadget_driver {
    ...
	int			(*setup)(struct usb_gadget *, const struct usb_ctrlrequest *);

  • usb_gadget，枚举信息；

    struct usb_gadget {
    ...
	struct usb_udc			*udc;

  • usb_ep，端点配置；

    struct usb_ep {
    ...
	const struct usb_ep_ops	*ops;     
	...
	struct usb_ep_caps	caps;        
	...
	u8			address;
	const struct usb_endpoint_descriptor	*desc;

  • usb_request，数据收发；

    struct usb_request {
	void			*buf;
	unsigned		length;

  • linux/usb/ch9.h，Gadget 驱动使用的在USB ch9 中定义的公共的 USB 数据结构，不分 Host 与 Device。

使用中关注：

  • 规定使用端点0作为作为各种硬件限定信息的配置与管理，如：发送类型、地址、包大小、缓存和其他能力集；
  • USB message 臃肿(chunky)，一个IO请求需要由一个或多个”数据包“组成且边界可被驱动感知；
  • USB 协议更像是异步通信协议(如：HDLC，每帧有 N 个 Byte，多个地址，Host 第一站，Device 其次)超过异步通信协议(如：TTY，每帧8个 Bit，无奇偶检验位，无停止位)；
  • USB 数据包是有边界的，如： 一个 USB IN 包数据是 two-byte 一个单元，因此不能将两个单字节直接写入一个单元；

对象与方法

Gadget 设备
核心
  • <linux/usb/gadget.h>， 定义了 Gadget 驱动核心对象与方法；
可选

核心 API 已足够支撑 Gadget 驱动开发，但还另外提供了一些可选工具用以简化常用任务。

  • drivers/usb/gadget/usbstring.c；
  • drivers/usb/gadget/config.c；
composite 设备

核心 API 已足够开发 Composite 设备(一个 configuration 中有多个功能)和 多功能设备驱动的开发，composite 复合框架将简化这些设备驱动的开发。

框架

composite 设备框架定义了一个设备结构体 struct usb_composite_driver ，其内可关联多个struct usb_configuration 实例。每个 configuration 又包含多个 struct usb_function 定义。在 function 中定义了用户可感知的设备角色，如：Network Link、mass storage device，也可包含管理功能，如：Device Firmware Upgrade。

  • include/linux/usb/composite.h，数据结构定义；
  • drivers/usb/gadget/composite.c，框架实现；
功能

当前只要是使用 DECLARE_USB_FUNCTION_INIT声明的 Gadget 驱动就都是 composite设备，可对应查看源码 drivers/usb/gadget/function/f_xxx.c。

Legacy 设备

源码目录 drivers/usb/gadget/legacy/xxx.c。

活动事件

Gadget 驱动执行I/O请求时时不用关注硬件细节要求，而当驱动执行 setup/configuration 时就需要关注流程：

  1. 注册 UDC 驱动(USB Device Controller，作为**设备(Slave)**角色的 USB 控制器驱动)；

    当前作为设备插入 Host 后会处于 attached 初始化状态( USB ch9 中定义)。此时既无功率消耗也法被使用(还不支持枚举)。

    因为当前数据线上的上拉未使能，所以即使 VBus 正常供电，Host 也无法感知到当前设备的存在(Host 通过设备是否上拉数据线探测设备)。

  2. 注册 Gadget 驱动；

    这些更高层级的 Fuction 驱动将调用 bind() 绑定到具体的 gadget 设备( struct usb_gadget 对象) 。有时这些 Function会在识别到 VBUS 后使能数据线上拉。

  3. 硬件驱动开始枚举；

    此时设备可以接受 USB power 和 set_address 请求，余下步骤由 gadget driver 接管。如果 dadget driver 在枚举前还未加载，忽略其后步骤直接跳转至步骤 7，执行 unbind()。

  4. 实现 Gadget 驱动中 setup()方法；

    setup()方法将返回当前设备的：描述符、硬件接口和能力集等信息。如果硬件允许，甚至可以执行更复杂的设定和配置。

  5. 实现 set_configuration 请求的应答；

    Gadget 驱动需要在setup()方法中实现对主机set_configuration请求的应答(枚举的最后一步)，使用所有在 Configuration 中使用的端点 和 默认 settings 中的接口；

  6. 实现数据收发；

  7. 实现 Gadget 驱动中 unbind()方法；

    当 Gadget 驱动卸载时，同时卸载 UDC 驱动；

注：

  1. 在设备连接到Hub后会导致Hub的D+或D-电平变化，Hub根据变化的引脚分辨接进来的是全速设备还是低速设备：

    • 低速设备内部的D-有1.5K的上拉电阻；

    • 全速设备内部的D+有1.5K的上拉电阻；

    • 高速设备一开始也是作为全速设备被识别的，高速模式时，D+的上拉电阻是断开的；

UDC 驱动

UDC(USB Device Controller)，即USB从机(设备)控制器，内核文档也称为 Peripheral Controller Drivers。内核中第一个支持的硬件的是 NetChip 2280 控制器(基于PCI 的支持 USB 2.0 调整模式)。其他的控制器基于 gadget 框架开发，见驱动源码文件： linux_5.10/drivers/usb/gadget/udc/xxx_udc.c。

虚拟UDC

方便硬件控制器未准备好(缺失或功能异常)时的软件调试，内核实例了一个虚拟的 UDC 驱动。它像 net2280、pxa25x 和 sa11x0 等硬件控制器一样指代多个端点和速率模式，也能够模拟 控制传输、批量传输 和 中断传输。这也就方便了开发支持在

Gadget 驱动

除 gadget_Zero驱动(主要用于UDC功能验证)之外，内核还有示例了多个常用的 gadget 驱动。

CDC 类

CDC(Communications Device Class)是太网模型的两个强制选项之一，也是电缆调制解调器交互操作性的标准之一。在USB主机看来，使用此代码的gadget 就像是以个太网适配器。

CDC类实现源码文件位于：drivers/usb/gadget/function/f_xxx.c，其下包含：

  • USB CDC serial 类： ACM；
  • USB CDC Ethernet 类：ECM、EEM、RNDIS，简单辨析如下：
    请添加图片描述

注：暂且把 微软的 RNDIS 驱动也纳入CDC Ethernet 类，因为 RNDIS 更适合运行在轻量化的 USB 控制器设备中。RNDIS 为设备接入 Windows 系统使用提供了便捷。

MSC 类

MSC(Mass Storage class)指常用的存储设备，如：U盘、CD-ROM等。大容量存储类设备驱动使用一种不同于 MS-Windows 和 MacOS 的交互方式：

  • USB 设备端，驱动使用一个具体的文件或块设备作为其后端存储介质；
  • USB 主机端，主机遵循 BBB, CB 或 CBI 版本的 MSC 类规格要求使用 SCSI 命令访问后端不认介质；

MSC 类实现源码文件包含：

  • drivers/usb/gadget/function/f_mass_storage.c，被主机视为 磁盘、CD-ROM 等存储设备访问；
  • drivers/usb/gadget/function/f_loopback.c，主要用于应用回环测试；

OTG 功能

USB OTG(USB On-The-GO)指代可以进制双角色切换机制的 USB 控制器：

  • 作为 Host时，使用标准 Linux-USB 主机侧驱动栈；
  • 作为 Device时，使用 Gadget 框架；

见下图，可以看到：Host Controllere、 Device Controller、OTG Bus Monitor 三个重要组成
请添加图片描述

在不同角色下，系统都应尽量复用顶层已申请的、硬件无关的顶层控制器驱动(Host， usb_bus；Device， usb_gadget)内存池；保证功能正常的最小修改；保证对非 OTG 产品的影响。可以抽象出以下几个控制特性：

  • is_otg，Gadget 驱动检查这个标记以确认是否需要在其 configurations 中添加 OTG 描述符；
  • b_hnp_enable， Gadget 驱动如果需要支持两种新的 OTG 协议：
    • HNP， 通过用户接口(如：两个 LED 灯)指示当前设备被 Host 挂起；
    • SRP， 可由用户发起(就像远程唤醒)，如按下相关按键；
  • 白名单，如同主机侧，驱动必须支持 OTG 目标外设名单，用以声明支持的 OTG 控制器，即 OTG 白名单。修改文件 otg_whitelist.h。

需知

  1. 每个 USB Function 都会在 config_groups 中定义期望用户配置的内容，可配置参考对应 Function 的实现文件：drivers/usb/gadget/f_*.c
  2. 主要阅读 USB 规范章节9 和 内核 gadget.rst 文档，以免忽略掉关键信息，如：端点自动配置，否则需要同时参考头文件与示例源码(如 Gadget Zere)；

参考

  • 内核文档 linux_5.10/Documentation/usb/gadget_configfs.rst
  • 11_Gadget驱动程序框架

http://www.kler.cn/a/504046.html

相关文章：

  • rtthread学习笔记系列(4/5/6/7/15/16)
  • Linux(Centos7)安装Mysql/Redis/MinIO
  • 认识机器学习中的经验风险最小化准则
  • vue3+vite+ts集成第三方js
  • 【华为OD-E卷 - IPv4地址转换成整数 100分（python、java、c++、js、c）】
  • 前端练习题
  • 如何开放2375和2376端口供Docker daemon监听
  • 强化学习代码实践1.DDQN:在CartPole游戏中实现 Double DQN
  • Linux第二课：LinuxC高级 学习记录day03
  • PHP Filesystem：深入解析与实战应用
  • 【机器学习】聚类评价指标之福尔克斯–马洛斯指数（Fowlkes–Mallows Index, FMI）
  • 说一说mongodb组合索引的匹配规则
  • 从github上，下载的android项目，从0-1进行编译运行-踩坑精力，如何进行部署
  • 65.在 Vue 3 中使用 OpenLayers 绘制带有箭头的线条
  • 伏羲1.0试用版（文生图）
  • 【软件工程】知识点总结（下）
  • 基于python的舆情监测管理系统
  • phpstorm jetbrain 配置review code
  • React 中事件机制详细介绍：概念与执行流程如何更好的理解
  • 软件测试 —— 自动化测试（Selenium）
  • element-ui dialog弹窗 设置点击空白处不关闭
  • 【Redis】初识Redis
  • 机器学习赋能的智能光子学器件系统研究与应用
  • Spring Boot 项目启动后自动加载系统配置的多种实现方式
  • 202305 青少年软件编程等级考试C/C++ 二级真题答案及解析（电子学会）
  • 本地服务器Docker搭建个人云音乐平台Splayer并实现远程访问告别烦人广告