从USB设备枚举到描述符交互：深入Linux Gadget框架通信机制

1. 项目概述：从描述符入手，拆解USB Gadget框架的通信本质

搞嵌入式开发，尤其是涉及到USB设备功能，你肯定绕不开Gadget框架。很多朋友学USB，一上来就被各种描述符、端点、传输模式搞得头大，看内核源码更是像看天书，一堆结构体套来套去，根本不知道从哪跟线头开始理。今天，我们不谈空洞的理论，就从最实在的“描述符获取”这个动作切入，把Gadget框架里，主机（Host）和设备（Device）之间到底怎么“对话”的，给彻底扒清楚。你会发现，所谓的复杂框架，核心就是一套“提问-回答”的机制。我们以最常见的USB设备枚举过程为线索，结合IMX6ULL和STM32MP157两款主流芯片的具体驱动源码，看看Linux内核是如何响应主机的每一次“提问”，并准备好正确的“答案”（描述符）的。无论你是正在调试一个USB网卡（RNDIS）、一个USB串口（CDC ACM）还是一个大容量存储设备（Mass Storage），理解了这个过程，就相当于握住了调试的钥匙。

2. USB设备枚举与描述符交互的全景解析

2.1 描述符：USB设备的“身份证”与“能力说明书”

在深入代码之前，我们必须达成一个共识：USB通信始于描述符。你可以把描述符理解为USB设备插上主机后，第一时间递出去的“名片”和“产品说明书”。

• 设备描述符 (Device Descriptor)：这是最顶层的“身份证”。它告诉主机：“我是一个什么样的设备？”（厂商ID、产品ID、设备类等），以及“我最大的包长度是多少？”（bMaxPacketSize0，这是关键！）。
• 配置描述符 (Configuration Descriptor)：描述设备的一种工作模式。一个设备可以有多个配置（比如一个摄像头可以有高清配置和低功耗配置），但一次只能激活一个。它包含了功耗、接口数量等信息。
• 接口描述符 (Interface Descriptor)：描述一个逻辑功能。比如一个复合设备（Composite Device），可能包含一个音频接口和一个HID（键盘）接口。接口才是功能承载的主体。
• 端点描述符 (Endpoint Descriptor)：描述通信的“管道”。除了默认的控制端点0，其他数据端点（如Bulk-IN/OUT, Interrupt-IN）都在这里定义其类型、方向、地址和最大包大小。

当你执行modprobe g_zero加载一个Gadget驱动时，驱动代码所做的最核心工作，就是在内存中构造好这一整套描述符信息。注意，是“构造”，而不是“发送”。此时，设备是“静默”的，它只是准备好了所有可能的应答材料，等待主机的询问。

2.2 枚举流程拆解：一次标准的主机“面试”

当用一根OTG线将开发板（作为设备）连接到电脑（作为主机）时，一场标准化的“面试”就开始了。这个过程是USB协议规定的，任何USB设备都必须遵循。我们结合输入材料里的步骤，详细拆解：

1. 首次握手与能力试探：主机首先发起一个控制传输（到默认地址0，端点0），请求读取设备描述符的前8个字节。为什么是8字节？因为第8个字节正是bMaxPacketSize0，它定义了控制端点0一次能处理的最大数据量。主机必须首先知道这个值，才能规划后续所有控制传输的包大小，避免发送超长的数据包导致设备无法处理。这是一个非常精妙的设计，体现了协议的自举和协商能力。

2. 分配“门牌号”：主机在了解设备基础能力后，会通过一个SET_ADDRESS请求，为设备分配一个唯一的设备地址（1-127）。从此，设备就使用这个新地址进行所有后续通信，地址0则留给新接入的设备。这个操作通常在底层UDC（USB Device Controller）驱动中直接处理，无需上层Gadget驱动干预。

3. 获取完整“身份证”：主机使用新分配的地址，再次请求读取完整的18字节设备描述符。这次，主机就拿到了设备的全部身份信息。

4. 索取详细“说明书”：接下来，主机通常会请求配置描述符。这里有个关键细节：主机往往会请求一个很大的长度（比如255字节）。这并非它真的需要255字节，而是一种“贪婪读取”策略。因为配置描述符、接口描述符、端点描述符以及可能有的类特定描述符，在内存中是连续存放的。主机通过一次请求，试图把当前配置下的所有描述符信息一股脑全部读回来，效率最高。

