[PATCH bpf-next v2 0/6] libbpf: Support kernel-side kfunc variants

From: Ihor Solodrai

Date: Fri Nov 20 2026 - 19:34:22 EST


A kfunc prototype change breaks BPF programs built against the old
prototype. For example, 8fe4dc4f6456 ("bpf: change prototype of
bpf_session_{cookie,is_return}") made this change in v7.0:

before: bool bpf_session_is_return(void);
v7.0: bool bpf_session_is_return(void *ctx);

A program built before v7.0 declares bpf_session_is_return(void), and
libbpf can't resolve it on v7.0. The kernel has no way to keep the old
prototype available to such programs. sched_ext works around the same
problem with ___v2___compat names in compat.bpf.h.

With this series, the kernel can keep the old prototype as a variant:

bool bpf_session_is_return(void *ctx);
bool bpf_session_is_return___v1(void);

and libbpf binds each declaration to the function with a matching BTF
prototype.

The new lookup changes what some existing declarations resolve to.

A replay of kfunc resolution against v6.18, v7.2 and bpf-next BTF
covered 1302 BPF objects: 1174 sched_ext schedulers from Meta's
internal builds, and 128 public objects from the scx repo,
tools/sched_ext, the selftests and bpftrace. It also covered 16
objects declaring every kfunc from each x86 vmlinux.h in the scx
repo's history, counted here as public. No strong declaration
changes. These __weak declarations change, counted in objects per
kernel:
public Meta
lost on v7.2 and bpf-next, no candidate:
scx_bpf_dsq_insert___v2___compat 36 136
scx_bpf_dsq_move_to_local___v2___compat 33 27
scx_bpf_reenqueue_local___v2___compat 9 44

lost on v7.2 and bpf-next, struct names differ:
bpf_io_uring_get_region(struct io_ring_ctx *) 1 0
bpf_io_uring_submit_sqes(struct io_ring_ctx *) 1 0

lost on bpf-next, struct names differ:
bpf_cpumask_populate(struct cpumask *) 8 88

lost on v6.18 and v7.2, struct names differ:
bpf_cpumask_populate(struct bpf_cpumask *) 4 0

gained on v7.2 and bpf-next:
scx_bpf_dsq_move_to_local___v2(u64, u64) 7 120
scx_bpf_dsq_insert___v2(...) 8 0
scx_bpf_reenqueue_local___v2(void) 8 0

In-tree compat.bpf.h now tries the plain ___v2 names first. Objects
that gain a ___v2 kfunc now call it instead of their fallback path.

---

v1->v2:
* Pick a kfunc by prototype among all funcs with the same essential
name, without preferring the exact name (Andrii, Eduard).
* Compare struct and union names, ignoring ___ suffixes, instead of
using bpf_core_types_are_compat(), so that variants can differ
only in a pointee type (Eduard, Andrii).
* Drop the alias exception that kept ___v2___compat names working
(Eduard). New patch 2 updates compat.bpf.h instead.
* resolve_btfids: check registered kfuncs within vmlinux or a module
with libbpf's new matcher and report every matching pair. New
patch #1 shares libbpf internals with it instead of wrapping them
(Eduard).
* Call kernel-side ___ functions "variants". "Flavor" stays CO-RE's
term for local suffixes.
* Rewrite the docs for the new rules.

v1: https://lore.kernel.org/bpf/20261117192153.3384031-1-ihor.solodrai@xxxxxxxxx/

---

Ihor Solodrai (6):
libbpf: Separate interfaces shared with in-tree tools
sched_ext: Prefer ___v2 kfunc names in compat.bpf.h
libbpf: Resolve kfunc variants by prototype
selftests/bpf: Test kfunc variant selection by prototype
resolve_btfids: Reject ambiguous kfunc variants
docs/bpf: Describe how to change a kfunc's prototype

Documentation/bpf/kfuncs.rst | 96 ++++++++++++++
tools/bpf/bpftool/Makefile | 9 +-
tools/bpf/resolve_btfids/btf_colors.c | 15 +--
tools/bpf/resolve_btfids/btf_colors.h | 4 -
tools/bpf/resolve_btfids/main.c | 74 ++++++++++-
tools/lib/bpf/btf.c | 99 ++++++++++++++-
tools/lib/bpf/libbpf.c | 117 ++++++++++++------
tools/lib/bpf/libbpf_internal.h | 32 +----
tools/lib/bpf/libbpf_tools.h | 48 +++++++
tools/sched_ext/include/scx/compat.bpf.h | 39 ++++--
.../selftests/bpf/prog_tests/verifier.c | 3 +
.../selftests/bpf/progs/kfunc_variants.c | 32 +++++
.../selftests/bpf/test_kmods/bpf_testmod.c | 12 ++
.../bpf/test_kmods/bpf_testmod_kfunc.h | 3 +
14 files changed, 481 insertions(+), 102 deletions(-)
create mode 100644 tools/lib/bpf/libbpf_tools.h
create mode 100644 tools/testing/selftests/bpf/progs/kfunc_variants.c


base-commit: 82cc2b4383e3edfa1026c8612fb4e90a9329ba11
--
2.56.1