Documentation/hid/hid-bpf.rst

4 HID-BPF
7 HID is a standard protocol for input devices but some devices may require
10 existing HID interfaces.
17 When (and why) to use HID-BPF
20 There are several use cases when using HID-BPF is better
30 With HID-BPF, we can apply this filtering in the kernel directly so userspace
38 HID-BPF allows the userspace program to load the program itself, ensuring we
44 In the HID tree, half of the drivers only fix one key or one byte
61 channels of communication that our HID and input stack do not support.
70 The kernel has a relatively static mapping of HID items to evdev bits.
92 With eBPF, we can intercept any HID command emitted to the device and
113 High-level view of HID-BPF
116 The main idea behind HID-BPF is that it works at an array of bytes level.
117 Thus, all of the parsing of the HID report and the HID report descriptor
124 A corollary of this is that HID-BPF doesn't know about the other subsystems
128 When a BPF program needs to emit input events, it needs to talk with the HID
129 protocol, and rely on the HID kernel processing to translate the HID data into
135 HID-BPF is built "on top" of BPF, meaning that we use tracing method to
138 HID-BPF has the following attachment types available:
149 This time, we can do any operations allowed by HID-BPF, and talking to the device is
166 Available tracing functions to attach a HID-BPF program:
172 Available API that can be used in all HID-BPF programs:
178 Available API that can be used in syscall HID-BPF programs:
184 General overview of a HID-BPF program
222 Effect of a HID-BPF program
225 For all HID-BPF attachment types except for :c:func:`hid_bpf_rdesc_fixup`, several eBPF
247 HID stack will work on the modified data, with the ``size`` field of the last hid_bpf_ctx
251 processed by the HID stack. Clients (hidraw, input, LEDs) will **not** see this event.
281 program was attached before), the kernel immediately disconnects the HID device
287 There is no ``detach`` facility in HID-BPF. Detaching a program happens when
297 ``libbpf`` does not export any helper to attach a HID-BPF program.
301 ``hid_id`` is the unique system ID of the HID device (the last 4 numbers in the
308 We can not rely on hidraw to bind a BPF program to a HID device. hidraw is an
309 artefact of the processing of the HID device, and is not stable. Some drivers
313 On the other hand, the ``hid_id`` is stable for the entire life of the HID device,
324 An (almost) complete example of a BPF enhanced HID device
354   /* HID programs need to be GPL */
357   /* HID-BPF kfunc API definitions */
441 detach the program from the HID device.
455   /* some more HID-BPF kfunc API definitions */