5. 获取可读信息：最后，主机可能会请求字符串描述符，比如厂商名称、产品名称、序列号等，这些是给人看的文本信息。

关键理解：在整个枚举过程中，设备端（我们的Gadget驱动）始终处于一种“被动响应”的状态。它不会主动向主机发送任何描述符。所有的数据返回，都是因为主机先发来了一个明确的GET_DESCRIPTOR请求（Setup Packet），设备才根据请求的类型和索引，从自己准备好的描述符集合中，找到对应的数据，通过端点0回传出去。不同的Gadget设备（如g_zero, g_ether, g_mass_storage），在枚举阶段的差异，几乎完全体现在它们所准备的描述符数据内容不同上，而响应请求的流程框架是一模一样的。

3. 中断处理：Gadget框架响应的起点

3.1 中断：一切主机请求的敲门声

那么，Linux内核是如何知道主机发来了请求呢？答案就是中断。USB控制器（UDC）在收到主机发来的令牌包和数据包后，会触发一个硬件中断。CPU跳转到相应的中断服务程序（ISR），这就是我们分析源码的逻辑起点。

根据输入材料，对于两款不同的芯片：

• IMX6ULL (Chipidea控制器)：中断处理函数是ci_irq(drivers/usb/chipidea/core.c)。
• STM32MP157 (DWC2控制器)：中断处理函数是dwc2_hsotg_irq(drivers/usb/dwc2/gadget.c)。

虽然入口函数不同，但它们的终极目标是一致的：解析USB控制器硬件寄存器，判断发生了什么事件，并调用相应的处理函数。对于我们关心的控制传输（端点0），最关键的事件就是“收到Setup包”。

3.2 IMX6ULL：Chipidea驱动的处理链

我们深入看一下IMX6ULL的路径，这有助于建立清晰的调用栈概念：

1. ci_irq被触发。
2. 它判断是设备控制器中断，然后调用ci->role->irq(ci)，对于设备模式，这个函数指针指向udc_irq(drivers/usb/chipidea/udc.c)。
3. udc_irq检查中断状态寄存器，如果发现USB中断（UI）标志，则调用isr_tr_complete_handler。
4. 在isr_tr_complete_handler中，会特别检查端点0的Setup状态位是否被置位。如果置位，说明收到了一个Setup事务，于是调用isr_setup_packet_handler。

至此，我们到达了处理控制传输Setup阶段的关键函数。这个函数的工作是：从USB控制器的接收FIFO中，读出主机发来的8字节Setup Packet数据，并解析它。

3.3 STM32MP157：DWC2驱动的处理链

DWC2驱动的流程在概念上相似，但具体实现有所不同：

1. dwc2_hsotg_irq被触发。
2. 它遍历所有端点，检查各端点的中断标志。对于端点0，会调用dwc2_hsotg_epint。
3. 在dwc2_hsotg_epint中，如果判断是端点0且当前没有正在处理的请求（!hs_ep->req），则调用dwc2_hsotg_enqueue_setup。
4. dwc2_hsotg_enqueue_setup这个名字很有趣，“入队一个Setup”。它的作用是初始化一个USB请求结构体（struct usb_request），并将其complete回调函数设置为dwc2_hsotg_complete_setup。然后启动这个请求，去接收Setup包之后可能跟随的Data数据包（对于控制写传输）。
5. 当Setup事务（或包含Data阶段的整个事务）完成时，硬件会再次触发中断，最终导致dwc2_hsotg_complete_setup被调用。这个函数才是DWC2驱动中解析Setup Packet的对应点。

操作心得：对比两者，IMX6ULL的Chipidea驱动在收到Setup包后立即在中断上下文进行解析（isr_setup_packet_handler），而STM32MP157的DWC2驱动则采用了一种“请求-完成”回调的机制，将Setup包的解析放到了完成函数（dwc2_hsotg_complete_setup）中。虽然时机略有差异，但它们的核心任务是一样的：解读主机的意图。

4. 控制传输请求的分发与处理三层模型

4.1 解析Setup Packet：读懂主机的“问题”

