[PATCH bpf-next v2 6/6] docs/bpf: Describe how to change a kfunc's prototype

From: Ihor Solodrai

Date: Fri Nov 20 2026 - 19:35:23 EST


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@xxxxxxxxx>
---
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