Beginner advice for USB HID filter driver

Antonio Ceccato 6

Hello everybody,

I have this issue: a USB mouse I recently bought has a total of 6 buttons, but the 6th button isn't recognized unless I install vendor software and bind it to extremely limited functions.

I inspected the raw USB HID report descriptor that the device reports, and two things are clear:

the Button usage page reports only 5 bits (so only 5 buttons) and declares 3 constant bits for padding to a full byte
when clicking the 6th button, the input report shows that bit 6 in the Button usage page is set (which is the first of the 3 declared as padding above)

Therefore, the device is hiding the 6th button by not declaring it in the Input Report.
I feel like the easiest workaround would be to intercept the USB HID report descriptor response and modify it on the fly to set 6 bits for buttons and 2 for padding instead of 5+3.

And here is where my knowledge stops: I have very little experience with Win32 / kernel low-level programming, my daily job involves mainly C# .NET and web environments.
I have found and read the official documentation about WDF, KMDF, UMDF, Virtual HID Framework, but I still don't have a clear enough picture to make an informed decision on where my code should be targeted. I understand I might have to write a "filter" driver, but I could also directly access HID reports from userspace (if that allows me to modify the descriptor, which I don't think so).

What advice can you give me on where to start with this driver? Or do you have a better idea with regards to solving my issue?

Thanks in advance

1 answer

Doron Holan 1,801 Reputation points

2022-01-14T00:51:23.537+00:00

You want a filter driver that is below hidusb.sys. You want to be able to modify the raw hid descriptor before hidclass (via hidusb) processes it. This also allows you to modify the incoming hid data as you want. This gets you far enough to properly report the 6th button and hidparse can find and extract it.....

BUT, you have another problem now. The mouse driver (mouhid.sys) does not know about the 6th button, so the higher-level driver will not query for the 6th button data. Mouhid.sys exclusively owns the mouse and is the only reader so there is no way for you to read the 6th button data in user mode nor does the 6th button get plumbed through the mouse input pipeline. So, you need another way to expose the 6th button data. Since the 6th button is not plumbed through the mouse input pipeline there is no generic solution to expose it to all applications, all consumption will be custom.

You can use the proposed (in the first paragraph) lower hidusb filter to expose the 6th button (and anything else) by exposing a raw PDO and routing the 6th button data through it. Your user mode application can then open the raw PDO through a device interface and read it. The moufiltr example shows how to create a raw PDO, you would have to go through the sample and extract the relevant code.

If you want to forgo modifying the raw hid descriptor and just want to get at the 6th button, there is another possible solution.
Please sign in to rate this answer.

1 person found this answer helpful.
Antonio Ceccato 6 Reputation points

2022-01-14T07:22:11.777+00:00

Thank you very much for your useful answer!

My idea of modifying the raw report descriptor was mostly to avoid having to handle the 6th button separately (ideally I would have used X-Mouse Button Control to remap buttons and functions, which currently only shows buttons 4 and 5, but not 6). I thought I would be able to trick the standard driver (mouhid.sys?), since I believed it would have used the report descriptor to "discover" buttons. Is there really no way to trick mouhid and have it seamlessly plumb everything needed for the 6th button?

What is the alternative solution you hinted to? If modifying the raw descriptor is a "dead end" and I'd still have to write something to handle the 6th button separately, I'd rather take the easier route.

Thank you again

Edit:
I just found this revealing document: https://learn.microsoft.com/en-us/windows-hardware/drivers/hid/keyboard-and-mouse-hid-client-drivers
It's clear to me now that only 5 buttons are supported by mouhid.sys. Also I now understand your hypothesis of adding a filter between hidusb.sys (HID transport driver) and hidclass.sys.

So, what would the easiest way to get events from the 6th button be? It's ok if it won't work with X-Mouse, I can write a small utility to map custom functions to it.

Thanks

Doron Holan 1,801 Reputation points

2022-01-14T23:07:06.343+00:00

The design and strategy is the same for the two options, both are about the same complexity. As stated above, the design is the driver

enumerates a raw PDO so that an application can open it (both hidclass and mouhid block your app open so you have to create a new path)

inspects the data coming from the device and copies off the relevant state so that it can be reported through the raw PDO. This inspection will be hand written, you can't use the HID parsing APIs since the sixth button is not in the HID descriptor.

optionally keep a ring buffer of state if the app is not reading fast enough (IOW, the device reports data when there is no queued IO from the app)

The app always has a query for data pending in the driver (could be more than one). That query can be a read request or an IOCTL (typically it is an IOCTL).

The driver can exist in either of these two locations in the stack

As described above, below hidusb. In this case you will set a completion routine on the read IO request (a submit URB IOCTL) on the appropriate pipe.

Below mouhid. In this case you will set a completion routine on the read request (IRP_MJ_READ).

Doron Holan 1,801 Reputation points

2022-01-14T23:07:13.677+00:00

There is no perfect fit WDK sample to start from. The best fit is moufiltr. It is written to sit above mouhid and filters data in a different way. You can remove all that logic if you want, it would be inert below mouhid as the filter will not see the IOCTLs that mouclass sends. Keep the logic around creating the raw PDO and the creation of the queues for the PDO and the filter device. You will need to update the sample to present read requests . In the queue dispatch routine you will set a completion routine and then send the read down the stack (WdfRequestFormatRequestUsingCurrentType , WdfRequestSetCompletionRoutine , WdfIoTargetSend).

Antonio Ceccato 6 Reputation points

2022-01-17T21:19:19.643+00:00

Thank you very much for your expert and detailed insight. I am now going to give it a try and report back if and when I succeed :)

Antonio Ceccato 6 Reputation points

2022-01-19T21:28:46.6+00:00

Hi DoronHolan,
after a non-trivial amount of trial and error I managed to successfully create a project, build it and run the driver on a target machine while connected to WinDbg, and view WPP traces via TraceView.
The code is currently nothing more than the basic scaffolding offered by VS2019's KMDF project template, plus the passthrough function from moufiltr that dispatches all IOCTLs to the lower driver.
I also edited the INF to include msmouse.inf, "need" its HID mouse installation sections and set my driver as a LowerFilter, plus setting the device hardware ID ("HID\VID_056E&PID_00FB&Col01").

Thank you again

Antonio Ceccato 6 Reputation points

2022-01-19T21:30:47.643+00:00

(My last reply is incomplete, clicking Submit just didn't do anything...)

I uploaded my code to GitHub: github.com/LaXiS96/EXGFilter

Now, everything (for what it currently is) seems to work without bug checking, but in Device Manager I now see two devices that are using my driver (while before it was a single "HID-compliant mouse"):

the first is "working properly", its device instance ID is "HID\VID_056E&PID_00FB&COL01\6&1D0220BE&0&0000"

the second reports code 10: "The specified request is not a valid operation for the target device" and its device instance ID is "ROOT\MOUSE\0000"

What does this mean? Did I not passthrough everything?
I would not have expected the second device to appear, and I'm not really sure what my code is doing under the hood.
Did I actually register a lower filter driver to mouhid, or something else?
Now, how would I start intercepting IRP_MJ_READ requests?

Most of the terms you used in your replies are currently flying over my head, but I'm reading as much documentation as possible.

Doron Holan 1,801 Reputation points

2022-01-19T21:59:38.963+00:00

ROOT\MOUSE\Xxxxx is a software enumerated device. You most likely ran devcon install when trying to apply your driver. Devcon install creates this root enumerated software device (install doesn't do what you think it does). You want to run devcon update and it will apply it to the HID\Xxxxx\Xxxxx device. you can safely remove the root\mouse device.
Sign in to comment