Re: [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors

From: Ihor Solodrai

Date: Thu Nov 19 2026 - 22:32:48 EST




On 11/17/26 12:21 PM, Ihor Solodrai wrote:
> An incompatible change to a kfunc's prototype, such as an added
> parameter, breaks BPF programs built against the old one. libbpf
> ignores the ___<flavor> suffix of a kfunc declared in a BPF program,
> but makes an exact name look up on the kernel side, so the kernel
> can't keep the old prototype available under the kfunc's name.
>
> sched_ext ran into this. cded46d97159 ("sched_ext: Make
> scx_bpf_dsq_insert*() return bool") kept the old prototype as
> scx_bpf_dsq_insert___compat, expecting libbpf to bind old binaries to
> it, and broke them. 2dbbdeda77a6 ("sched_ext: Fix scx_bpf_dsq_insert()
> backward binary compatibility") reversed the naming. A ___v2 kfunc
> declared as vmlinux.h spells it doesn't bind: 56bbc91219c0
> ("sched_ext: Fix scx_bpf_dsq_move_to_local___v2 compat detection")
> fixed a compat macro that silently dropped enq_flags because of this.
>
> With this series, if the kernel's bpf_foo kfunc is missing or its
> prototype is incompatible with the declaration, libbpf binds the
> bpf_foo___<flavor> that has a compatible prototype. So a changed kfunc
> can keep its name, and the old prototype stays available as foo___v1.
>
> resolve_btfids fails the build if two of bpf_foo and its flavors have
> compatible prototypes, unless both have foo's exact prototype
> (aliases), so the fallback finds at most one match. This ensures at
> kernel / module build time that no ambigous kfunc flavors exist.
> Documentation/bpf/kfuncs.rst describes the rules.
>
> Compatibility is determined by bpf_core_types_are_compat(), the check
> libbpf already applies to kfuncs. Of the 70 same-name kfunc prototype
> changes between v6.6 and bpf-next, it finds 8 incompatible (arity,
> return kind, callback prototype). The other 62 (const, typedefs,
> parameter names, integer widths, pointee struct names, annotation
> suffixes) were made in place without breaking old callers.
>
> The flavors feature is backwards compatible: declarations that resolve
> today bind the same kernel function. The exact name lookup is
> attempted first. Declarations rejected today for an incompatible
> prototype, or left unresolved if __weak, may now bind to a flavor, for
> example scx_bpf_dsq_insert___v2 as vmlinux.h declares it. Older libbpf
> and light skeletons don't get the fallback.

We had an off-list discussion with Eduard and Andrii today. We agreed
on the implementation as described below, which I plan to submit as v2
of this series (soon).

Writing from memory, please correct me if I forgot or misremembered
anything.

A single kfunc selection mechanism in libbpf:

1. Find all functions in kernel BTF with the essential name (the
name before the first ___ separator) that matches target kfunc's
essential name. "bpf_kfunc" decl tag is ignored.
This gives a candidate list.

2. From the candidate list, find the one with a compatible
prototype. Error on ambiguity.

No exceptions for "exact name" match (as in v1) or anything like that.

A function prototype compatibility check here will be a little
stricter than bpf_core_types_are_compat(). But it's also not going to
be a type traversal as done by bpf_core_types_match(). It will be a
new check specifically for func prototype comparison.

In particular, for pointers to structs, unions or typedefs *the name*
of the type will also be checked. And the typedefs won't "skipped"
anymore, but shallowly compared. For example:

void kfunc(struct foo *arg);
vs
void kfunc(struct bar *arg);

become incompatible now. And

typedef struct foo {...} foo_t;
void kfunc(foo_t *arg);
vs
void kfunc(struct foo *arg);

become incompatible now.

However:

typedef struct foo_v1 {...} foo_t;
void kfunc(foo_t *arg);
vs
typedef struct foo_v2 {...} foo_t;
void kfunc(foo_t *arg);

are compatible, because the name "foo_t" matches.

resolve_btfids built-time "no ambiguity" enforcement remains.

The consequence of this approach is that a BPF program expecting a
kfunc that changed its prototype in the past in a CO-RE compatible
way, will now get an error if loaded with new libbpf. The fix is
simple: use an up-to-date kfunc prototype in the BPF program.

A notable recent example is bpf_cpumask_populate() change [1].

[1] https://lore.kernel.org/bpf/20260709182800.2037938-2-main.kalliope@xxxxxxxxx/


>
> [...]