usb hid descriptor requirements are rejecting hardware (ZWO EFWmini, 03c3:1f01)

[Salvatore Bonaccorso <carnil@debian.org>]

Hi Sam,

Jiri, Benjamin, this is about a report originally done in Debian as
https://bugs.debian.org/1122193 where Sam's device, a ZWO EFWmini with
vendor and product id's as 03c3:1f01 is not working, usbhid not
loaded.

On Mon, Dec 08, 2025 at 03:03:49PM +0000, Sam Halliday wrote:
> Package: linux-image-amd64
> Version: 6.12.57-1
> Severity: normal
> Tags: patch
> X-Debbugs-Cc: debian-amd64@lists.debian.org
> User: debian-amd64@lists.debian.org
> Usertags: amd64
> 
> Dear Maintainer,
> 
> I propose a patch to workaround USB HID descriptor requirements that
> are stopping users from being able to use astrophotography
> equipment.
> 
> I have a usb device (an ZWO EFWmini, used for astronomy) which has
> the following vendor information: 03c3:1f01 ZWO ZWO EFW
> 
> This device is known to offer a suboptimal descriptor, e.g. see the lsusb output
> 
>       Warning: Descriptor too short
>         HID Device Descriptor:
>           bLength                 9
>           bDescriptorType        33
>           bcdHID               1.01
>           bCountryCode            0 Not supported
>           bNumDescriptors         2
>           bDescriptorType        34 (null)
>           wDescriptorLength      68
>           bDescriptorType         0 (null)
>           wDescriptorLength       0
>           Report Descriptors: 
>             ** UNAVAILABLE **
> 
> My software (I write it, it is GPLv3, I'm the only user, but it isn't particularly relevant...) runs primarilly on a raspberry pi, which accepts this with kernel 6.12.25-1+rpt1, and I've also done some desktop development on archlinux (unknown kernel versions but up to at least 6 months ago). I only access the hardware for development from a debian desktop computer.
> 
> Since moving to Debian 13, my hardware no longer works, with dmesg showing the following error:
> 
> [   14.182522] usb 1-2.2: new full-speed USB device number 10 using xhci_hcd
> [   14.276921] usb 1-2.2: New USB device found, idVendor=03c3, idProduct=1f01, bcdDevice= 0.00
> [   14.276930] usb 1-2.2: New USB device strings: Mfr=1, Product=2, SerialNumber=0
> [   14.276933] usb 1-2.2: Product: ZWO EFW
> [   14.276935] usb 1-2.2: Manufacturer: ZW0
> [   14.282951] usbhid 1-2.2:1.0: can't add hid device: -22
> [   14.282963] usbhid 1-2.2:1.0: probe with driver usbhid failed with error -22
> 
> I have tried going back as far as debian's kernel from bullseye (5.10), bookworm (6.1), trixie (6.12) and backports (6.17) but it's the same error every time.
> 
> Communicating with the ZWO (the device manufacturer) support team, they recommended patching the kernel, which I did, and it now works.
> 
> I applied the following patch and built my own kernel
> 
> ===========================================================================
> --- drivers/hid/usbhid/hid-core.c.orig	2025-12-08 13:15:08.657917762 +0000
> +++ drivers/hid/usbhid/hid-core.c	2025-12-08 13:16:24.293959487 +0000
> @@ -1015,7 +1015,7 @@
>  			      (hdesc->bNumDescriptors - 1) * sizeof(*hcdesc)) {
>  		dbg_hid("hid descriptor invalid, bLen=%hhu bNum=%hhu\n",
>  			hdesc->bLength, hdesc->bNumDescriptors);
> -		return -EINVAL;
> +		// return -EINVAL;
>  	}
>  
>  	hid->version = le16_to_cpu(hdesc->bcdHID);
> ===========================================================================
> 
> The new dmesg output is
> 
> [  366.477628] usbhid 1-2:1.0: 1 unsupported optional hid class descriptors
> [  366.478327] hid-generic 0003:03C3:1F01.0006: hiddev1,hidraw4: USB HID v1.01 Device [ZW0 ZWO EFW] on usb-000
> 
> 
> Apologies but I don't think I'm giving you a particularly good patch
> because the author of this code clearly intended for a -EINVAL
> failure. A kernel dev may prefer to create a hardware quirk (which
> ideally should be enabled for 03c3:1f01 by default) to exit if the
> descriptor isn't valid. I'm not a kernel developer so that's beyond
> me.
> 
> The device works perfectly fine despite the descriptor not meeting
> the kernel's current requirements. And I don't believe a firmware
> upgrade is possible... it's just a little motor that turns a wheel
> containing photographic filters.

I suspect your case can be a candidate for HID-BPF, cf.
https://docs.kernel.org/hid/hid-bpf.html and you might try to fixup
the required descriptors.

But I'm not entirely sure. Jiri and Benjamin is that something we
could have quirk for the device or the problem tackled in some other
way?

Regards,
Salvatore