From 380ccf0ee4b78580329dc0b1ebaa373d6e1de2bf Mon Sep 17 00:00:00 2001 From: Peter Hutterer <peter.hutterer@who-t.net> Date: Mon, 10 Feb 2025 21:32:34 +1000 Subject: [PATCH] doc: update the docs for the FixedSizeVendorReport macro This needs to be set to the largest HID report as the kernel discards any HID report sized larger than whatever the report descriptor defines. Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net> Part-of: <https://gitlab.freedesktop.org/libevdev/udev-hid-bpf/-/merge_requests/182> --- doc/report-descriptor-macros.rst | 21 ++++++++++++++------- tools/hid_report_helpers.h.jinja | 7 +++++-- 2 files changed, 19 insertions(+), 9 deletions(-) diff --git a/doc/report-descriptor-macros.rst b/doc/report-descriptor-macros.rst index e5cdfc5..88b6209 100644 --- a/doc/report-descriptor-macros.rst +++ b/doc/report-descriptor-macros.rst @@ -65,13 +65,20 @@ to make the device work without having to change the actual HID reports in the B Enforcing the right HID Report size ----------------------------------- -However there is a drawback: the kernel requires that the returned HID Report -Descriptor describes **at least one HID Report** that is the same size as the -original HID Report Descriptor describes. -In other words, if the original HID Report Descriptor describes a report of size 11 the fixed -HID Report Descriptor **must** include at least one report that is of size 11. +However there is a drawback: the kernel discards any any HID reports that are +larger than the largest report in the HID report descriptor. Thus a modified +HID Report Descriptor must include **at least one HID Report** that is (at +least) the same size as the **largest** report in the original HID Report +Descriptor. + +In other words, if the original HID Report Descriptor describes three +reports of sizes 8, 16 and 20 the fixed HID Report Descriptor **must** include +at least one report that is of size 20. This can easily be achieved with the ``FixedSizeVendorReport(len)`` helper macro as shown above. This macro will add one additional vendor-specific HID Report to the HID Report Descriptor with -the given size. This HID Report will be ignored by the kernel but serves to guarantee our BPF -is handled correctly. +the given size in bytes. This HID Report will be ignored by the kernel but +guarantees HID reports are not immediately discarded before the BPF program gets to look at them. +The ``FixedSizeVendorReport(len)`` macro must not be used more than once per +report descriptor and should not be larger than necessary +to avoid unnecessary buffer allocations in the kernel. diff --git a/tools/hid_report_helpers.h.jinja b/tools/hid_report_helpers.h.jinja index bf12e2e..8793279 100644 --- a/tools/hid_report_helpers.h.jinja +++ b/tools/hid_report_helpers.h.jinja @@ -144,8 +144,11 @@ * report with Report ID 0xac of the given size in bytes. * The size is inclusive of the 1 byte Report ID prefix. * - * HID-BPF requires that at least one report has - * the same size as the original report from the device. + * The kernel discards any HID reports that are larger + * than the largest report in a HID report descriptor. + * Thus at least one report must have (at least) + * the same size as the largest original report from + * the device. * The easy way to ensure that is to add this * macro as the last element of your CollectionApplication * other reports can be of any size less than this. -- GitLab