README

  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```