无论是isr_setup_packet_handler还是dwc2_hsotg_complete_setup，它们首先都要做同一件事：从USB控制器的缓冲区里取出那8字节的Setup Packet，并填充到一个struct usb_ctrlrequest结构体中。这个结构体定义如下（来自include/uapi/linux/usb/ch9.h）：

struct usb_ctrlrequest { __u8 bRequestType; __u8 bRequest; __u16 wValue; __u16 wIndex; __u16 wLength; } __attribute__ ((packed));

• bRequestType：指明了请求的方向（主机到设备，还是设备到主机）、类型（标准、类、厂商）和接收者（设备、接口、端点）。
• bRequest：这是请求码，是核心中的核心！它告诉设备主机想要干什么。比如USB_REQ_GET_DESCRIPTOR（获取描述符）、USB_REQ_SET_ADDRESS（设置地址）、USB_REQ_SET_CONFIGURATION（设置配置）等。
• wValue/wIndex/wLength：请求的参数。例如，对于GET_DESCRIPTOR请求，wValue的高字节表示描述符类型（设备、配置、字符串等），低字节表示索引；wLength表示主机期望返回的数据长度。

解析出这些信息后，驱动就需要决定：“这个请求该由谁来处理？”

4.2 处理层级划分：各司其职的响应体系

Gadget框架采用了一个清晰的三层处理模型，像一个处理流水线：

第一层：UDC驱动层（硬件相关）这一层是芯片厂商提供的控制器驱动，与硬件寄存器直接打交道。它处理那些最基础、与硬件状态强相关的标准请求。因为这些请求的处理通常需要直接操作控制器寄存器，放在底层效率最高。

• 典型请求：
  • USB_REQ_SET_ADDRESS：设置设备地址。驱动需要将新地址写入控制器的设备地址寄存器。
  • USB_REQ_SET_FEATURE/USB_REQ_CLEAR_FEATURE(针对设备或端点)：例如远程唤醒、端点Halt特性。需要操作对应的控制位。
  • USB_REQ_GET_STATUS(针对设备)：读取设备状态（如自供电、远程唤醒使能）。
• 处理位置：
  • IMX6ULL:isr_setup_packet_handler函数中的handle_standard_request分支。
  • STM32MP157:dwc2_hsotg_complete_setup函数中的类似分支。
• 处理原则：如果UDC驱动能处理，它就直接处理并返回成功或失败；如果不能处理（比如请求的目标是接口或不属于上述类型），它就返回一个特殊状态（如-EOPNOTSUPP），让请求继续向上传递。

第二层：Gadget驱动核心层（Composite层）这是Gadget框架的核心，文件通常是drivers/usb/gadget/composite.c中的composite_setup函数。绝大部分描述符和配置相关的标准请求都在这里处理。这一层是硬件无关的，它操作的是我们在软件中构建的struct usb_gadget,struct usb_configuration,struct usb_function等抽象数据结构。

• 典型请求：
  • USB_REQ_GET_DESCRIPTOR：这是我们的主角！函数会根据wValue中的描述符类型，从当前激活的配置、接口等结构中，找到对应的描述符数据，并通过usb_ep_queue()函数将数据排入端点0的发送队列，等待主机来读取。
  • USB_REQ_SET_CONFIGURATION：激活指定的配置。这会触发一系列回调，通知所有属于该配置的“功能”（Function）进入激活状态。
  • USB_REQ_GET_CONFIGURATION：返回当前激活的配置值。
  • USB_REQ_SET_INTERFACE/USB_REQ_GET_INTERFACE：选择或获取指定接口的备用设置（Alternate Setting）。
  • 一些UDC层未处理的GET_STATUS/CLEAR_FEATURE/SET_FEATURE请求（针对接口或端点）。
• 处理流程：composite_setup函数是一个大的switch-case语句，根据bRequest跳转到不同的处理分支。对于GET_DESCRIPTOR，它可能调用composite_get_descriptor等函数。

第三层：具体功能层（Function或Configuration层）这一层处理的是类特定（Class-Specific）请求或厂商自定义（Vendor-Specific）请求。这些请求不是USB标准定义的，而是由设备所属的类别（如HID、CDC、Mass Storage）或厂商自己定义的。

