Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <20220318161528.1531164-1-benjamin.tissoires@redhat.com> <20220318161528.1531164-18-benjamin.tissoires@redhat.com>
In-Reply-To: <20220318161528.1531164-18-benjamin.tissoires@redhat.com>
From:   Song Liu <song@kernel.org>
Date:   Fri, 18 Mar 2022 11:05:37 -0700
Message-ID: <CAPhsuW77u64mxxLxp3B99cvu8NbqgNv1oW5Ffv0yn-k=YBw6GQ@mail.gmail.com>
Subject: Re: [PATCH bpf-next v3 17/17] Documentation: add HID-BPF docs
To:     Benjamin Tissoires <benjamin.tissoires@redhat.com>
Cc:     Greg KH <gregkh@linuxfoundation.org>,
        Jiri Kosina <jikos@kernel.org>,
        Alexei Starovoitov <ast@kernel.org>,
        Daniel Borkmann <daniel@iogearbox.net>,
        Andrii Nakryiko <andrii@kernel.org>,
        Martin KaFai Lau <kafai@fb.com>,
        Song Liu <songliubraving@fb.com>, Yonghong Song <yhs@fb.com>,
        John Fastabend <john.fastabend@gmail.com>,
        KP Singh <kpsingh@kernel.org>, Shuah Khan <shuah@kernel.org>,
        Dave Marchevsky <davemarchevsky@fb.com>,
        Joe Stringer <joe@cilium.io>, Jonathan Corbet <corbet@lwn.net>,
        Tero Kristo <tero.kristo@linux.intel.com>,
        open list <linux-kernel@vger.kernel.org>,
        "open list:HID CORE LAYER" <linux-input@vger.kernel.org>,
        Networking <netdev@vger.kernel.org>, bpf <bpf@vger.kernel.org>,
        linux-kselftest@vger.kernel.org,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

On Fri, Mar 18, 2022 at 9:22 AM Benjamin Tissoires
<benjamin.tissoires@redhat.com> wrote:
>
> Gives a primer on HID-BPF.
>
> Signed-off-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>
>
> ---
>
> new in v3
> ---
>  Documentation/hid/hid-bpf.rst | 444 ++++++++++++++++++++++++++++++++++
>  Documentation/hid/index.rst   |   1 +
>  include/uapi/linux/bpf_hid.h  |  54 ++++-
>  3 files changed, 492 insertions(+), 7 deletions(-)
>  create mode 100644 Documentation/hid/hid-bpf.rst
>
> diff --git a/Documentation/hid/hid-bpf.rst b/Documentation/hid/hid-bpf.rst
> new file mode 100644
> index 000000000000..0bf0d937b0e1
> --- /dev/null
> +++ b/Documentation/hid/hid-bpf.rst
> @@ -0,0 +1,444 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +=======
> +HID-BPF
> +=======
> +
> +HID is a standard protocol for input devices and it can greatly make use
> +of the eBPF capabilities to speed up development and add new capabilities
> +to the existing HID interfaces.
> +
> +.. contents::
> +    :local:
> +    :depth: 2
> +
> +
> +When (and why) using HID-BPF
> +============================
> +
> +We can enumerate several use cases for when using HID-BPF is better than
> +using a standard kernel driver fix.
> +
> +dead zone of a joystick
> +-----------------------
> +
> +Assuming you have a joystick that is getting older, it is common to see it
> +wobbling around its neutral point. This is usually filtered at the application
> +level by adding a *dead zone* for this specific axis.
> +
> +With HID-BPF, we can put the filtering of this dead zone in the kernel directly
> +so we don't wake up userspace when nothing else is happening on the input
> +controller.
> +
> +Of course, given that this dead zone is device specific, we can not create a

nit: s/can not/cannot

There are a few more "can not" below.

[...]

> +firewall
> +--------
> +
> +What if we want to prevent other users to access a specific feature of a
> +device? (think a possibly bonker firmware update entry popint)
nit: point

> +
> +With eBPF, we can intercept any HID command emitted to the device and
> +validate it or not.
> +
> +This also allows to sync the state between the userspace and the
> +kernel/bpf program because we can intercept any incoming command.
> +
[...]

> +
> +The main idea behind HID-BPF is that it works at an array of bytes level.
> +Thus, all of the parsing of the HID report and the HID report descriptor
> +must be implemented in the userspace component that loads the eBPF
> +program.
> +
> +For example, in the dead zone joystick from above, knowing which fields
> +in the data stream needs to be set to ``0`` needs to be computed by userspace.
> +
> +A corrolar of this is that HID-BPF doesn't know about the other subsystems

nit: corollary?

> +available in the kernel. *You can not directly emit input event through the
> +input API from eBPF*.
> +
> +When a BPF program need to emit input events, it needs to talk HID, and rely
> +on the HID kernel processing to translate the HID data into input events.
> +
> +Available types of programs
> +===========================
[...]
> +
> +``BPF_HID_RDESC_FIXUP``
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Last, the ``BPF_HID_RDESC_FIXUP`` program works in the similar maneer than
nit: manner.

> +``.report_fixup`` of ``struct hid_driver``.
> +

[...]