[libusb] Windows HID API Clarifications

[Xiaofan C. <xia...@gm...>]

Hi Tim,

I need your help here. Thanks.

On Tue, Jun 15, 2021 at 10:43 AM Xiaofan Chen <xia...@gm...> wrote:
>
> On Tue, Jun 15, 2021 at 2:29 AM Tim Roberts <ti...@pr...> wrote:
> > >  From Ihor Dutchak:
> > >> I believe we can parse hid descriptor (which we already doing for some other
> > >> purposes) and find out the largest report size, and use it as a length parameter
> > >> passed to libusb_fill_interrupt_transfer.
> >
> > Yes,  This, for example, is how the Windows HID subsystem operates.
>
> Thanks. I have other questions on the Windows HID APIs and I will ask
> in another email. It is pretty messy because of the report ID handling in
> hidapi and libusb Windows HID backend.

The following article is from the Windows Hardware Developer site.
************************
https://docs.microsoft.com/en-us/windows-hardware/drivers/hid/obtaining-hid-reports

This topic discusses the obtaining of HID input reports or HID feature reports,
by user-mode applications using ReadFile or the HidD_GetXxx routines.

However, an application should only use the HidD_GetXxx routines to obtain the
current state of a device. If an application attempts to use
HidD_GetInputReport to
continuously obtain input reports, the reports can be lost. In
addition, some devices
might not support HidD_GetInputReport, and will become unresponsive if this
routine is used.

...

Using IOCTL_HID_GET_Xxx Requests
A driver can use the following I/O requests to obtain the most current input and
feature reports from a HID collection:

IOCTL_HID_GET_INPUT_REPORT Returns an input report from a HID collection
(Windows XP and later versions).

IOCTL_HID_GET_FEATURE Returns a feature report from a HID collection.
**********************

So you can see that HIDAPI is using ReadFile for the fetching of HID reports
continuously with the hid_read API. And then it does not use
HidD_GetXxx routines
to obtain the most current input report and feature report, rather it
uses IOCTLs to
get the input report and feature report.

https://github.com/libusb/hidapi/blob/master/windows/hid.c#L56
#define IOCTL_HID_GET_FEATURE                         HID_OUT_CTL_CODE(100)
#define IOCTL_HID_GET_INPUT_REPORT              HID_OUT_CTL_CODE(104)

Historical reasons why Alan Ott chose to use DeviceIoControl() call and not
HidD_GetXxx.
https://github.com/libusb/hidapi/issues/229

So it seems to me that the Microsoft documentation may be a bit confusing to
say the driver can use the two IOCTLs. Usually driver means kernel space in
this context even though there are user mode drivers as well.

Now the question is the return data of the two IOCTLs (output buffer).
>From what I read, I believe
HIDAPI codes are wrong in both cases, as Microsoft documentation says
that the first byte of
the buffer is unchanged (report ID or 0 if no report ID).
https://github.com/libusb/hidapi/blob/master/windows/hid.c#L933
https://github.com/libusb/hidapi/blob/master/windows/hid.c#L884

*********** from Microsoft ***********
https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/hidclass/ni-hidclass-ioctl_hid_get_input_report
https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/hidclass/ni-hidclass-ioctl_hid_get_feature

Output buffer
The Irp->MdlAddress member points to the requester-allocated output
buffer that the HID class driver
uses to return the input report. The first byte of the buffer, which
the requester uses to input a report ID
or zero, is unchanged. The input report -- excluding its report ID, if
report IDs are used -- is returned at
((PUCHAR)Irp->MdlAddress + 1).

Output buffer length
The size of the input report.
***************************************

Please help to check if my interpretation is correct or not. Thanks.

-- 
Xiaofan