• 处理方式：在composite_setup函数中，如果前两层都无法处理某个请求，它会将这个请求向下传递给当前激活的usb_configuration，或者更进一步传递给该配置下所有的usb_function。每个usb_function驱动（如f_mass_storage.c,f_rndis.c）都有自己的setup回调函数来处理这些非标准请求。
• 举例：对于RNDIS（USB网络适配器）设备，Windows主机会发送一系列微软定义的RNDIS控制消息来初始化网络设备，这些消息就是通过控制传输发送的类特定请求，最终由f_rndis.c中的rndis_setup函数处理。

排查技巧：当你自定义一个USB设备，需要处理特殊的控制请求时，你通常需要在你自己实现的usb_function的setup回调函数中添加处理逻辑。如果请求没有正确响应，首先检查：1）你的setup回调是否被正确注册；2）composite_setup是否将未处理的请求传递了下来；3）你的请求类型（bRequestType）和请求码（bRequest）是否与主机发送的完全匹配。

5. 核心环节实现：以GET_DESCRIPTOR请求为例的代码追踪

让我们聚焦最关键的USB_REQ_GET_DESCRIPTOR请求，看看一个描述符是如何从内存中走到主机手里的。我们以Linux 5.x内核的Composite框架为例，路径非常典型。

5.1 请求抵达Composite层

假设一个GET_DESCRIPTOR请求成功通过UDC驱动层，来到了composite_setup函数（在drivers/usb/gadget/composite.c）。

