Merge branch 'for-6.11/bpf' into for-linus

protocol, and rely on the HID kernel processing to translate the HID data into

input events.

In-tree HID-BPF programs and ``udev-hid-bpf``

=============================================

Official device fixes are shipped in the kernel tree as source in the

``drivers/hid/bpf/progs`` directory. This allows to add selftests to them in

``tools/testing/selftests/hid``.

However, the compilation of these objects is not part of a regular kernel compilation

given that they need an external tool to be loaded. This tool is currently

`udev-hid-bpf <https://libevdev.pages.freedesktop.org/udev-hid-bpf/index.html>`_.

For convenience, that external repository duplicates the files from here in

``drivers/hid/bpf/progs`` into its own ``src/bpf/stable`` directory. This allows

distributions to not have to pull the entire kernel source tree to ship and package

those HID-BPF fixes. ``udev-hid-bpf`` also has capabilities of handling multiple

objects files depending on the kernel the user is running.

Available types of programs

===========================

HID-BPF is built "on top" of BPF, meaning that we use tracing method to

HID-BPF is built "on top" of BPF, meaning that we use bpf struct_ops method to

declare our programs.

HID-BPF has the following attachment types available:

1. event processing/filtering with ``SEC("fmod_ret/hid_bpf_device_event")`` in libbpf

1. event processing/filtering with ``SEC("struct_ops/hid_device_event")`` in libbpf

2. actions coming from userspace with ``SEC("syscall")`` in libbpf

3. change of the report descriptor with ``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` in libbpf

3. change of the report descriptor with ``SEC("struct_ops/hid_rdesc_fixup")`` or

   ``SEC("struct_ops.s/hid_rdesc_fixup")`` in libbpf

A ``hid_bpf_device_event`` is calling a BPF program when an event is received from

A ``hid_device_event`` is calling a BPF program when an event is received from

the device. Thus we are in IRQ context and can act on the data or notify userspace.

And given that we are in IRQ context, we can not talk back to the device.

This time, we can do any operations allowed by HID-BPF, and talking to the device is

allowed.

Last, ``hid_bpf_rdesc_fixup`` is different from the others as there can be only one

Last, ``hid_rdesc_fixup`` is different from the others as there can be only one

BPF program of this type. This is called on ``probe`` from the driver and allows to

change the report descriptor from the BPF program. Once a ``hid_bpf_rdesc_fixup``

change the report descriptor from the BPF program. Once a ``hid_rdesc_fixup``

program has been loaded, it is not possible to overwrite it unless the program which

inserted it allows us by pinning the program and closing all of its fds pointing to it.

Note that ``hid_rdesc_fixup`` can be declared as sleepable (``SEC("struct_ops.s/hid_rdesc_fixup")``).

Developer API:

==============

User API data structures available in programs:

-----------------------------------------------

Available ``struct_ops`` for HID-BPF:

-------------------------------------

.. kernel-doc:: include/linux/hid_bpf.h

   :identifiers: hid_bpf_ops

Available tracing functions to attach a HID-BPF program:

--------------------------------------------------------

.. kernel-doc:: drivers/hid/bpf/hid_bpf_dispatch.c

   :functions: hid_bpf_device_event hid_bpf_rdesc_fixup

User API data structures available in programs:

-----------------------------------------------

Available API that can be used in all HID-BPF programs:

-------------------------------------------------------

.. kernel-doc:: include/linux/hid_bpf.h

   :identifiers: hid_bpf_ctx

Available API that can be used in all HID-BPF struct_ops programs:

------------------------------------------------------------------

.. kernel-doc:: drivers/hid/bpf/hid_bpf_dispatch.c

   :functions: hid_bpf_get_data

   :identifiers: hid_bpf_get_data

Available API that can be used in syscall HID-BPF programs:

-----------------------------------------------------------

Available API that can be used in syscall HID-BPF programs or in sleepable HID-BPF struct_ops programs:

-------------------------------------------------------------------------------------------------------

.. kernel-doc:: drivers/hid/bpf/hid_bpf_dispatch.c

   :functions: hid_bpf_attach_prog hid_bpf_hw_request hid_bpf_hw_output_report hid_bpf_input_report hid_bpf_allocate_context hid_bpf_release_context

   :identifiers: hid_bpf_hw_request hid_bpf_hw_output_report hid_bpf_input_report hid_bpf_try_input_report hid_bpf_allocate_context hid_bpf_release_context

General overview of a HID-BPF program

=====================================

Effect of a HID-BPF program

---------------------------

For all HID-BPF attachment types except for :c:func:`hid_bpf_rdesc_fixup`, several eBPF

programs can be attached to the same device.

For all HID-BPF attachment types except for :c:func:`hid_rdesc_fixup`, several eBPF

programs can be attached to the same device. If a HID-BPF struct_ops has a

:c:func:`hid_rdesc_fixup` while another is already attached to the device, the

kernel will return `-EINVAL` when attaching the struct_ops.

Unless ``HID_BPF_FLAG_INSERT_HEAD`` is added to the flags while attaching the

program, the new program is appended at the end of the list.

``HID_BPF_FLAG_INSERT_HEAD`` will insert the new program at the beginning of the

list which is useful for e.g. tracing where we need to get the unprocessed events

from the device.

Unless ``BPF_F_BEFORE`` is added to the flags while attaching the program, the new

program is appended at the end of the list.

``BPF_F_BEFORE`` will insert the new program at the beginning of the list which is

useful for e.g. tracing where we need to get the unprocessed events from the device.

Note that if there are multiple programs using the ``HID_BPF_FLAG_INSERT_HEAD`` flag,

Note that if there are multiple programs using the ``BPF_F_BEFORE`` flag,

only the most recently loaded one is actually the first in the list.

``SEC("fmod_ret/hid_bpf_device_event")``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``SEC("struct_ops/hid_device_event")``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Whenever a matching event is raised, the eBPF programs are called one after the other

and are working on the same data buffer.

in the sysfs path: ``/sys/bus/hid/devices/xxxx:yyyy:zzzz:0000``).

To retrieve a context associated with the device, the program must call

:c:func:`hid_bpf_allocate_context` and must release it with :c:func:`hid_bpf_release_context`

hid_bpf_allocate_context() and must release it with hid_bpf_release_context()

before returning.

Once the context is retrieved, one can also request a pointer to kernel memory with

:c:func:`hid_bpf_get_data`. This memory is big enough to support all input/output/feature

hid_bpf_get_data(). This memory is big enough to support all input/output/feature

reports of the given device.

``SEC("fmod_ret/hid_bpf_rdesc_fixup")``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``SEC("struct_ops/hid_rdesc_fixup")``

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``hid_bpf_rdesc_fixup`` program works in a similar manner to

``.report_fixup`` of ``struct hid_driver``.

The ``hid_rdesc_fixup`` program works in a similar manner to ``.report_fixup``

of ``struct hid_driver``.

When the device is probed, the kernel sets the data buffer of the context with the

content of the report descriptor. The memory associated with that buffer is

The eBPF program can modify the data buffer at-will and the kernel uses the

modified content and size as the report descriptor.

Whenever a ``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` program is attached (if no

program was attached before), the kernel immediately disconnects the HID device

