Kernel 4.9.118下FunctionFS组合FS/HS描述符报无效参数问题

问题背景 #

在运行Kernel 4.9.118的嵌入式设备上，采用ConfigFS模式的Linux FunctionFS开发USB 2.0 gadget，目标是实现支持Full-Speed（FS）和High-Speed（HS）的厂商自定义批量数据接口。编写FunctionFS所需的二进制描述符Blob后，遇到以下问题：

• 写入包含FS+HS组合描述符的Blob到/dev/usb-ffs/mygadget/descriptors时，持续返回「Invalid argument」错误；
• 启用gadget时出现configfs-gadget ... failed to start mygadget: -19（无此设备）的提示；
• 仅保留HS描述符（flags设为FUNCTIONFS_HAS_HS_DESC）时，写入成功且gadget可正常工作。

已验证内容：

• 十六进制转储显示二进制数据符合USB 2.0规范及FUNCTIONFS_DESCRIPTORS_MAGIC_V2头要求；
• 单独使用HS描述符功能正常；
• 内核版本为4.9.118。

可能的原因及排查方向 #

1. Kernel 4.9.x FunctionFS V2的FS/HS描述符校验Bug #

Kernel 4.9.x分支的FunctionFS V2实现存在已知兼容性问题：当同时设置FUNCTIONFS_HAS_FS_DESC和FUNCTIONFS_HAS_HS_DESC标志时，内核对FS描述符块的长度校验逻辑存在疏漏，即使Blob实际长度合规，也会被误判为非法。该问题在后续内核版本（如4.14+）中已被修复，但4.9.118未包含相关补丁。

2. FS与HS描述符的接口/端点一致性未满足 #

内核要求组合FS和HS描述符时，两者必须满足严格一致性：

• 接口数量完全相同；
• 每个接口对应的端点数量一致；
• 端点的方向（IN/OUT）、类型（批量/中断等）必须一一对应；
• 接口的bInterfaceNumber、bAlternateSetting字段值需完全匹配。
  即使单独看FS或HS描述符均合规，只要上述任意一项不匹配，内核就会返回EINVAL错误。

3. FS描述符的bMaxPacketSize违反USB规范 #

USB 2.0规范明确要求：

• Full-Speed模式下，批量端点的最大包长只能是64字节；
• High-Speed模式下为512字节。
  若FS描述符中bMaxPacketSize字段设置为512（与HS一致），内核会直接拒绝该Blob，触发「Invalid argument」错误。

4. FUNCTIONFS_V2头的flags字段位掩码错误 #

需确认FUNCTIONFS_HAS_FS_DESC和FUNCTIONFS_HAS_HS_DESC的位掩码定义是否正确。在Kernel 4.9的头文件中，这两个标志的定义通常为：

#define FUNCTIONFS_HAS_FS_DESC    (1 << 0)
#define FUNCTIONFS_HAS_HS_DESC    (1 << 1)

若误将两个标志设置为同一比特位（如均用1 << 0），内核无法正确识别同时存在FS和HS描述符，进而判定Blob非法。

5. 描述符Blob总长度与头字段不匹配 #

内核会严格校验Blob总长度是否等于struct functionfs_descriptors_v2结构体长度 + fs_desc_len + hs_desc_len。需确保：

• 头中的fs_desc_len字段准确对应FS描述符块的总字节数；
• hs_desc_len字段准确对应HS描述符块的总字节数；
• 实际写入的Blob总字节数与上述计算值完全一致（无多余或缺失字节）。
  Kernel 4.9对该校验的容错性较低，哪怕差1字节都会触发EINVAL。

内容的提问来源于stack exchange，提问作者Dongju Park