Skip to content

Program type BPF_PROG_TYPE_SYSCALL

v5.14

Syscall programs can be used to execute syscalls from eBPF.

Usage

The abstract purpose of the syscall program type is to execute syscalls from eBPF. The initial use case for this program type was to offload some of the work of loader libraries to syscall eBPF programs. The program type can also be used by for "HID-BPF" to register a BPF program as a HID device driver.

Loading with light skeletons

This use case revolves around using a BPF_PROG_TYPE_SYSCALL program to load one or more eBPF programs. The reason behind this is two-fold. First, with a bit of automation in the form of generation tools, loading a program can be made easier. Second, this new structure would make it easier to implement a form of code signing for eBPF programs. However, the code signing use case so far has not been successful.

The way this works is that you write and compile your primary eBPF program as normal. You then feed it to bpftool with the gen skeleton -L {prog}.o > {prog}.skel.h command. This will generate a "light skeleton" for the program. Essentially a header file which can be included by a custom userspace program as dependency. It exposes pre-defined function to then load the eBPF program. The header file embeds the essential parts of the primary ELF file and a generated BPF_PROG_TYPE_SYSCALL program. Parts of the primary program such as its instructions, map definitions, and initial keys/values are part of the generated program or provided as data via existing mechanisms. The syscall program then uses a series of bpf_sys_bpf helper calls to load the primary program just like a loader would normally do from userspace.

HID-BPF

The use case of HID-BPF is to implement HID device drivers in eBPF, at least partially. This allows HID drivers implemented this way for new devices to work on older kernels without the need for a kernel module.

No special program type was created for this use case, rather the FMOD_RET tracing program type is repurposed. However, normally these attach to a single instance of a kernel function. For the HID-BPF use case, we want to attach to a specific HID device. This is done by using the hid_bpf_attach_prog kfunc to attach the program to the HID device. Which bring us to the BPF_PROG_TYPE_SYSCALL program which is used to actually execute this kfunc.

Context

This program type does not have a set context type, so as long as your eBPF program and userspace are aligned, you can use any context type you want.

Attachment

Syscall programs are never attached to any hook. They can only be executed from the BPF_PROG_RUN syscall command.

Example

BPF-HID

// SPDX-License-Identifier: GPL-2.0-only
/* Copyright (c) 2022 Benjamin Tissoires
*/

#include "vmlinux.h"
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_tracing.h>
#include "hid_bpf_helpers.h"

struct attach_prog_args {
    int prog_fd;
    unsigned int hid;
    int retval;
};

SEC("syscall")
int attach_prog(struct attach_prog_args *ctx)
{
    ctx->retval = hid_bpf_attach_prog(ctx->hid,
                    ctx->prog_fd,
                    0);
    return 0;
}

Helper functions

Not all helper functions are available in all program types. These are the helper calls available for syscall programs:

Supported helper functions

KFuncs

Supported kfuncs