and does a reprobe.

Whenever a struct_ops containing a ``SEC("struct_ops/hid_rdesc_fixup")`` program

is attached (if no program was attached before), the kernel immediately disconnects

the HID device and does a reprobe.

In the same way, when the ``SEC("fmod_ret/hid_bpf_rdesc_fixup")`` program is

detached, the kernel issues a disconnect on the device.

In the same way, when this struct_ops is detached, the kernel issues a disconnect

on the device.

There is no ``detach`` facility in HID-BPF. Detaching a program happens when

all the user space file descriptors pointing at a program are closed.

all the user space file descriptors pointing at a HID-BPF struct_ops link are closed.

Thus, if we need to replace a report descriptor fixup, some cooperation is

required from the owner of the original report descriptor fixup.

The previous owner will likely pin the program in the bpffs, and we can then

The previous owner will likely pin the struct_ops link in the bpffs, and we can then

replace it through normal bpf operations.

Attaching a bpf program to a device

===================================

``libbpf`` does not export any helper to attach a HID-BPF program.

Users need to use a dedicated ``syscall`` program which will call

``hid_bpf_attach_prog(hid_id, program_fd, flags)``.

We now use standard struct_ops attachment through ``bpf_map__attach_struct_ops()``.

But given that we need to attach a struct_ops to a dedicated HID device, the caller

must set ``hid_id`` in the struct_ops map before loading the program in the kernel.

``hid_id`` is the unique system ID of the HID device (the last 4 numbers in the

sysfs path: ``/sys/bus/hid/devices/xxxx:yyyy:zzzz:0000``)

``progam_fd`` is the opened file descriptor of the program to attach.

``flags`` is of type ``enum hid_bpf_attach_flags``.

One can also set ``flags``, which is of type ``enum hid_bpf_attach_flags``.

We can not rely on hidraw to bind a BPF program to a HID device. hidraw is an

