rk3568平台启用CONFIG_USB_CONFIGFS_F_PRINTER=y后无法识别为USB打印机设备？

Question

在RK3568平台启用`CONFIG_USB_CONFIGFS_F_PRINTER=y`后，主机PC（Windows/macOS/Linux）无法识别为USB打印机设备，常见原因包括：① USB Gadget未正确绑定到`printer`功能（如`ls /sys/kernel/config/usb_gadget/*/configs/*/printer/`缺失或未写入`idVendor`/`idProduct`）；② 缺少必要的复合配置（如未同时启用`CONFIG_USB_CONFIGFS_ACMS`或未配置`os_desc`兼容性）；③ 内核未启用`CONFIG_USB_CONFIGFS_SERIAL`等依赖项导致复合设备枚举失败；④ Rockchip UDC驱动（`rk_udc`）对CDC-ACM+Printer复合模式支持不完善，触发USB描述符校验错误；⑤ 用户空间未通过`configfs`正确挂载并设置`bcdDevice`、`bInterfaceClass=07`（Printer Class）及`bInterfaceSubClass=01`（Printer Subclass）。典型现象为设备管理器中显示“未知USB设备（设备描述符请求失败）”或`dmesg`报`ep0: failed to get descriptor`。需结合`lsusb -v`与`dmesg | grep -i usb`交叉验证描述符完整性。

Answer 1

