On Fri, Mar 18, 2022 at 9:22 AM Benjamin Tissoires benjamin.tissoires@redhat.com wrote:
Gives a primer on HID-BPF.
Signed-off-by: Benjamin Tissoires benjamin.tissoires@redhat.com
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``.
[...]