Documentation/hid/hid-bpf.rst

38 HID-BPF allows the userspace program to load the program itself, ensuring we
48 We can reduce this burden by providing an eBPF program instead. Once such a
49 program  has been verified by the user, we can embed the source code into the
50 kernel tree and ship the eBPF program and load it directly instead of loading
80 events into wheel events. Also, the userspace program can set/unset the haptic
96 kernel/bpf program because we can intercept any incoming command.
119 program.
128 When a BPF program needs to emit input events, it needs to talk with the HID
144 A ``hid_bpf_device_event`` is calling a BPF program when an event is received from
153 BPF program of this type. This is called on ``probe`` from the driver and allows to
154 change the report descriptor from the BPF program. Once a ``hid_bpf_rdesc_fixup``
155 program has been loaded, it is not possible to overwrite it unless the program which
156 inserted it allows us by pinning the program and closing all of its fds pointing to it.
166 Available tracing functions to attach a HID-BPF program:
184 General overview of a HID-BPF program
191 it, a bpf program needs to first call :c:func:`hid_bpf_get_data`.
222 Effect of a HID-BPF program
229 program, the new program is appended at the end of the list.
230 ``HID_BPF_FLAG_INSERT_HEAD`` will insert the new program at the beginning of the
243 If a program changes the data associated with the context, the next one will see
250 A BPF program returning a negative error discards the event, i.e. this event will not be
260 To retrieve a context associated with the device, the program must call
270 The ``hid_bpf_rdesc_fixup`` program works in a similar manner to
277 The eBPF program can modify the data buffer at-will and the kernel uses the
280 Whenever a ``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` program is attached (if no
281 program was attached before), the kernel immediately disconnects the HID device
284 In the same way, when the ``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` program is
287 There is no ``detach`` facility in HID-BPF. Detaching a program happens when
288 all the user space file descriptors pointing at a program are closed.
291 The previous owner will likely pin the program in the bpffs, and we can then
294 Attaching a bpf program to a device
297 ``libbpf`` does not export any helper to attach a HID-BPF program.
298 Users need to use a dedicated ``syscall`` program which will call
304 ``progam_fd`` is the opened file descriptor of the program to attach.
308 We can not rely on hidraw to bind a BPF program to a HID device. hidraw is an
322 component that loads the eBPF program.
348 For that, we can create a basic skeleton for our BPF program::
411 program first::
436 Our userspace program can now listen to notifications on the ring buffer, and
439 When the userspace program doesn't need to listen to events anymore, it can just
441 detach the program from the HID device.
443 Of course, in other use cases, the userspace program can also pin the fd to the
449 To be able to change the haptic feedback from the tablet, the userspace program
452 Instead of using hidraw for that, we can create a ``SEC("syscall")`` program
492 And then userspace needs to call that program directly::
515 Now our userspace program is aware of the haptic state and can control it. The
516 program could make this state further available to other userspace programs