xref: /linux/drivers/hid/bpf/progs/README (revision 2697b79a469b68e3ad3640f55284359c1396278d) 
1# HID-BPF programs
2
3This directory contains various fixes for devices. They add new features or
4fix some behaviors without being entirely mandatory. It is better to load them
5when you have such a device, but they should not be a requirement for a device
6to be working during the boot stage.
7
8The .bpf.c files provided here are not automatically compiled in the kernel.
9They should be loaded in the kernel by `udev-hid-bpf`:
10
11https://gitlab.freedesktop.org/libevdev/udev-hid-bpf
12
13The main reasons for these fixes to be here is to have a central place to
14"upstream" them, but also this way we can test them thanks to the HID
15selftests.
16
17Once a .bpf.c file is accepted here, it is duplicated in `udev-hid-bpf`
18in the `src/bpf/stable` directory, and distributions are encouraged to
19only ship those bpf objects. So adding a file here should eventually
20land in distributions when they update `udev-hid-bpf`
21
22## Compilation
23
24Just run `make`
25
26## Installation
27
28### Automated way
29
30Just run `sudo udev-hid-bpf install ./my-awesome-fix.bpf.o`
31
32### Manual way
33
34- copy the `.bpf.o` you want in `/etc/udev-hid-bpf/`
35- create a new udev rule to automatically load it
36
37The following should do the trick (assuming udev-hid-bpf is available in
38/usr/bin):
39
40```
41$> cp xppen-ArtistPro16Gen2.bpf.o /etc/udev-hid-bpf/
42$> udev-hid-bpf inspect xppen-ArtistPro16Gen2.bpf.o
43[
44  {
45    "name": "xppen-ArtistPro16Gen2.bpf.o",
46    "devices": [
47      {
48        "bus": "0x0003",
49        "group": "0x0001",
50        "vid": "0x28BD",
51        "pid": "0x095A"
52      },
53      {
54        "bus": "0x0003",
55        "group": "0x0001",
56        "vid": "0x28BD",
57        "pid": "0x095B"
58      }
59    ],
60...
61$> cat <EOF > /etc/udev/rules.d/99-load-hid-bpf-xppen-ArtistPro16Gen2.rules
62ACTION!="add|remove", GOTO="hid_bpf_end"
63SUBSYSTEM!="hid", GOTO="hid_bpf_end"
64
65# xppen-ArtistPro16Gen2.bpf.o
66ACTION=="add",ENV{MODALIAS}=="hid:b0003g0001v000028BDp0000095A", RUN{program}+="/usr/local/bin/udev-hid-bpf add $sys$devpath /etc/udev-hid-bpf/xppen-ArtistPro16Gen2.bpf.o"
67ACTION=="remove",ENV{MODALIAS}=="hid:b0003g0001v000028BDp0000095A", RUN{program}+="/usr/local/bin/udev-hid-bpf remove $sys$devpath "
68# xppen-ArtistPro16Gen2.bpf.o
69ACTION=="add",ENV{MODALIAS}=="hid:b0003g0001v000028BDp0000095B", RUN{program}+="/usr/local/bin/udev-hid-bpf add $sys$devpath /etc/udev-hid-bpf/xppen-ArtistPro16Gen2.bpf.o"
70ACTION=="remove",ENV{MODALIAS}=="hid:b0003g0001v000028BDp0000095B", RUN{program}+="/usr/local/bin/udev-hid-bpf remove $sys$devpath "
71
72LABEL="hid_bpf_end"
73EOF
74$> udevadm control --reload
75```
76
77Then unplug and replug the device.
78
79## Checks
80
81### udev rule
82
83You can check that the udev rule is correctly working by issuing
84
85```
86$> udevadm test /sys/bus/hid/devices/0003:28BD:095B*
87...
88run: '/usr/local/bin/udev-hid-bpf add /sys/devices/virtual/misc/uhid/0003:28BD:095B.0E57 /etc/udev-hid-bpf/xppen-ArtistPro16Gen2.bpf.o'
89```
90
91### program loaded
92
93You can check that the program has been properly loaded with `bpftool`
94
95```
96$> bpftool prog
97...
98247: tracing  name xppen_16_fix_eraser tag 18d389353ed2ef07  gpl
99	loaded_at 2024-03-28T16:02:28+0100  uid 0
100	xlated 120B  jited 77B  memlock 4096B
101	btf_id 487
102```
103