drivers/hid/bpf/progs/README

   1 # HID-BPF programs
   2
   3 This directory contains various fixes for devices. They add new features or
   4 fix some behaviors without being entirely mandatory. It is better to load them
   5 when you have such a device, but they should not be a requirement for a device
   6 to be working during the boot stage.
   7
   8 The .bpf.c files provided here are not automatically compiled in the kernel.
   9 They should be loaded in the kernel by `udev-hid-bpf`:
  10
  11 https://gitlab.freedesktop.org/libevdev/udev-hid-bpf
  12
  13 The 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
  15 selftests.
  16
  17 Once a .bpf.c file is accepted here, it is duplicated in `udev-hid-bpf`
  18 in the `src/bpf/stable` directory, and distributions are encouraged to
  19 only ship those bpf objects. So adding a file here should eventually
  20 land in distributions when they update `udev-hid-bpf`
  21
  22 ## Compilation
  23
  24 Just run `make`
  25
  26 ## Installation
  27
  28 ### Automated way
  29
  30 Just 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
  37 The 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
  62 ACTION!="add|remove", GOTO="hid_bpf_end"
  63 SUBSYSTEM!="hid", GOTO="hid_bpf_end"
  64
  65 # xppen-ArtistPro16Gen2.bpf.o
  66 ACTION=="add",ENV{MODALIAS}=="hid:b0003g0001v000028BDp0000095A", RUN{program}+="/usr/local/bin/udev-hid-bpf add $sys$devpath /etc/udev-hid-bpf/xppen-ArtistPro16Gen2.bpf.o"
  67 ACTION=="remove",ENV{MODALIAS}=="hid:b0003g0001v000028BDp0000095A", RUN{program}+="/usr/local/bin/udev-hid-bpf remove $sys$devpath "
  68 # xppen-ArtistPro16Gen2.bpf.o
  69 ACTION=="add",ENV{MODALIAS}=="hid:b0003g0001v000028BDp0000095B", RUN{program}+="/usr/local/bin/udev-hid-bpf add $sys$devpath /etc/udev-hid-bpf/xppen-ArtistPro16Gen2.bpf.o"
  70 ACTION=="remove",ENV{MODALIAS}=="hid:b0003g0001v000028BDp0000095B", RUN{program}+="/usr/local/bin/udev-hid-bpf remove $sys$devpath "
  71
  72 LABEL="hid_bpf_end"
  73 EOF
  74 $> udevadm control --reload
  75 ```
  76
  77 Then unplug and replug the device.
  78
  79 ## Checks
  80
  81 ### udev rule
  82
  83 You can check that the udev rule is correctly working by issuing
  84
  85 ```
  86 $> udevadm test /sys/bus/hid/devices/0003:28BD:095B*
  87 ...
  88 run: '/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
  93 You can check that the program has been properly loaded with `bpftool`
  94
  95 ```
  96 $> bpftool prog
  97 ...
  98 247: 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 ```