g_webcam UVC gadget causes USB\DEVICE_DESCRIPTOR_FAILURE on Windows 11

g_webcam UVC gadget causes USB\DEVICE_DESCRIPTOR_FAILURE on Windows 11

[Josh Cabarrus]

Bug Report: g_webcam UVC gadget incompatible with Windows 11 USB
descriptor validation

To: linux-usb@vger.kernel.org
CC: laurent.pinchart@ideasonboard.com, balbi@kernel.org
Subject: g_webcam UVC gadget causes USB\DEVICE_DESCRIPTOR_FAILURE on Windows 11

Summary

The g_webcam UVC gadget driver fails to enumerate properly on Windows
11, returning USB\DEVICE_DESCRIPTOR_FAILURE in Device Manager, while
other USB gadgets (g_serial, g_mass_storage) work correctly on the
same hardware and Windows version. This represents a regression in
Windows compatibility.

System Information

Hardware: Raspberry Pi Zero W Rev 1.1 (BCM2835, Revision: 9000c1)
Kernel: Linux 6.12.25+rpt-rpi-v6 #1 Raspbian (armv6l)
USB Controller: dwc2 20980000.usb
Host OS: Windows 11 (up to date)

Problem Description

When g_webcam is loaded and the Pi Zero W is connected to Windows 11 via USB:

g_webcam behavior:

Loads successfully on Pi: g_webcam ready, bound driver g_webcam
UDC state remains: not attached (never reaches configured)
Windows shows: Unknown USB Device (Device Descriptor Request Failed)
Hardware ID: USB\DEVICE_DESCRIPTOR_FAILURE

g_serial behavior (control test):

Loads successfully: g_serial ready, bound driver g_serial
UDC state becomes: configured
Windows properly recognizes as COM port device

Steps to Reproduce

bash

# On Raspberry Pi Zero W:
sudo modprobe g_webcam
cat /sys/class/udc/20980000.usb/state  # Shows: not attached

# Connect USB cable to Windows 11
# Result: "Unknown USB Device" in Device Manager

# Control test:
sudo rmmod g_webcam
sudo modprobe g_serial
cat /sys/class/udc/20980000.usb/state  # Shows: configured
# Result: Working COM port in Windows

Expected vs Actual Behavior

Expected: g_webcam should enumerate successfully on Windows 11 like
other gadgets and previous Windows versions.

Actual: Windows 11 rejects the USB device descriptors with
DEVICE_DESCRIPTOR_FAILURE.

Analysis

The issue appears to be Windows 11's stricter USB descriptor
validation. The g_webcam UVC descriptors may not fully comply with:

USB Video Class specification requirements
Windows 11's enhanced USB security validation
Microsoft's USB descriptor formatting standards

Loaded Modules

g_webcam               16384  0
usb_f_uvc              77824  5
uvc                    12288  1 usb_f_uvc
libcomposite           69632  17 usb_f_acm,usb_f_uvc,g_webcam
dwc2                  176128  0

Kernel Messages

g_webcam gadget.0: uvc: uvc_function_bind()
g_webcam gadget.0: Webcam Video Gadget
g_webcam gadget.0: g_webcam ready
dwc2 20980000.usb: bound driver g_webcam

Impact

This affects numerous Raspberry Pi Zero W webcam projects and
tutorials that previously worked with Windows. Users report this issue
across multiple Pi Zero W webcam implementations.

Suggested Investigation Areas

USB Descriptor Compliance: Review g_webcam's USB descriptors against
latest USB Video Class specification
Windows 11 Requirements: Compare descriptor format with Windows 11's
validation requirements
VID/PID Issues: Verify Vendor/Product ID configuration doesn't trigger
Windows driver conflicts
UVC Version Compatibility: Check if UVC version advertised matches
capabilities provided

Request

Could the maintainers investigate updating g_webcam's USB descriptors
to meet Windows 11's stricter validation requirements? The fact that
g_serial works but g_webcam fails suggests this is a
descriptor-specific issue rather than hardware or driver framework
problem.

Additional Information Available

I can provide:

USB protocol analyzer captures
Testing with different Windows versions
Comparison with working UVC implementations
Further diagnostic information as needed

Thank you for maintaining the USB gadget subsystem.

Reporter: Josh Cabarrus joshcabarrus@gmail.com
Date: May 27, 2025

P.S.  I used anthropic's claude.ai running Claude Sonnet 4 to
troubleshoot this issue.  I can upload the full conversation with all
troubleshooting steps if needed.

Re: g_webcam UVC gadget causes USB\DEVICE_DESCRIPTOR_FAILURE on Windows 11

[Greg KH]

On Tue, May 27, 2025 at 08:48:20PM -0600, Josh Cabarrus wrote:
> Bug Report: g_webcam UVC gadget incompatible with Windows 11 USB
> descriptor validation

Has this ever worked in the past?  If so, what kernel versions did work,
and can you use git bisect to track down the offending commits?

If it has never worked, any patches to change the code to make it work
would be appreciated.

> Could the maintainers investigate updating g_webcam's USB descriptors
> to meet Windows 11's stricter validation requirements? The fact that
> g_serial works but g_webcam fails suggests this is a
> descriptor-specific issue rather than hardware or driver framework
> problem.

g_serial is trivial compared to g_webcam, so this is not really a fair
comparison.  What changed in windows 11 descriptor requirements?  Do you
have a pointer to the relevant documentation for where it is explained
what has changed?

And what exact descriptors are failing here?

> I can provide:
> 
> USB protocol analyzer captures
> Testing with different Windows versions

Did windows 10 work?

> Comparison with working UVC implementations

Great, that might be the simplest, what descriptors work, and what do
not?

thanks,

greg k-h