artefact of the processing of the HID device, and is not stable. Some drivers

  extern __u8 *hid_bpf_get_data(struct hid_bpf_ctx *ctx,

			      unsigned int offset,

			      const size_t __sz) __ksym;

  extern int hid_bpf_attach_prog(unsigned int hid_id, int prog_fd, u32 flags) __ksym;

  struct {

	__uint(type, BPF_MAP_TYPE_RINGBUF);

	__uint(max_entries, 4096 * 64);

  } ringbuf SEC(".maps");

  struct attach_prog_args {

	int prog_fd;

	unsigned int hid;

	unsigned int flags;

	int retval;

  };

  SEC("syscall")

  int attach_prog(struct attach_prog_args *ctx)

  {

	ctx->retval = hid_bpf_attach_prog(ctx->hid,

					  ctx->prog_fd,

					  ctx->flags);

	return 0;

  }

  __u8 current_value = 0;

  SEC("?fmod_ret/hid_bpf_device_event")

  SEC("struct_ops/hid_device_event")

  int BPF_PROG(filter_switch, struct hid_bpf_ctx *hid_ctx)

  {

	__u8 *data = hid_bpf_get_data(hid_ctx, 0 /* offset */, 192 /* size */);

	return 0;

  }

To attach ``filter_switch``, userspace needs to call the ``attach_prog`` syscall