```html

一、现象层诊断：从主机端异常反馈反推USB枚举失败根源

当Windows设备管理器显示“未知USB设备（设备描述符请求失败）”，macOS系统日志中出现USBDeviceOpen: device not configured，或Linux主机执行lsusb -v时卡在Couldn't open device, some information will be missing——这已明确指向USB设备描述符（Descriptor）未被正确响应。此时需立即在RK3568端运行：dmesg | grep -i "usb\|ep0\|configfs"，重点关注ep0: failed to get descriptor、configfs: cannot create 'printer'等错误。该层级不涉及驱动逻辑，仅确认主机是否“看见”设备及基础通信是否建立。

二、配置层验证：检查configfs挂载与printer功能节点完整性

执行以下命令链验证Gadget配置状态：

mount | grep configfs
ls /sys/kernel/config/usb_gadget/
ls /sys/kernel/config/usb_gadget/*/configs/*/printer/ 2>/dev/null || echo "⚠️ printer function node MISSING"
cat /sys/kernel/config/usb_gadget/*/idVendor 2>/dev/null
cat /sys/kernel/config/usb_gadget/*/idProduct 2>/dev/null

若printer/目录不存在，说明未执行mkdir printer；若idVendor为空，则未写入合法VID（如0x2207对应Rockchip），将导致Windows拒绝加载WinUSB驱动。此为90%初学者踩坑点。

三、内核编译层依赖分析：CONFIG_USB_CONFIGFS_F_PRINTER的隐式依赖树

启用CONFIG_USB_CONFIGFS_F_PRINTER=y并非孤立操作。其完整依赖关系如下表所示：

配置项	必要性	作用说明
CONFIG_USB_CONFIGFS	强制启用	configfs USB gadget框架基座
CONFIG_USB_CONFIGFS_SERIAL	复合模式必需	提供CDC ACM接口，Printer常需共存于同一配置（bConfigurationValue=1）
CONFIG_USB_CONFIGFS_ACM	推荐启用	避免Windows因缺少CDC类描述符而跳过整个配置

四、硬件抽象层瓶颈：rk_udc驱动对复合设备描述符的兼容性缺陷

RK3568的rk_udc驱动（drivers/usb/gadget/udc/rk_udc.c）在4.19+主线内核中仍存在两个关键限制：

• 不支持bInterfaceClass=0x07（Printer Class）与bInterfaceClass=0x02（CDC ACM）在同一configuration中动态切换接口启用状态；
• 对os_desc（Microsoft OS Descriptor）解析存在校验偏移错误，导致Windows 10/11拒绝加载WinUsb.sys。

解决方案：必须打补丁修复rk_udc_ep0_queue()中对GET_DESCRIPTOR请求的length字段截断逻辑，并显式启用CONFIG_USB_CONFIGFS_F_OS_DESC=y。

五、协议层合规性：USB Printer Class描述符的强制字段校验

根据USB Device Class Definition for Printing Devices v1.1，Printer功能必须满足：

• bInterfaceClass = 0x07（必须）
• bInterfaceSubClass = 0x01（Bidirectional mode，必须）
• bInterfaceProtocol = 0x02（IEEE 1284.4，推荐）
• bcdDevice ≥ 0x0100（否则Windows视为旧版非即插即用设备）

在configfs中设置示例：

echo 0x07 > /sys/kernel/config/usb_gadget/g1/configs/c.1/printer/bInterfaceClass
echo 0x01 > /sys/kernel/config/usb_gadget/g1/configs/c.1/printer/bInterfaceSubClass
echo 0x02 > /sys/kernel/config/usb_gadget/g1/configs/c.1/printer/bInterfaceProtocol
echo 0x0100 > /sys/kernel/config/usb_gadget/g1/bcdDevice

六、交叉验证工作流：dmesg + lsusb -v + usbmon三重定位法

构建可复现的问题诊断流程图：

graph TD
    A[dmesg | grep ep0] -->|ep0: setup 0x0600...| B{Descriptor Type?}
    B -->|0x01 Device| C[检查idVendor/idProduct]
    B -->|0x02 Config| D[检查configs/c.1/bmAttributes]
    B -->|0x04 Interface| E[检查printer/bInterfaceClass]
    C --> F[lsusb -v -s :1]
    D --> F
    E --> F
    F -->|Missing bInterfaceClass| G[回写configfs]
    F -->|bcdDevice=0x0000| H[强制设为0x0100]

七、生产环境加固方案：systemd服务化Gadget初始化

避免手动执行configfs命令出错，建议创建/etc/systemd/system/usb-printer-gadget.service：

[Unit]
Description=USB Printer Gadget
After=multi-user.target

[Service]
Type=oneshot
ExecStart=/bin/sh -c '
  mkdir -p /sys/kernel/config/usb_gadget/g1/configs/c.1/printer &&
  echo 0x2207 > /sys/kernel/config/usb_gadget/g1/idVendor &&
  echo 0x0001 > /sys/kernel/config/usb_gadget/g1/idProduct &&
  echo 0x07 > /sys/kernel/config/usb_gadget/g1/configs/c.1/printer/bInterfaceClass &&
  echo 0x01 > /sys/kernel/config/usb_gadget/g1/configs/c.1/printer/bInterfaceSubClass &&
  echo 0x0100 > /sys/kernel/config/usb_gadget/g1/bcdDevice &&
  echo g1 > /sys/kernel/config/usb_gadget/g1/UDC'

RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

启用服务：systemctl daemon-reload && systemctl enable --now usb-printer-gadget。

八、Windows专用适配：INF文件与WinUSB驱动绑定

即使Linux端描述符合规，Windows仍可能加载默认usbccgp.sys（Composite Parent Driver）而非预期驱动。需提供定制INF：

[Version]
Signature="$WINDOWS NT$"
Class=USB
ClassGuid={36fc9e60-c465-11cf-8056-444553540000}

[SourceDisksNames]
1 = %DiskName%,,,

[SourceDisksFiles]
usbprint.inf = 1,,

[Manufacturer]
%ManufacturerName% = Standard,NTarm64

[Standard.NTarm64]
%DeviceName% = USB_Install, USB\VID_2207&PID_0001

其中VID_2207&PID_0001须与RK3568 configfs中设置完全一致，否则设备管理器无法匹配。

九、终极调试技巧：使用usbmon捕获主机端控制传输原始字节

在Windows主机安装USBPcap，或Linux主机执行：

modprobe usbmon
tcpdump -i usbmon0 -w usb-printer.pcap
# 触发设备重插拔后分析pcap包中SET_CONFIGURATION与GET_DESCRIPTOR事务

重点观察Setup Data中bRequest=0x06（GET_DESCRIPTOR）时，wValue=0x0100（Device Descriptor）是否返回0x12字节有效数据，若返回0长度即证明rk_udc未完成描述符填充。

十、Rockchip官方补丁追踪：规避已知内核版本缺陷

截至2024年Q2，RK3568 SDK基于Linux 5.10.110，其rk_udc存在如下已知问题：

• Commit 8a3f2e1（RK3568 UDC: fix ep0 descriptor length for composite configs）——修复复合配置下GET_DESCRIPTOR响应长度错误；
• Commit c7d9b4a（usb: gadget: configfs: add os_desc support for printer function）——为printer节点注入os_desc属性；

强烈建议从Rockchip GitHub仓库同步最新rockchip-linux/linux分支，并启用CONFIG_USB_CONFIGFS_F_OS_DESC=y以获得Windows 11原生支持。

```