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 v1 4/4] docs/bpf: Describe how to change a kfunc's prototype
Date: Tue, 17 Nov 2026 12:21:53 -0700 [thread overview]
Message-ID: <20261117192153.3384031-5-ihor.solodrai@linux.dev> (raw)
In-Reply-To: <20261117192153.3384031-1-ihor.solodrai@linux.dev>
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
next prev parent reply other threads:[~2026-11-17 19:22 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
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 ` [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 [this message]
2026-11-17 20:53 ` [PATCH bpf-next v1 0/4] libbpf: Support kernel-side kfunc flavors Tejun Heo
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=20261117192153.3384031-5-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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox