arduino / arduino/ArduinoCore-avr

USB enumeration timeouts due to missing ZLPs

Open
#553 4 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
C
Stars
1.5k
Forks
1.1k
PR merge metrics
No merged PRs in 30d

Description

USBCore doesn't send required ZLPs for device-to-host transfers. This can cause timeouts during enumeration, among other problems.

Test case outline: create a HID interface with a report descriptor that's exactly 64 bytes long. Attach the device to Windows while monitoring the USB bus. Observe multiple control transfer timeouts and bus resets as Windows tries to get the device to enumerate correctly.

For whatever reason, Windows often (always?) requests 64 bytes more than were advertised for a HID report descriptor. This means that if the descriptor is an exact multiple of wMaxPacketSize, and the device sends fewer bytes than requested by the host, the device must send a ZLP to terminate the transfer. (see USB 2.0 §5.5.3) The missing ZLP causes Windows to time out.

It's also possible to replicate the timeout on other platforms (tested on macOS) by explicitly requesting a control read for more than 64 bytes to retrieve a descriptor that is exactly 64 bytes long.

I don't have a minimized test case yet, but the patch in keyboardio/Kaleidoscope-Bundle-Keyboardio#53 appears to resolve the problem for us.

It's a bit surprising that nobody has (knowingly?) encountered this before. It could also cause problems for configuration descriptor sets or string descriptors.

I can submit the patch as a PR against this repository directly, but I don't currently have a lot of time to create a minimized test case or to do exhaustive testing of the patch.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the USBCore transfer handling and comparing it with the patch referenced in keyboardio/Kaleidoscope-Bundle-Keyboardio#53. Reproduce the 64-byte HID report descriptor case, including an oversized control read on Windows or macOS. Done means transfers ending on an exact packet boundary send the required ZLP and enumeration completes without timeouts or bus resets.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
embedded-iot
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.