Quirks, user hacks, testing and stable

udev-hid-bpf divides HID-BPF programs into two categories: quirks and user hacks. Quirks are programs that fix a device that objectively has a hardware or firmware bug. Examples include axis that are inverted, provide the wrong ranges/values or event sequences that are logically impossible. We expect that quirks are eventually upstreamed into the kernel.

User hacks are HID-BPF programs that change a user-subjective preference on a device. Examples include swapping buttons for convenience or muting an axis to avoid crashes in a specific application. These programs will never be upstreamed as they are user and use-case specific. udev-hid-bpf maintains a set of user hacks as examples and starting point for users who want to develop their own hacks.

To divide this we use the following directory structure:

• bpf/testing/ is where all new quirks should go. Once they have proven to be good enough, they should be submitted to the upstream kernel. Distributions that package udev-hid-bpf may make these quirks available but should not require them.

• bpf/stable/ is where quirks move to once upstream has accepted them and they will be part of the next kernel release. Distributions that package udev-hid-bpf should package these stable quirks.

• bpf/userhacks is where all user hacks should go. Unlike quirks these will never move to stable. It is not recommended that distributions package userhacks.

Installing testing or stable

By default, only testing is enabled during meson setup. To select which one to install, run meson configure -Dbpfs=testing,stable builddir/ (or a subset thereof) or pass -Dbpfs to the initial meson setup call. Note that userhacks cannot be selected as a whole and have to be built and installed individually.

Installing individual HID-BPF programs

To build and install only one specific file use the -Dfilter-bpf option. This option takes one or more comma-separated strings, any bpf.c file that contains one of the strings will be installed. For example, to build and install all BPF files with Foo or Bar in their file name use -Dfilter-bpf=Foo,Bar. Specifying a filter automatically enables all of testing, stable and userhacks but only the matching files will be installed.

Rebuilding

Note that all the bpf.c files that are known to meson (so registered in src/bpf/*/meson.build) are recompiled when there is a change. So for bpf/userhacks, in most cases, no meson option needs to be added: just recompile with ninja and then use udev-hid-bpf install ./builddir/src/bpf/userhacks/my_awesome_hid_bpf_filter.bpf.c.