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 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.