static int composite_setup(struct usb_gadget *gadget, const struct usb_ctrlrequest *ctrl) { struct usb_composite_dev *cdev = get_gadget_data(gadget); u8_t b_request = ctrl->bRequest; switch (b_request) { case USB_REQ_GET_DESCRIPTOR: if (ctrl->bRequestType != USB_DIR_IN) goto unknown; switch (w_value >> 8) { // w_value的高字节是描述符类型 case USB_DT_DEVICE: cdev->req->complete = composite_setup_complete; value = get_device_descriptor(cdev, ctrl); break; case USB_DT_CONFIG: cdev->req->complete = composite_setup_complete; value = get_config_descriptor(cdev, ctrl); break; case USB_DT_STRING: value = get_string_descriptor(cdev, ctrl); break; // ... 其他描述符类型 default: goto unknown; } if (value >= 0) { // value 是描述符的长度 cdev->req->length = value; cdev->req->zero = value < w_length; // 如果返回的数据比请求的短，可能需要补零 value = usb_ep_queue(gadget->ep0, cdev->req, GFP_ATOMIC); if (value < 0) { DBG(cdev, "ep0 queue reply failed, err %d\n", value); cdev->req->complete = NULL; } } break; // ... 处理其他请求 unknown: // 传递给配置或功能层处理 if (cdev->config) { if (cdev->config->setup) value = cdev->config->setup(cdev->config, ctrl); // 如果配置层没处理，再传递给所有功能 if (value < 0) { struct usb_function *f; list_for_each_entry(f, &cdev->config->functions, list) { if (f->setup) { value = f->setup(f, ctrl); if (value >= 0) break; } } } } // 如果还是没处理，可能返回协议错误 if (value < 0) value = composite_ep0_queue(cdev, NULL, 0, NULL); // 返回STALL } return value; }

代码逻辑解读：

1. 判断请求方向：GET_DESCRIPTOR必须是主机读（USB_DIR_IN）方向。
2. 根据描述符类型分发：解析wValue的高字节，判断是请求设备、配置还是字符串描述符等。
3. 获取描述符数据：调用对应的函数（如get_config_descriptor）。这些函数会从cdev（composite设备）关联的usb_configuration和usb_function数据结构中，取出预先构造好的描述符字节数组。
   • 关键细节：描述符在内存中是以一个线性的字节数组（unsigned char *）形式存在的。例如，一个配置描述符及其下属的所有接口、端点描述符，在struct usb_configuration的descriptors指针里，就是连续存放的。这就是为什么主机可以一次读取255字节来获取全部信息。
4. 计算返回长度：返回的长度value是实际要发送的数据长度。它等于min(描述符总长度, 主机请求的w_length)。这是USB协议的要求，设备不能返回比主机请求更多的数据。
5. 排队发送：将包含描述符数据的请求（cdev->req）通过usb_ep_queue()函数，排入端点0（gadget->ep0）的传输队列。注意，usb_ep_queue只是把数据放入队列，并启动传输（如果硬件就绪）。真正的数据发送是由USB控制器硬件在主机发起IN令牌包时自动完成的。
6. 补零（ZLP）：cdev->req->zero标志很重要。如果描述符的实际长度小于主机请求的长度（w_length），并且实际长度是端点0最大包大小的整数倍，那么设备需要在发送完有效数据后，再发送一个长度为0的数据包（Zero Length Packet, ZLP），来告知主机数据发送结束。否则，主机会一直等待，直到超时。

5.2 描述符的构造源头

那么，get_config_descriptor函数拿到的数据是从哪里来的呢？这要追溯到Gadget驱动初始化的阶段。以g_zero驱动为例：

在drivers/usb/gadget/legacy/zero.c的zero_bind函数中，会调用usb_add_config()来添加配置。这个函数内部会调用配置的bind回调。对于g_zero，它可能使用source_sink_bind_config这样的函数。

在bind函数中，会做两件关键事：

1. 创建功能（Function）：实例化usb_function（如struct f_sourcesink）。
2. 构造描述符：调用usb_interface_id()为接口分配ID，然后调用usb_assign_descriptors()。这个函数会将几个关键的描述符函数（fs_descriptors,hs_descriptors,ss_descriptors等）赋值给usb_function结构体。

这些*_descriptors函数，返回的就是指向静态描述符字节数组的指针。例如，在drivers/usb/gadget/function/f_sourcesink.c中，你可以找到fs_source_sink_descriptors这个静态数组，里面就完整定义了该功能在全速模式下的所有描述符。

所以，完整的链条是：驱动初始化时构造描述符数组 -> 主机发起GET_DESCRIPTOR请求 ->composite_setup调用get_config_descriptor-> 从对应的usb_function中取出描述符数组指针 -> 计算长度并排队 -> USB控制器硬件在主机IN令牌包到来时发送数据。

6. 常见问题与深度排查技巧实录

理解了框架，调试时才能有的放矢。下面是我在开发和调试USB Gadget驱动时积累的一些典型问题场景和排查思路。

6.1 枚举失败：主机报告“无法识别的USB设备”

这是最常见的问题。根本原因是主机在枚举的某个阶段没有收到预期响应。

排查步骤（从底向上）：

1. 检查硬件连接与供电：确保OTG线完好，开发板供电充足。USB对电源噪声敏感，供电不足会导致枚举不稳定。
2. 确认驱动加载与UDC绑定：
   • lsmod | grep g_查看你的Gadget驱动（如g_zero,g_ether）是否加载。
   • ls /sys/class/udc/查看系统识别到的USB设备控制器。应该有一个，比如ci_hdrc.0或20980000.usb。
   • cat /sys/kernel/config/usb_gadget/<your_gadget>/UDC查看当前Gadget配置绑定了哪个UDC。如果为空，需要echo “ci_hdrc.0” > UDC进行绑定。绑定失败通常意味着驱动probe有问题或资源冲突。
3. 使用内核调试信息：
   • 确保内核编译时开启了CONFIG_USB_GADGET_DEBUG和CONFIG_USB_CHIPIDEA_DEBUG(或对应控制器的DEBUG选项)。
   • 使用dmesg -w或cat /proc/kmsg实时查看内核打印。关注是否有composite_setup相关的错误打印，或者UDC驱动的中断错误。
   • 关键信息：寻找类似“GET_DESCRIPTOR req 0x600, wValue 0x100, wIndex 0x0, wLength 0x40”的日志。这表示主机请求了设备描述符（wValue=0x100，类型1索引0）。如果看到这个请求，但后面没有成功的响应日志，问题可能出在数据发送阶段。
4. 逻辑分析仪抓包（终极武器）：如果软件层面无法定位，必须使用USB协议分析仪（如Saleae, Beagle）或支持USB抓包的逻辑分析仪。这是最直接的方法。
   • 抓取Setup Packet：确认主机发出的请求是否正确（bRequest,wValue等）。
   • 查看Data Stage：对于GET_DESCRIPTOR，主机在发送Setup包后，会发起一个IN令牌包。此时，逻辑分析仪上应该能看到设备返回的描述符数据。如果看不到数据，或者数据错误（如全是0xFF），说明设备端的数据队列或发送逻辑有问题。
   • 查看Status Stage：最后主机发送一个OUT令牌包（带0长度数据）表示状态阶段完成。如果缺少这一步，枚举也会失败。

6.2 描述符内容错误导致的功能异常

有时设备能识别，但功能不对（例如，被识别成了未知设备，而不是网络适配器）。

1. 核对描述符字节：仔细检查你的驱动中构造的描述符数组。一个字节的错误都可能导致主机解析失败。特别检查：
   • 描述符长度字段：每个描述符的第一个字节bLength必须准确。
   • 描述符类型字段：第二个字节bDescriptorType必须正确（如设备描述符是0x01）。
   • 类/子类/协议码：在接口描述符中，bInterfaceClass,bInterfaceSubClass,bInterfaceProtocol这三个字段决定了主机加载哪个驱动程序。必须与你期望的驱动严格匹配（可参考USB-IF的文档）。
   • 端点地址和方向：端点描述符中的bEndpointAddress的最高位表示方向（1=IN, 0=OUT），不要搞反。
2. 使用lsusb -v命令：在Linux主机上，使用lsusb -v可以详细列出已连接USB设备的所有描述符。将输出与你设备中定义的描述符逐字节对比，是发现差异的好方法。
3. Windows设备管理器错误码：在Windows上，如果设备有黄色感叹号，查看属性-详细信息-错误代码。常见的0xc0000001（驱动程序错误）或0xc00000e9（资源不足）可以指向不同的问题。

6.3 数据传输不稳定或速度慢

枚举成功，但进行大数据传输时出错或速度不达标。

1. 端点最大包大小：确认你的端点描述符中定义的wMaxPacketSize是否正确。对于高速（High-Speed）Bulk端点，最大值是512字节；对于全速（Full-Speed），是64字节。设置过小会严重影响吞吐量。
2. DMA与内存对齐：如果使用DMA，确保提供给USB控制器的数据缓冲区地址是DMA对齐的（通常是4字节或缓存行对齐）。非对齐访问可能导致数据损坏或传输失败。在申请DMA缓冲区时使用dma_alloc_coherent()或kmalloc()配合DMA_*标志。
3. 请求队列深度：USB传输是异步的。你需要持续向端点队列提交多个请求（struct usb_request），形成一个流水线，才能达到最高速度。如果每次只提交一个请求，等它完成再提交下一个，速度会大打折扣。参考f_mass_storage.c或f_rndis.c，看它们如何管理请求池（req_pool）。
4. 中断延迟与看门狗：确保你的USB中断服务程序（ISR）处理时间尽可能短。长时间关中断可能导致USB控制器FIFO溢出或主机超时。复杂的处理应该放到tasklet或工作队列（workqueue）中。

6.4 如何为自定义功能添加描述符

如果你想创建一个全新的USB功能，需要自己定义描述符。

1. 定义描述符数组：创建一个静态的unsigned char数组，按照USB规范顺序排列设备、配置、接口、端点等描述符。务必保证长度和类型字段正确。
2. 实现描述符回调函数：创建一个函数，返回指向上述数组的指针。通常需要为不同速度（全速、高速、超高速）定义不同的数组和函数。
3. 绑定到Function：在你的usb_function的bind回调中，调用usb_assign_descriptors()，将你的描述符回调函数传进去。
4. 处理类特定请求：如果你的功能需要响应非标准请求，实现usb_function的setup回调函数，并在其中处理你的自定义请求码。

调试自定义描述符时，先用一个已知好的驱动（如g_zero）做框架验证，确保基本的UDC和Composite层工作正常，然后再替换成你自己的描述符和功能逻辑，这样可以有效隔离问题。

理解Gadget框架的描述符交互机制，是掌握USB设备侧开发的关键一步。它不再是黑盒，而是一个清晰的分层响应模型。从硬件中断到UDC驱动，再到Composite核心层，最后到具体功能层，每一层都有明确的职责。下次当你再面对USB枚举失败的问题时，不妨沿着这条数据流，用逻辑分析仪和内核日志作为你的眼睛，一步步追踪，问题的根源总会水落石出。