* [PATCH bpf-next v1 1/4] libbpf: Fall back to kernel ___ flavors when resolving kfuncs
2026-11-17 19:21 [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors Ihor Solodrai
@ 2026-11-17 19:21 ` Ihor Solodrai
2026-11-17 19:21 ` [PATCH bpf-next v1 2/4] selftests/bpf: Test kfunc flavor resolution Ihor Solodrai
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Ihor Solodrai @ 2026-11-17 19:21 UTC (permalink / raw)
To: Alexei Starovoitov, Andrii Nakryiko, Daniel Borkmann,
Eduard Zingerman, Kumar Kartikeya Dwivedi
Cc: Alan Maguire, Emil Tsalapatis, Jiri Olsa, Song Liu, Tejun Heo,
Yonghong Song, bpf, linux-kernel, sched-ext
When resolving a kfunc, libbpf strips the ___<flavor> suffix from its
name and binds the kfunc with the resulting name if its prototype is
compatible. So when a kfunc foo changes its prototype, the kernel can't
keep the old one available to existing BPF programs as foo___v1: they
declare foo, and libbpf never looks at foo___v1.
sched_ext worked around this by giving the new prototype the name
scx_bpf_dsq_insert___v2 and spelling it scx_bpf_dsq_insert___v2___compat
in BPF programs, so that the stripped name matches the kernel name
exactly. That leaks kernel naming into BPF programs, and calling the
kfunc as vmlinux.h declares it fails: scx_bpf_dsq_insert___v2 strips to
scx_bpf_dsq_insert, whose prototype is incompatible.
If the kfunc with the stripped name is missing or its prototype is
incompatible, look among the kfuncs named <name>___<flavor>, in vmlinux
first and then in the first module that has any, and bind the one whose
prototype is compatible. Only FUNCs with the bpf_kfunc decl tag are
candidates. More than one compatible flavor is an error even for a kfunc
declared __weak: ambiguity isn't absence.
The lookup of the stripped name comes first and is unchanged, so
bindings that work today stay the same.
Print the name of the chosen kfunc in the debug message.
Signed-off-by: Ihor Solodrai <ihor.solodrai@linux.dev>
---
tools/lib/bpf/btf.c | 26 ++++++
tools/lib/bpf/libbpf.c | 140 +++++++++++++++++++++++++++++++-
tools/lib/bpf/libbpf_internal.h | 1 +
3 files changed, 165 insertions(+), 2 deletions(-)
diff --git a/tools/lib/bpf/btf.c b/tools/lib/bpf/btf.c
index a4bf01403a43..9eb13c8a95a5 100644
--- a/tools/lib/bpf/btf.c
+++ b/tools/lib/bpf/btf.c
@@ -1164,6 +1164,32 @@ static __s32 btf_find_type_by_name_bsearch(const struct btf *btf, const char *na
return btf__type_cnt(btf);
}
+/*
+ * Set [*start, *end) to the IDs of btf's own types that can have a name
+ * starting with prefix. On BTF sorted by name these are exactly the ones that
+ * do, a contiguous run found by binary search; otherwise all own types.
+ */
+void btf_name_prefix_range(const struct btf *btf, const char *prefix, __u32 *start, __u32 *end)
+{
+ __u32 i, n = btf__type_cnt(btf);
+ size_t len = strlen(prefix);
+
+ if (btf->named_start_id <= 0) {
+ *start = btf->start_id;
+ *end = n;
+ return;
+ }
+ *start = btf_find_type_by_name_bsearch(btf, prefix, btf->named_start_id);
+ for (i = *start; i < n; i++) {
+ const struct btf_type *t = btf_type_by_id(btf, i);
+ const char *name = btf__str_by_offset(btf, t->name_off);
+
+ if (strncmp(name, prefix, len) != 0)
+ break;
+ }
+ *end = i;
+}
+
static __s32 btf_find_by_name_kind(const struct btf *btf, int start_id,
const char *type_name, __s32 kind)
{
diff --git a/tools/lib/bpf/libbpf.c b/tools/lib/bpf/libbpf.c
index 1efc0dd37b2e..9089e9c55dfd 100644
--- a/tools/lib/bpf/libbpf.c
+++ b/tools/lib/bpf/libbpf.c
@@ -9513,6 +9513,130 @@ static int bpf_object__resolve_ksym_var_btf_id(struct bpf_object *obj,
return 0;
}
+/* t is the bpf_kfunc decl tag of FUNC id */
+static inline bool btf_is_kfunc_tag(const struct btf *btf, const struct btf_type *t, int id)
+{
+ const char *name;
+
+ if (!btf_is_decl_tag(t) || t->type != id)
+ return false;
+ if (btf_decl_tag(t)->component_idx != -1)
+ return false;
+ name = btf__name_by_offset(btf, t->name_off);
+ return strcmp(name, "bpf_kfunc") == 0;
+}
+
+/* FUNC id has the bpf_kfunc decl tag */
+static bool btf_is_kfunc(const struct btf *btf, int id)
+{
+ __u32 i, n;
+
+ btf_name_prefix_range(btf, "bpf_kfunc", &i, &n);
+ for (; i < n; i++) {
+ if (btf_is_kfunc_tag(btf, btf__type_by_id(btf, i), id))
+ return true;
+ }
+ return false;
+}
+
+/* id is a kfunc named <name>___<flavor>, where len is strlen(name) */
+static bool btf_is_kfunc_flavor(const struct btf *btf, int id, const char *name, size_t len)
+{
+ const struct btf_type *t = btf__type_by_id(btf, id);
+ const char *kname;
+
+ if (!btf_is_func(t))
+ return false;
+ kname = btf__name_by_offset(btf, t->name_off);
+ if (strncmp(kname, name, len) != 0)
+ return false;
+ /* kname is <name> itself, already tried by the exact lookup */
+ if (kname[len] == '\0')
+ return false;
+ if (bpf_core_essential_name_len(kname) != len)
+ return false;
+ return btf_is_kfunc(btf, id);
+}
+
+/*
+ * Find the kfunc named <name>___<flavor> among btf's own types whose
+ * prototype is compatible with ext's.
+ *
+ * Returns the kfunc's type id, 0 if no flavor is compatible, -ESRCH if there
+ * are no flavors, or -ENOTUNIQ if more than one is compatible.
+ */
+static int find_kfunc_flavor(const struct bpf_object *obj, const struct extern_desc *ext,
+ const struct btf *btf)
+{
+ const char *name = ext->essent_name ?: ext->name;
+ size_t len = strlen(name);
+ bool has_flavors = false;
+ int found = 0;
+ __u32 i, n;
+
+ btf_name_prefix_range(btf, name, &i, &n);
+ for (; i < n; i++) {
+ const struct btf_type *t = btf__type_by_id(btf, i);
+
+ if (!btf_is_kfunc_flavor(btf, i, name, len))
+ continue;
+ has_flavors = true;
+ if (bpf_core_types_are_compat(obj->btf, ext->ksym.type_id, btf, t->type) <= 0)
+ continue;
+ if (found)
+ return -ENOTUNIQ;
+ found = i;
+ }
+ if (!has_flavors)
+ return -ESRCH;
+ return found;
+}
+
+/*
+ * Like find_ksym_btf_id(), but for a ___flavor of ext's kfunc: vmlinux first,
+ * then the first module that has any. *res_btf and *res_mod_btf are only set
+ * when a compatible flavor is found.
+ */
+static int find_kfunc_flavor_btf_id(struct bpf_object *obj, const struct extern_desc *ext,
+ struct btf **res_btf, struct module_btf **res_mod_btf)
+{
+ struct module_btf *mod_btf = NULL;
+ struct btf *btf = obj->btf_vmlinux;
+ int i, id, err;
+
+ id = find_kfunc_flavor(obj, ext, btf);
+ if (id == -ESRCH) {
+ err = load_module_btfs(obj);
+ if (err)
+ return err;
+
+ for (i = 0; i < obj->btf_module_cnt && id == -ESRCH; i++) {
+ mod_btf = &obj->btf_modules[i];
+ btf = mod_btf->btf;
+ id = find_kfunc_flavor(obj, ext, btf);
+ }
+ }
+ if (id > 0) {
+ *res_btf = btf;
+ *res_mod_btf = mod_btf;
+ }
+ return id;
+}
+
+/* ext's kfunc is missing, or kfunc_id's prototype is incompatible with ext's */
+static bool need_kfunc_flavor(const struct bpf_object *obj, const struct extern_desc *ext,
+ const struct btf *kern_btf, int kfunc_id)
+{
+ const struct btf_type *t;
+
+ if (kfunc_id == -ESRCH)
+ return true;
+ if (kfunc_id < 0)
+ return false;
+ t = btf__type_by_id(kern_btf, kfunc_id);
+ return bpf_core_types_are_compat(obj->btf, ext->ksym.type_id, kern_btf, t->type) <= 0;
+}
+
static int bpf_object__resolve_ksym_func_btf_id(struct bpf_object *obj,
struct extern_desc *ext)
{
@@ -9526,6 +9650,17 @@ static int bpf_object__resolve_ksym_func_btf_id(struct bpf_object *obj,
kfunc_id = find_ksym_btf_id(obj, ext->essent_name ?: ext->name, BTF_KIND_FUNC, &kern_btf,
&mod_btf);
+ if (need_kfunc_flavor(obj, ext, kern_btf, kfunc_id)) {
+ ret = find_kfunc_flavor_btf_id(obj, ext, &kern_btf, &mod_btf);
+ if (ret == -ENOTUNIQ) {
+ /* an error even if declared __weak: ambiguity isn't absence */
+ pr_warn("extern (func ksym) '%s': more than one compatible kfunc flavor\n",
+ ext->name);
+ return ret;
+ }
+ if (ret && ret != -ESRCH)
+ kfunc_id = ret;
+ }
if (kfunc_id < 0) {
if (kfunc_id == -ESRCH && ext->is_weak)
return 0;
@@ -9579,8 +9714,9 @@ static int bpf_object__resolve_ksym_func_btf_id(struct bpf_object *obj,
* {kernel_btf_id, kernel_btf_obj_fd} -> fixup ld_imm64.
*/
ext->ksym.kernel_btf_obj_fd = mod_btf ? mod_btf->fd : 0;
- pr_debug("extern (func ksym) '%s': resolved to %s [%d]\n",
- ext->name, mod_btf ? mod_btf->name : "vmlinux", kfunc_id);
+ pr_debug("extern (func ksym) '%s': resolved to %s '%s' [%d]\n",
+ ext->name, mod_btf ? mod_btf->name : "vmlinux",
+ btf__name_by_offset(kern_btf, kern_func->name_off), kfunc_id);
return 0;
}
diff --git a/tools/lib/bpf/libbpf_internal.h b/tools/lib/bpf/libbpf_internal.h
index e90b5336bac0..c84521ea562e 100644
--- a/tools/lib/bpf/libbpf_internal.h
+++ b/tools/lib/bpf/libbpf_internal.h
@@ -248,6 +248,7 @@ struct btf_type *btf_type_by_id(const struct btf *btf, __u32 type_id);
const char *btf_kind_str(const struct btf_type *t);
const struct btf_type *skip_mods_and_typedefs(const struct btf *btf, __u32 id, __u32 *res_id);
const struct btf_header *btf_header(const struct btf *btf);
+void btf_name_prefix_range(const struct btf *btf, const char *prefix, __u32 *start, __u32 *end);
void btf_set_base_btf(struct btf *btf, const struct btf *base_btf);
int btf_relocate(struct btf *btf, const struct btf *base_btf, __u32 **id_map,
__u32 **str_map);
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH bpf-next v1 2/4] selftests/bpf: Test kfunc flavor resolution
2026-11-17 19:21 [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors Ihor Solodrai
2026-11-17 19:21 ` [PATCH bpf-next v1 1/4] libbpf: Fall back to kernel ___ flavors when resolving kfuncs Ihor Solodrai
@ 2026-11-17 19:21 ` Ihor Solodrai
2026-11-17 19:21 ` [PATCH bpf-next v1 3/4] resolve_btfids: Reject kfunc families that libbpf can't disambiguate Ihor Solodrai
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Ihor Solodrai @ 2026-11-17 19:21 UTC (permalink / raw)
To: Alexei Starovoitov, Andrii Nakryiko, Daniel Borkmann,
Eduard Zingerman, Kumar Kartikeya Dwivedi
Cc: Alan Maguire, Emil Tsalapatis, Jiri Olsa, Song Liu, Tejun Heo,
Yonghong Song, bpf, linux-kernel, sched-ext
Add a kfunc family to bpf_testmod: bpf_kfunc_flavor() with the current
prototype, bpf_kfunc_flavor___v1() with an older one that takes one
fewer parameter, and bpf_kfunc_flavor___v2(), an alias with the exact
prototype of bpf_kfunc_flavor().
Check that libbpf binds:
- bpf_kfunc_flavor to the kfunc itself rather than to its alias ___v2;
- the old prototype to ___v1, both under a local flavor and under the
kernel name, as a header generated from BTF spells it;
- the kernel name with a local flavor on top to ___v1;
- a __weak kfunc that matches no member to nothing.
Signed-off-by: Ihor Solodrai <ihor.solodrai@linux.dev>
---
.../selftests/bpf/prog_tests/verifier.c | 3 +
.../selftests/bpf/progs/kfunc_flavors.c | 55 +++++++++++++++++++
.../selftests/bpf/test_kmods/bpf_testmod.c | 24 ++++++++
.../bpf/test_kmods/bpf_testmod_kfunc.h | 4 ++
4 files changed, 86 insertions(+)
create mode 100644 tools/testing/selftests/bpf/progs/kfunc_flavors.c
diff --git a/tools/testing/selftests/bpf/prog_tests/verifier.c b/tools/testing/selftests/bpf/prog_tests/verifier.c
index 57ff2578a991..351e53744e37 100644
--- a/tools/testing/selftests/bpf/prog_tests/verifier.c
+++ b/tools/testing/selftests/bpf/prog_tests/verifier.c
@@ -8,6 +8,7 @@
#include "cap_helpers.h"
#include "sysctl_helpers.h"
#include "cb_refs.skel.h"
+#include "kfunc_flavors.skel.h"
#include "verifier_aggregate_arg.skel.h"
#include "verifier_aggregate_ret.skel.h"
#include "verifier_alu_range.skel.h"
@@ -220,6 +221,8 @@ void test_arena_kfunc_jit(void) { RUN_TESTS(arena_kfunc_jit); }
void test_cb_refs(void) { RUN_TESTS(cb_refs); }
+void test_kfunc_flavors(void) { RUN_TESTS(kfunc_flavors); }
+
void test_verifier_aggregate_arg(void) { RUN_TESTS(verifier_aggregate_arg); }
void test_verifier_aggregate_ret(void) { RUN_TESTS(verifier_aggregate_ret); }
void test_verifier_alu_range(void) { RUN(verifier_alu_range); }
diff --git a/tools/testing/selftests/bpf/progs/kfunc_flavors.c b/tools/testing/selftests/bpf/progs/kfunc_flavors.c
new file mode 100644
index 000000000000..6b06cb8d8447
--- /dev/null
+++ b/tools/testing/selftests/bpf/progs/kfunc_flavors.c
@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: GPL-2.0
+/* Copyright (c) 2026 Meta Platforms, Inc. and affiliates. */
+
+#include <vmlinux.h>
+#include <bpf/bpf_helpers.h>
+#include "bpf_misc.h"
+#include "../test_kmods/bpf_testmod_kfunc.h"
+
+/* the old prototype of bpf_kfunc_flavor(), under local flavors */
+extern int bpf_kfunc_flavor___old(int a) __ksym;
+extern int bpf_kfunc_flavor___v1___local(int a) __ksym;
+/* a prototype that no member of the family has */
+extern int bpf_kfunc_flavor___none(void) __weak __ksym;
+
+char _license[] SEC("license") = "GPL";
+
+/* bpf_kfunc_flavor binds itself, though its alias ___v2 matches too */
+SEC("syscall")
+__retval(3)
+int exact_name(void *ctx)
+{
+ return bpf_kfunc_flavor(1, 2);
+}
+
+/* the old prototype under a local flavor binds ___v1 */
+SEC("syscall")
+__retval(1)
+int local_flavor(void *ctx)
+{
+ return bpf_kfunc_flavor___old(1);
+}
+
+/* so does the kernel name, which strips to bpf_kfunc_flavor */
+SEC("syscall")
+__retval(1)
+int kernel_flavor(void *ctx)
+{
+ return bpf_kfunc_flavor___v1(1);
+}
+
+/* a local flavor on top of the kernel name binds ___v1 by name */
+SEC("syscall")
+__retval(1)
+int stacked_flavor(void *ctx)
+{
+ return bpf_kfunc_flavor___v1___local(1);
+}
+
+/* a __weak kfunc that matches no member stays unresolved */
+SEC("syscall")
+__retval(0)
+int no_match(void *ctx)
+{
+ return bpf_ksym_exists(bpf_kfunc_flavor___none);
+}
diff --git a/tools/testing/selftests/bpf/test_kmods/bpf_testmod.c b/tools/testing/selftests/bpf/test_kmods/bpf_testmod.c
index 1f8bc0c99a71..e16559607270 100644
--- a/tools/testing/selftests/bpf/test_kmods/bpf_testmod.c
+++ b/tools/testing/selftests/bpf/test_kmods/bpf_testmod.c
@@ -1926,6 +1926,27 @@ __bpf_kfunc void bpf_kfunc_trigger_ctx_check(void)
irq_work_queue(&ctx_check_irq);
}
+/*
+ * A kfunc family for the kfunc_flavors test: bpf_kfunc_flavor() has the
+ * current prototype, ___v1 an older one, and ___v2 is an alias with its exact
+ * prototype. ___v2 negates the result, so that the test can tell which of the
+ * two it called.
+ */
+__bpf_kfunc int bpf_kfunc_flavor(int a, int b)
+{
+ return a + b;
+}
+
+__bpf_kfunc int bpf_kfunc_flavor___v1(int a)
+{
+ return bpf_kfunc_flavor(a, 0);
+}
+
+__bpf_kfunc int bpf_kfunc_flavor___v2(int a, int b)
+{
+ return -bpf_kfunc_flavor(a, b);
+}
+
BTF_KFUNCS_START(bpf_testmod_check_kfunc_ids)
BTF_ID_FLAGS(func, bpf_testmod_test_mod_kfunc, KF_SPINLOCK_SAFE)
BTF_ID_FLAGS(func, bpf_kfunc_call_test1)
@@ -2017,6 +2038,9 @@ BTF_ID_FLAGS(func, bpf_kfunc_implicit_arg, KF_IMPLICIT_ARGS)
BTF_ID_FLAGS(func, bpf_kfunc_implicit_arg_legacy, KF_IMPLICIT_ARGS)
BTF_ID_FLAGS(func, bpf_kfunc_implicit_arg_legacy_impl)
BTF_ID_FLAGS(func, bpf_kfunc_trigger_ctx_check)
+BTF_ID_FLAGS(func, bpf_kfunc_flavor)
+BTF_ID_FLAGS(func, bpf_kfunc_flavor___v1)
+BTF_ID_FLAGS(func, bpf_kfunc_flavor___v2)
BTF_KFUNCS_END(bpf_testmod_check_kfunc_ids)
static int bpf_testmod_ops_init(struct btf *btf)
diff --git a/tools/testing/selftests/bpf/test_kmods/bpf_testmod_kfunc.h b/tools/testing/selftests/bpf/test_kmods/bpf_testmod_kfunc.h
index 0a7df1798603..2c6126e4f0d0 100644
--- a/tools/testing/selftests/bpf/test_kmods/bpf_testmod_kfunc.h
+++ b/tools/testing/selftests/bpf/test_kmods/bpf_testmod_kfunc.h
@@ -381,4 +381,8 @@ void bpf_testmod_test_hardirq_fn(void);
void bpf_testmod_test_softirq_fn(void);
void bpf_kfunc_trigger_ctx_check(void) __ksym;
+int bpf_kfunc_flavor(int a, int b) __ksym;
+int bpf_kfunc_flavor___v1(int a) __ksym;
+int bpf_kfunc_flavor___v2(int a, int b) __ksym;
+
#endif /* _BPF_TESTMOD_KFUNC_H */
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH bpf-next v1 3/4] resolve_btfids: Reject kfunc families that libbpf can't disambiguate
2026-11-17 19:21 [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors Ihor Solodrai
2026-11-17 19:21 ` [PATCH bpf-next v1 1/4] libbpf: Fall back to kernel ___ flavors when resolving kfuncs Ihor Solodrai
2026-11-17 19:21 ` [PATCH bpf-next v1 2/4] selftests/bpf: Test kfunc flavor resolution Ihor Solodrai
@ 2026-11-17 19:21 ` Ihor Solodrai
2026-11-17 19:21 ` [PATCH bpf-next v1 4/4] docs/bpf: Describe how to change a kfunc's prototype Ihor Solodrai
2026-11-17 20:53 ` [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors Tejun Heo
4 siblings, 0 replies; 6+ messages in thread
From: Ihor Solodrai @ 2026-11-17 19:21 UTC (permalink / raw)
To: Alexei Starovoitov, Andrii Nakryiko, Daniel Borkmann,
Eduard Zingerman, Kumar Kartikeya Dwivedi
Cc: Alan Maguire, Emil Tsalapatis, Jiri Olsa, Song Liu, Tejun Heo,
Yonghong Song, bpf, linux-kernel, sched-ext
Kfuncs sharing an essential name, foo and foo___<flavor>, form a family.
When resolving a kfunc foo, libbpf binds the kernel's foo if the
prototypes are compatible, and otherwise the only family member whose
prototype passes bpf_core_types_are_compat() against the declaration.
That is only safe if no declaration can be compatible with two members
at once.
bpf_core_types_are_compat() compares prototypes kind by kind, so it
acts as an equivalence and a pairwise check is enough. Run it on every
pair of family members after dedup, using libbpf's own function, and
fail the build if any pair is compatible. A foo___<flavor> with the
same deduplicated FUNC_PROTO as foo is an alias and is allowed: libbpf
binds foo first, so the alias is never picked in its place. There is
only one foo: btf_check_kfunc_name() refuses to register a module kfunc
named like a function in vmlinux or in another module. Dedup compares
parameter names too, so an alias has to copy the signature verbatim.
Recognize family members by their bpf_kfunc decl tags rather than by
the BTF ID sets. The tags are what libbpf filters candidates on, and for
a module they also cover the vmlinux kfuncs in base BTF, so module
kfuncs get checked against vmlinux kfuncs of the same family.
The bpf_kfunc_flavor family in bpf_testmod passes: ___v1 differs in
arity and ___v2 is an alias.
Signed-off-by: Ihor Solodrai <ihor.solodrai@linux.dev>
---
tools/bpf/resolve_btfids/btf_colors.c | 11 +++
tools/bpf/resolve_btfids/btf_colors.h | 3 +
tools/bpf/resolve_btfids/main.c | 134 ++++++++++++++++++++++++++
3 files changed, 148 insertions(+)
diff --git a/tools/bpf/resolve_btfids/btf_colors.c b/tools/bpf/resolve_btfids/btf_colors.c
index 5d307d70e7f2..91c10106319e 100644
--- a/tools/bpf/resolve_btfids/btf_colors.c
+++ b/tools/bpf/resolve_btfids/btf_colors.c
@@ -13,6 +13,17 @@ void btf_sha256(const void *data, size_t len,
libbpf_sha256(data, len, out);
}
+size_t btf_essential_name_len(const char *name)
+{
+ return bpf_core_essential_name_len(name);
+}
+
+int btf_types_are_compat(const struct btf *btf1, __u32 id1,
+ const struct btf *btf2, __u32 id2)
+{
+ return bpf_core_types_are_compat(btf1, id1, btf2, id2);
+}
+
/*
* Marks `root_id` and local types reachable from it with `color`.
* `colors` is indexed by source ID; worklist has room for every local type.
diff --git a/tools/bpf/resolve_btfids/btf_colors.h b/tools/bpf/resolve_btfids/btf_colors.h
index 56a85a242d6b..3d48194e73b6 100644
--- a/tools/bpf/resolve_btfids/btf_colors.h
+++ b/tools/bpf/resolve_btfids/btf_colors.h
@@ -15,6 +15,9 @@ enum btf_color {
void btf_sha256(const void *data, size_t len,
__u8 out[BTF_SHA256_DIGEST_LENGTH]);
+size_t btf_essential_name_len(const char *name);
+int btf_types_are_compat(const struct btf *btf1, __u32 id1,
+ const struct btf *btf2, __u32 id2);
void btf_mark_reachable(struct btf *btf, __u32 root, enum btf_color color,
__u8 *colors, __u32 *worklist);
diff --git a/tools/bpf/resolve_btfids/main.c b/tools/bpf/resolve_btfids/main.c
index 0ac895222a14..68a5519cf8b6 100644
--- a/tools/bpf/resolve_btfids/main.c
+++ b/tools/bpf/resolve_btfids/main.c
@@ -1917,6 +1917,136 @@ static int sort_btf_by_name(struct btf *btf)
return err;
}
+static const char *func_name(const struct btf *btf, u32 id)
+{
+ return btf__name_by_offset(btf, btf__type_by_id(btf, id)->name_off);
+}
+
+static int cmp_essential_names(const void *a, const void *b, void *priv)
+{
+ const char *na = func_name(priv, *(u32 *)a);
+ const char *nb = func_name(priv, *(u32 *)b);
+ size_t la = btf_essential_name_len(na);
+ size_t lb = btf_essential_name_len(nb);
+ int r = strncmp(na, nb, min(la, lb));
+
+ if (r != 0)
+ return r;
+ if (la == lb)
+ return 0;
+ return la < lb ? -1 : 1;
+}
+
+/*
+ * Returns 1 if libbpf can't tell kfuncs a and b of one family apart, 0 if it
+ * can, or a negative error.
+ */
+static int kfuncs_are_ambiguous(const struct btf *btf, u32 a, u32 b, u32 unsuffixed_proto)
+{
+ const char *na = func_name(btf, a), *nb = func_name(btf, b);
+ u32 pa = btf__type_by_id(btf, a)->type;
+ u32 pb = btf__type_by_id(btf, b)->type;
+ int ret;
+
+ if (pa == pb && pa == unsuffixed_proto) {
+ pr_debug("kfuncs %s and %s: alias\n", na, nb);
+ return 0;
+ }
+ ret = btf_types_are_compat(btf, pa, btf, pb);
+ if (ret < 0) {
+ pr_err("ERROR: resolve_btfids: failed to compare kfuncs %s and %s: %d\n",
+ na, nb, ret);
+ return ret;
+ }
+ if (ret == 0)
+ pr_debug("kfuncs %s and %s: distinct\n", na, nb);
+ return ret;
+}
+
+static int check_kfunc_family(const struct btf *btf, const u32 *ids, u32 cnt, u32 start_id)
+{
+ size_t len = btf_essential_name_len(func_name(btf, ids[0]));
+ u32 unsuffixed_proto = 0;
+ int err, bad = 0;
+
+ for (u32 i = 0; i < cnt; i++) {
+ const char *name = func_name(btf, ids[i]);
+
+ if (name[len] == '\0')
+ unsuffixed_proto = btf__type_by_id(btf, ids[i])->type;
+ }
+
+ for (u32 i = 0; i < cnt; i++) {
+ for (u32 j = i + 1; j < cnt; j++) {
+ /* base BTF pairs were checked when building vmlinux */
+ if (ids[i] < start_id && ids[j] < start_id)
+ continue;
+ err = kfuncs_are_ambiguous(btf, ids[i], ids[j], unsuffixed_proto);
+ if (err < 0)
+ return err;
+ if (err == 0)
+ continue;
+ pr_err("ERROR: resolve_btfids: kfuncs %s and %s have compatible prototypes, libbpf cannot tell them apart\n",
+ func_name(btf, ids[i]), func_name(btf, ids[j]));
+ bad++;
+ }
+ }
+
+ return bad ? -EINVAL : 0;
+}
+
+/*
+ * Fail if libbpf can't tell apart two kfuncs sharing an essential name, i.e.
+ * if bpf_core_types_are_compat() finds their prototypes compatible. An alias
+ * of the unsuffixed kfunc, which has its type id after dedup, is allowed:
+ * libbpf binds the unsuffixed kfunc first.
+ *
+ * Kfuncs are recognized by their bpf_kfunc decl tags: these are what libbpf
+ * looks at, and for a module they also cover the vmlinux kfuncs in base BTF.
+ */
+static int check_kfunc_families(struct btf *btf)
+{
+ const struct btf *base = btf__base_btf(btf);
+ u32 start_id = base ? btf__type_cnt(base) : 1;
+ u32 type_cnt = btf__type_cnt(btf);
+ u32 *ids = NULL, nr_ids = 0, cap = 0;
+ int ret, err = 0;
+
+ for (u32 id = 1; id < type_cnt; id++) {
+ const struct btf_type *t = btf__type_by_id(btf, id);
+ const char *tag_name;
+
+ if (!btf_is_decl_tag(t))
+ continue;
+ if (btf_decl_tag(t)->component_idx != -1)
+ continue;
+ tag_name = btf__name_by_offset(btf, t->name_off);
+ if (strcmp(tag_name, DECL_TAG_KFUNC) != 0)
+ continue;
+ err = ensure_mem(&ids, &cap, nr_ids + 1);
+ if (err)
+ goto out;
+ ids[nr_ids++] = t->type;
+ }
+
+ qsort_r(ids, nr_ids, sizeof(*ids), cmp_essential_names, btf);
+
+ for (u32 i = 0, j; i < nr_ids; i = j) {
+ for (j = i + 1; j < nr_ids; j++) {
+ if (cmp_essential_names(&ids[i], &ids[j], btf) != 0)
+ break;
+ }
+ if (j - i < 2)
+ continue;
+ ret = check_kfunc_family(btf, ids + i, j - i, start_id);
+ if (ret)
+ err = ret;
+ }
+out:
+ free(ids);
+ return err;
+}
+
static int finalize_btf(struct object *obj)
{
struct btf *base_btf = obj->base_btf, *btf = obj->btf;
@@ -1928,6 +2058,10 @@ static int finalize_btf(struct object *obj)
return err;
}
+ err = check_kfunc_families(obj->btf);
+ if (err)
+ return err;
+
if (obj->base_btf && obj->distill_base) {
err = btf__distill_base(obj->btf, &base_btf, &btf);
if (err) {
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread* [PATCH bpf-next v1 4/4] docs/bpf: Describe how to change a kfunc's prototype
2026-11-17 19:21 [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors Ihor Solodrai
` (2 preceding siblings ...)
2026-11-17 19:21 ` [PATCH bpf-next v1 3/4] resolve_btfids: Reject kfunc families that libbpf can't disambiguate Ihor Solodrai
@ 2026-11-17 19:21 ` Ihor Solodrai
2026-11-17 20:53 ` [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors Tejun Heo
4 siblings, 0 replies; 6+ messages in thread
From: Ihor Solodrai @ 2026-11-17 19:21 UTC (permalink / raw)
To: Alexei Starovoitov, Andrii Nakryiko, Daniel Borkmann,
Eduard Zingerman, Kumar Kartikeya Dwivedi
Cc: Alan Maguire, Emil Tsalapatis, Jiri Olsa, Song Liu, Tejun Heo,
Yonghong Song, bpf, linux-kernel, sched-ext
Add a section on changing a kfunc's prototype to the kfunc lifecycle
expectations. libbpf now falls back to ___-suffixed kfuncs and
resolve_btfids rejects kfuncs that libbpf can't tell apart, so kernel
developers can keep BPF programs built against an old prototype
loading, provided they follow the rules this section describes.
Signed-off-by: Ihor Solodrai <ihor.solodrai@linux.dev>
---
Documentation/bpf/kfuncs.rst | 83 ++++++++++++++++++++++++++++++++++++
1 file changed, 83 insertions(+)
diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst
index c7da603cab77..17043ef15da3 100644
--- a/Documentation/bpf/kfuncs.rst
+++ b/Documentation/bpf/kfuncs.rst
@@ -800,6 +800,89 @@ procedure is followed for removal:
3. After the deprecation period the kfunc will be removed. At this point, BPF
programs calling the kfunc will be rejected by the verifier.
+3.2 Changing a kfunc's prototype
+--------------------------------
+
+libbpf binds a kfunc by name, ignoring any ``___suffix`` in the BPF program's
+declaration, if the declared prototype is compatible with the kernel's.
+Otherwise, it looks for a kfunc named ``<name>___<anything>`` with a compatible
+prototype.
+
+Prototypes are compatible if they have the same number of parameters and the
+same kind (integer, enum, pointer, struct, union, ...) of each parameter and of
+the return value. A pointer's kind includes the kind it points to: ``int *``
+and ``struct task_struct *`` differ, ``struct file *`` and
+``struct task_struct *`` don't. Integer sizes and signedness don't matter, nor
+do the names and members of structs, unions and enums. Typedefs, ``const`` and
+``volatile`` are looked through.
+
+A change that keeps the prototype compatible, e.g. widening an integer or adding
+``const``, is done in place. Otherwise the new prototype keeps the name, and the
+old one stays available as ``<name>___v1`` (``___v2`` for the next change, and
+so on) for a deprecation period, usually as a thin wrapper registered with the
+same flags:
+
+.. code-block:: c
+
+ __bpf_kfunc int bpf_foo(struct task_struct *p, u64 flags)
+ {
+ ...
+ }
+
+ /* bpf_foo() before flags was added */
+ __bpf_kfunc int bpf_foo___v1(struct task_struct *p)
+ {
+ return bpf_foo(p, 0);
+ }
+
+ BTF_ID_FLAGS(func, bpf_foo, KF_RCU)
+ BTF_ID_FLAGS(func, bpf_foo___v1, KF_RCU)
+
+BPF programs built against either prototype then load:
+
+.. code-block:: c
+
+ /* built against the old prototype: binds bpf_foo___v1 */
+ extern int bpf_foo(struct task_struct *p) __ksym;
+
+ /* built against the new prototype: binds bpf_foo */
+ extern int bpf_foo(struct task_struct *p, u64 flags) __ksym;
+
+Only libbpf 1.9 and later look for ``bpf_foo___v1``. Older libbpf and light
+skeletons see only ``bpf_foo``, as after an in-place change.
+
+Two kfuncs whose names differ only in the ``___`` suffix must not have
+compatible prototypes: libbpf couldn't tell them apart, and ``resolve_btfids``
+fails the build. The one exception is an alias of ``<name>``: a kfunc with the
+identical prototype, parameter names included (BTF dedup compares them).
+
+For example, this widens an offset to 64 bits and keeps the old prototype as
+``bpf_bar___v1``:
+
+.. code-block:: c
+
+ __bpf_kfunc int bpf_bar(const struct bpf_dynptr *p, u64 offset);
+
+ /* bpf_bar() before offset was widened */
+ __bpf_kfunc int bpf_bar___v1(const struct bpf_dynptr *p, u32 offset);
+
+``resolve_btfids`` rejects it::
+
+ ERROR: resolve_btfids: kfuncs bpf_bar and bpf_bar___v1 have compatible prototypes, libbpf cannot tell them apart
+
+Widening keeps the prototype compatible, so it is done in place instead: drop
+``bpf_bar___v1``, and programs built against the old prototype bind
+``bpf_bar``.
+
+Give the new prototype a new name that doesn't start with ``<name>___`` if
+programs loaded by older libbpf or light skeletons must keep working, or if the
+prototypes are compatible but the change breaks callers, e.g. two integer
+parameters swap places.
+
+Don't rename a ``<name>___vN`` kfunc in place: BPF programs may call it by that
+name. To give its prototype to ``<name>``, keep it as an alias for a
+deprecation period.
+
4. Core kfuncs
==============
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors
2026-11-17 19:21 [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors Ihor Solodrai
` (3 preceding siblings ...)
2026-11-17 19:21 ` [PATCH bpf-next v1 4/4] docs/bpf: Describe how to change a kfunc's prototype Ihor Solodrai
@ 2026-11-17 20:53 ` Tejun Heo
4 siblings, 0 replies; 6+ messages in thread
From: Tejun Heo @ 2026-11-17 20:53 UTC (permalink / raw)
To: Ihor Solodrai
Cc: Alexei Starovoitov, Andrii Nakryiko, Daniel Borkmann,
Eduard Zingerman, Kumar Kartikeya Dwivedi, Alan Maguire,
Emil Tsalapatis, Jiri Olsa, Song Liu, Yonghong Song, bpf,
linux-kernel, sched-ext
Hello, Ihor.
Thanks for working on this. This would make compat support a lot easier
and more robust for sched_ext.
Thanks.
--
tejun
^ permalink raw reply [flat|nested] 6+ messages in thread