program first::

  static int attach_filter(struct hid *hid_skel, int hid_id)

  {

	int err, prog_fd;

	int ret = -1;

	struct attach_prog_args args = {

		.hid = hid_id,

  SEC(".struct_ops.link")

  struct hid_bpf_ops haptic_tablet = {

  	.hid_device_event = (void *)filter_switch,

  };

	DECLARE_LIBBPF_OPTS(bpf_test_run_opts, tattrs,

		.ctx_in = &args,

		.ctx_size_in = sizeof(args),

	);

	args.prog_fd = bpf_program__fd(hid_skel->progs.filter_switch);

	prog_fd = bpf_program__fd(hid_skel->progs.attach_prog);

To attach ``haptic_tablet``, userspace needs to set ``hid_id`` first::

	err = bpf_prog_test_run_opts(prog_fd, &tattrs);

  static int attach_filter(struct hid *hid_skel, int hid_id)

  {

  	int err, link_fd;

  	hid_skel->struct_ops.haptic_tablet->hid_id = hid_id;

  	err = hid__load(skel);

  	if (err)

  		return err;

	return args.retval; /* the fd of the created bpf_link */

  	link_fd = bpf_map__attach_struct_ops(hid_skel->maps.haptic_tablet);

  	if (!link_fd) {

  		fprintf(stderr, "can not attach HID-BPF program: %m\n");

  		return -1;

  	}

  	return link_fd; /* the fd of the created bpf_link */

  }

Our userspace program can now listen to notifications on the ring buffer, and

is awaken only when the value changes.

When the userspace program doesn't need to listen to events anymore, it can just

close the returned fd from :c:func:`attach_filter`, which will tell the kernel to

close the returned bpf link from :c:func:`attach_filter`, which will tell the kernel to

detach the program from the HID device.

Of course, in other use cases, the userspace program can also pin the fd to the

obj-$(CONFIG_HID_BPF) += hid_bpf.o

CFLAGS_hid_bpf_dispatch.o += -I$(LIBBPF_INCLUDE)

CFLAGS_hid_bpf_jmp_table.o += -I$(LIBBPF_INCLUDE)

hid_bpf-objs += hid_bpf_dispatch.o hid_bpf_jmp_table.o

hid_bpf-objs += hid_bpf_dispatch.o hid_bpf_struct_ops.o

# SPDX-License-Identifier: GPL-2.0

OUTPUT := .output

abs_out := $(abspath $(OUTPUT))

CLANG ?= clang

LLC ?= llc

LLVM_STRIP ?= llvm-strip

TOOLS_PATH := $(abspath ../../../../tools)

BPFTOOL_SRC := $(TOOLS_PATH)/bpf/bpftool

BPFTOOL_OUTPUT := $(abs_out)/bpftool

DEFAULT_BPFTOOL := $(BPFTOOL_OUTPUT)/bootstrap/bpftool

BPFTOOL ?= $(DEFAULT_BPFTOOL)

LIBBPF_SRC := $(TOOLS_PATH)/lib/bpf

LIBBPF_OUTPUT := $(abs_out)/libbpf

LIBBPF_DESTDIR := $(LIBBPF_OUTPUT)

LIBBPF_INCLUDE := $(LIBBPF_DESTDIR)/include

BPFOBJ := $(LIBBPF_OUTPUT)/libbpf.a

INCLUDES := -I$(OUTPUT) -I$(LIBBPF_INCLUDE) -I$(TOOLS_PATH)/include/uapi

CFLAGS := -g -Wall

VMLINUX_BTF_PATHS ?= $(if $(O),$(O)/vmlinux)				\

		     $(if $(KBUILD_OUTPUT),$(KBUILD_OUTPUT)/vmlinux)	\

		     ../../../../vmlinux				\

		     /sys/kernel/btf/vmlinux				\

		     /boot/vmlinux-$(shell uname -r)

VMLINUX_BTF ?= $(abspath $(firstword $(wildcard $(VMLINUX_BTF_PATHS))))

ifeq ($(VMLINUX_BTF),)

$(error Cannot find a vmlinux for VMLINUX_BTF at any of "$(VMLINUX_BTF_PATHS)")

endif

ifeq ($(V),1)

Q =

msg =

else

Q = @

msg = @printf '  %-8s %s%s\n' "$(1)" "$(notdir $(2))" "$(if $(3), $(3))";

MAKEFLAGS += --no-print-directory

submake_extras := feature_display=0

endif

.DELETE_ON_ERROR:

.PHONY: all clean

all: entrypoints.lskel.h

clean:

	$(call msg,CLEAN)

	$(Q)rm -rf $(OUTPUT) entrypoints

entrypoints.lskel.h: $(OUTPUT)/entrypoints.bpf.o | $(BPFTOOL)

	$(call msg,GEN-SKEL,$@)

	$(Q)$(BPFTOOL) gen skeleton -L $< > $@

$(OUTPUT)/entrypoints.bpf.o: entrypoints.bpf.c $(OUTPUT)/vmlinux.h $(BPFOBJ) | $(OUTPUT)

	$(call msg,BPF,$@)

	$(Q)$(CLANG) -g -O2 --target=bpf $(INCLUDES)			      \

		 -c $(filter %.c,$^) -o $@ &&				      \

	$(LLVM_STRIP) -g $@

$(OUTPUT)/vmlinux.h: $(VMLINUX_BTF) $(BPFTOOL) | $(INCLUDE_DIR)

ifeq ($(VMLINUX_H),)

	$(call msg,GEN,,$@)

	$(Q)$(BPFTOOL) btf dump file $(VMLINUX_BTF) format c > $@

else

	$(call msg,CP,,$@)

	$(Q)cp "$(VMLINUX_H)" $@

endif

$(OUTPUT) $(LIBBPF_OUTPUT) $(BPFTOOL_OUTPUT):

	$(call msg,MKDIR,$@)

	$(Q)mkdir -p $@

$(BPFOBJ): $(wildcard $(LIBBPF_SRC)/*.[ch] $(LIBBPF_SRC)/Makefile) | $(LIBBPF_OUTPUT)

	$(Q)$(MAKE) $(submake_extras) -C $(LIBBPF_SRC)			       \

		    OUTPUT=$(abspath $(dir $@))/ prefix=		       \

		    DESTDIR=$(LIBBPF_DESTDIR) $(abspath $@) install_headers

ifeq ($(CROSS_COMPILE),)

$(DEFAULT_BPFTOOL): $(BPFOBJ) | $(BPFTOOL_OUTPUT)

	$(Q)$(MAKE) $(submake_extras) -C $(BPFTOOL_SRC)			       \

		    OUTPUT=$(BPFTOOL_OUTPUT)/				       \

		    LIBBPF_BOOTSTRAP_OUTPUT=$(LIBBPF_OUTPUT)/		       \

		    LIBBPF_BOOTSTRAP_DESTDIR=$(LIBBPF_DESTDIR)/ bootstrap

else

$(DEFAULT_BPFTOOL): | $(BPFTOOL_OUTPUT)

	$(Q)$(MAKE) $(submake_extras) -C $(BPFTOOL_SRC)			       \

		    OUTPUT=$(BPFTOOL_OUTPUT)/ bootstrap

endif

WARNING:

If you change "entrypoints.bpf.c" do "make -j" in this directory to rebuild "entrypoints.skel.h".

Make sure to have clang 10 installed.

See Documentation/bpf/bpf_devel_QA.rst

// SPDX-License-Identifier: GPL-2.0

/* Copyright (c) 2022 Benjamin Tissoires */

#include ".output/vmlinux.h"

#include <bpf/bpf_helpers.h>

#include <bpf/bpf_tracing.h>

#define HID_BPF_MAX_PROGS 1024

struct {

	__uint(type, BPF_MAP_TYPE_PROG_ARRAY);

	__uint(max_entries, HID_BPF_MAX_PROGS);

	__uint(key_size, sizeof(__u32));

	__uint(value_size, sizeof(__u32));

} hid_jmp_table SEC(".maps");

SEC("fmod_ret/__hid_bpf_tail_call")

int BPF_PROG(hid_tail_call, struct hid_bpf_ctx *hctx)

{

	bpf_tail_call(ctx, &hid_jmp_table, hctx->index);

	return 0;

}

char LICENSE[] SEC("license") = "GPL";