On Fri, Mar 18, 2022 at 9:22 AM Benjamin Tissoires <benjamin.tissoires@xxxxxxxxxx> wrote: > > Gives a primer on HID-BPF. > > Signed-off-by: Benjamin Tissoires <benjamin.tissoires@xxxxxxxxxx> > > --- > > new in v3 > --- > Documentation/hid/hid-bpf.rst | 444 ++++++++++++++++++++++++++++++++++ > Documentation/hid/index.rst | 1 + > include/uapi/linux/bpf_hid.h | 54 ++++- > 3 files changed, 492 insertions(+), 7 deletions(-) > create mode 100644 Documentation/hid/hid-bpf.rst > > diff --git a/Documentation/hid/hid-bpf.rst b/Documentation/hid/hid-bpf.rst > new file mode 100644 > index 000000000000..0bf0d937b0e1 > --- /dev/null > +++ b/Documentation/hid/hid-bpf.rst > @@ -0,0 +1,444 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +======= > +HID-BPF > +======= > + > +HID is a standard protocol for input devices and it can greatly make use > +of the eBPF capabilities to speed up development and add new capabilities > +to the existing HID interfaces. > + > +.. contents:: > + :local: > + :depth: 2 > + > + > +When (and why) using HID-BPF > +============================ > + > +We can enumerate several use cases for when using HID-BPF is better than > +using a standard kernel driver fix. > + > +dead zone of a joystick > +----------------------- > + > +Assuming you have a joystick that is getting older, it is common to see it > +wobbling around its neutral point. This is usually filtered at the application > +level by adding a *dead zone* for this specific axis. > + > +With HID-BPF, we can put the filtering of this dead zone in the kernel directly > +so we don't wake up userspace when nothing else is happening on the input > +controller. > + > +Of course, given that this dead zone is device specific, we can not create a nit: s/can not/cannot There are a few more "can not" below. [...] > +firewall > +-------- > + > +What if we want to prevent other users to access a specific feature of a > +device? (think a possibly bonker firmware update entry popint) nit: point > + > +With eBPF, we can intercept any HID command emitted to the device and > +validate it or not. > + > +This also allows to sync the state between the userspace and the > +kernel/bpf program because we can intercept any incoming command. > + [...] > + > +The main idea behind HID-BPF is that it works at an array of bytes level. > +Thus, all of the parsing of the HID report and the HID report descriptor > +must be implemented in the userspace component that loads the eBPF > +program. > + > +For example, in the dead zone joystick from above, knowing which fields > +in the data stream needs to be set to ``0`` needs to be computed by userspace. > + > +A corrolar of this is that HID-BPF doesn't know about the other subsystems nit: corollary? > +available in the kernel. *You can not directly emit input event through the > +input API from eBPF*. > + > +When a BPF program need to emit input events, it needs to talk HID, and rely > +on the HID kernel processing to translate the HID data into input events. > + > +Available types of programs > +=========================== [...] > + > +``BPF_HID_RDESC_FIXUP`` > +~~~~~~~~~~~~~~~~~~~~~~~ > + > +Last, the ``BPF_HID_RDESC_FIXUP`` program works in the similar maneer than nit: manner. > +``.report_fixup`` of ``struct hid_driver``. > + [...]
