From: Ihor Solodrai <ihor.solodrai@linux.dev>
To: Alexei Starovoitov <ast@kernel.org>,
Andrii Nakryiko <andrii@kernel.org>,
Daniel Borkmann <daniel@iogearbox.net>,
Eduard Zingerman <eddyz87@gmail.com>,
Kumar Kartikeya Dwivedi <memxor@gmail.com>
Cc: Alan Maguire <alan.maguire@oracle.com>,
Emil Tsalapatis <emil@etsalapatis.com>,
Jiri Olsa <jolsa@kernel.org>, Song Liu <song@kernel.org>,
Tejun Heo <tj@kernel.org>,
Yonghong Song <yonghong.song@linux.dev>,
bpf@vger.kernel.org, linux-kernel@vger.kernel.org,
sched-ext@lists.linux.dev
Subject: [PATCH bpf-next v2 6/6] docs/bpf: Describe how to change a kfunc's prototype
Date: Fri, 20 Nov 2026 17:34:03 -0700 [thread overview]
Message-ID: <20261121003403.2928928-7-ihor.solodrai@linux.dev> (raw)
In-Reply-To: <20261121003403.2928928-1-ihor.solodrai@linux.dev>
Add a section on changing a kfunc's prototype to the kfunc lifecycle
expectations. libbpf now binds a ___-suffixed kfunc by prototype 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 | 96 ++++++++++++++++++++++++++++++++++++
1 file changed, 96 insertions(+)
diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst
index c7da603cab77..4d60a13ecbe3 100644
--- a/Documentation/bpf/kfuncs.rst
+++ b/Documentation/bpf/kfuncs.rst
@@ -800,6 +800,102 @@ 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 drops the last ``___suffix`` from the name of a kfunc declared in a BPF
+program and from the names of functions in kernel and module BTF, as it does
+for CO-RE type names. Among the functions with the same remaining name, it
+binds the one with a prototype that matches the declaration. Types are
+compared kind by kind, and structs and unions by name only:
+
+.. code-block:: c
+
+ typedef struct task_struct task_t;
+
+ /* these match */
+ int bpf_foo(struct task_struct *p, u32 flags);
+ int bpf_foo(const task_t *p, u64 flags);
+ int bpf_foo(struct task_struct___local *p, int flags);
+
+ /* none of these match the ones above */
+ int bpf_foo(struct file *p, u32 flags);
+ int bpf_foo(struct task_struct *p);
+ void bpf_foo(struct task_struct *p, u32 flags);
+
+If the old and new prototypes match, change the kfunc 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;
+
+ /* the suffix doesn't select a kfunc: both bind bpf_foo___v1 */
+ extern int bpf_foo___v1(struct task_struct *p) __ksym;
+ extern int bpf_foo___local(struct task_struct *p) __ksym;
+
+ /* a stacked suffix binds nothing */
+ extern int bpf_foo___v1___local(struct task_struct *p) __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.
+
+If two kfunc names differ only in the ``___`` suffix, their prototypes must not
+match, not even for aliases: libbpf can't tell them apart and fails to load a
+program that declares either one, even as ``__weak``. 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 matching prototypes
+
+Widening keeps the prototype matching, so it is done in place instead: drop
+``bpf_bar___v1``, and programs built against the old prototype bind
+``bpf_bar``. ``resolve_btfids`` checks registered kfuncs within vmlinux or one
+module. libbpf catches other matches, such as between two modules, when loading
+the program.
+
+Give the new prototype a name outside the family, not ``<name>___*``, if:
+
+- programs loaded by older libbpf or light skeletons must keep working, or
+- the prototypes match but the change breaks callers, e.g. two integer
+ parameters swap places.
+
+Don't rename a ``<name>___vN`` kfunc while older libbpf or light skeletons
+still load programs that call it by that name. libbpf 1.9 and later bind by
+prototype, so a rename doesn't affect them.
+
4. Core kfuncs
==============
--
2.56.1
prev parent reply other threads:[~2026-11-21 0:34 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-21 0:33 [PATCH bpf-next v2 0/6] libbpf: Support kernel-side kfunc variants Ihor Solodrai
2026-11-21 0:33 ` [PATCH bpf-next v2 1/6] libbpf: Separate interfaces shared with in-tree tools Ihor Solodrai
2026-11-21 0:33 ` [PATCH bpf-next v2 2/6] sched_ext: Prefer ___v2 kfunc names in compat.bpf.h Ihor Solodrai
2026-11-21 0:34 ` [PATCH bpf-next v2 3/6] libbpf: Resolve kfunc variants by prototype Ihor Solodrai
2026-11-21 0:34 ` [PATCH bpf-next v2 4/6] selftests/bpf: Test kfunc variant selection " Ihor Solodrai
2026-11-21 0:34 ` [PATCH bpf-next v2 5/6] resolve_btfids: Reject ambiguous kfunc variants Ihor Solodrai
2026-11-21 0:34 ` Ihor Solodrai [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261121003403.2928928-7-ihor.solodrai@linux.dev \
--to=ihor.solodrai@linux.dev \
--cc=alan.maguire@oracle.com \
--cc=andrii@kernel.org \
--cc=ast@kernel.org \
--cc=bpf@vger.kernel.org \
--cc=daniel@iogearbox.net \
--cc=eddyz87@gmail.com \
--cc=emil@etsalapatis.com \
--cc=jolsa@kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=memxor@gmail.com \
--cc=sched-ext@lists.linux.dev \
--cc=song@kernel.org \
--cc=tj@kernel.org \
--cc=yonghong.song@linux.dev \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.