USB Report Descriptors, inconsistent/lacking documentation.
> Quoting from ther USB spec for HID Descriptors:
http://www.usb.org/developers/hidpage/HID1_11.pdf "the value bNumDescriptors
identifies the number of additional class specific descriptors present. This
number must be at least one (1) as a Report
> descriptor will always be present."
> The problem is, what does 'present' mean? It isn't in the config descriptor
which is where the HID descriptor is, so in the complete absence of
documentation in the MDSN for this descriptor type, I had a dig around in some
Linux code for a host and discovered the report descriptor is obtained not from
the device, like the other descriptors, but from an interface.
Right, it is a separate descriptor type, fetched with a separate
GET_DESCRIPTOR request, just like the string descriptors. Section 7.1.1
talks about that.
> Microsoft include a define for this,
URB_FUNCTION_GET_DESCRIPTOR_FROM_INTERFACE, but not a macro
(UsbBuildGetDescriptorRequest being the macro to get a descriptor from a
> What is also odd is that the report descriptor doesnt follow the format of the
other descriptors in having a USB_COMMON_DESCRIPTOR type header at its start.
(In fact it is just an array of chars).
Right. Again, the very spec you cited has those exact words:
6.2.2. Report Descriptor
The Report descriptor is unlike other descriptors in that it is not
simply a table of values.
> What is also inconsistent is that when using this define you don't need to
specify an interface index like you do when using URB_FUNCTION_VENDOR_INTERFACE.
The request on the wire requires an interface number in wIndex, but in
this case the USB driver stack is filling that in for you. It knows
what interface number your driver was assigned, and a HID driver is
always assigned one interface. In the case of
URB_FUNCTION_VENDOR_INTERFACE, it's possible for that request to be
called when you have multiple interfaces (like USB Audio or USB Video),
so it can't automatically fill in the correct. value.
> So why the oversight? Why the missing macro and why is the descriptor
structure different from the others, including the HID descriptor? And why no
The macro is trivial to write. The general "get descriptor" macros are
useful for ALL USB devices. The "get report descriptor" macro is only
applicable to one class of devices (HID).
The descriptor structure is different because there's no reason not to
be. That's just the way the HID interface was designed 20 years ago.
You don't need to specify the interface because the USB stack already
knows what interface you are handling. It will fill in the wIndex value
on your behalf.
> Not a big problem, provided you know where to look in linux to see how a USB
host works, but it would be nice to have better consistency and documentaion in
If you want to know how USB devices work, you look in the USB
specifications. That's where the rubber meets the road. There's really
no need for Microsoft to duplicate the thorough and quite readable USB
Tim Roberts, firstname.lastname@example.org
Providenza & Boekelheide, Inc.