Repository navigation
Consolidate HID report descriptor parsing across backends #833
Description
Problem
HIDAPI currently has several private implementations that decode or walk HID report descriptors:
libusb/hid.chas its own item walker for Usage Page/Usage extraction.- PR Properly determine libusb read size for large reports (Fixes #274) #728 adds
libusb/hidapi_libusb_report_descriptor.hto calculate maximum Input/Output/Feature report sizes. linux/hid.cindependently implements report-item decoding and Usage Page/Usage extraction.netbsd/hid.ccontains another closely related implementation.
These routines duplicate short/long item decoding, bounds checks, global-item state, Usage handling, and malformed-descriptor behavior. Keeping the new libusb parser under the backend directory also makes reuse by the hidraw and NetBSD backends unnecessarily difficult.
Windows' hidapi_descriptor_reconstruct.c performs the inverse operation—reconstructing a descriptor from preparsed data—so it may remain separate, but shared item definitions or test data could still be evaluated.
Proposal
Introduce a private common report-descriptor module, for example under src/ or another backend-neutral internal directory, and migrate reusable decoding logic into it.
The common layer should:
- Decode HID short and long items safely.
- Expose enough parser state or callbacks to derive Usage Page/Usage and per-report-ID sizes.
- Keep transport-specific descriptor retrieval in each backend.
- Remain an internal implementation detail with no public ABI additions.
- Compile as both C and C++ under
HIDAPI_BUILD_AS_CXX. - Preserve each backend's existing fallback and malformed-descriptor behavior.
Acceptance criteria
- libusb, Linux hidraw, and NetBSD reuse the common descriptor walker where practical.
- Duplicated byte/item decoding helpers are removed.
- Existing backend behavior remains covered by tests.
- The Windows fixture corpus and focused malformed/boundary cases provide shared parser coverage.
- The eventual location and naming of
hidapi_libusb_report_descriptor.hno longer imply that generic parsing belongs exclusively to libusb.
Related to #728.
Related to #796.
Generated by Codex (GPT-5.6 Sol).
Activity
benedekkupper commentedon Sep 2, 2026
I don't know what are your feelings/policies about C++, but this library could be helpful here: https://github.com/IntergatedCircuits/hid-rp
It has various levels of facilities for parsing HID report descriptors, from the simplest iteration from item to item, to more structured parsing with global state stack tracking. It also generates full usage tables and can print report descriptors with usage information.
Youw commentedon Sep 2, 2026
I don't mind anything regarding C++ (I'm a C++ developer myself), specially where it makes sense.
As for the scope of this particular task - using
hid-rpwould mean make all of HIDAPI implementation a C++ source, or introduce C++ modules with "C bindings", which I think should neither happen. What is used by HIDAPI internally is partial and isolated, let it stay that way.libusb: handle reports larger than USB packets (#728)