Skip to contentSkip to conversation

Documentation/bpf: make it clear that kfuncs should be non-static

PATCH In review JP Kobryn 6 participants 6 messages Jun 26 – Jul 1

Subsystems (2)
lore
Share & tools
lore

JP Kobryn

author
#0 lore raw

PATCH 1/1 Documentation/bpf: make it clear that kfuncs should be non-static

The kfunc documentation mentions how the macro __bpf_kfunc prevents inlining for static functions. This makes it sound like static kfuncs are acceptable. Although static kfuncs may happen to work, it is by chance that the compiler chose not to rename these functions and BTF resolution still succeeds.

Make it clear in the documentation why kfuncs should not be declared static. First, remove wording that makes it sound like static is ok. Then point out the external naming needed for BTF resolution. Finally point out that sparse may warn on unreferenced kfuncs and that this warning can be ignored.

---
 Documentation/bpf/kfuncs.rst | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
Documentation/bpf/kfuncs.rst +14 -7
index 4c814ff6061e..1dbaff8d4805 100644
@@ -276,19 +276,26 @@ This set encodes the BTF ID of each kfunc listed above, and encodes the flags
 along with it. Ofcourse, it is also allowed to specify no flags.
 
 kfunc definitions should also always be annotated with the ``__bpf_kfunc``
-macro. This prevents issues such as the compiler inlining the kfunc if it's a
-static kernel function, or the function being elided in an LTO build as it's
-not used in the rest of the kernel. Developers should not manually add
-annotations to their kfunc to prevent these issues. If an annotation is
-required to prevent such an issue with your kfunc, it is a bug and should be
-added to the definition of the macro so that other kfuncs are similarly
-protected. An example is given below::
+macro. This prevents issues such as the compiler inlining the kfunc, or the
+function being elided in an LTO build as it's not used in the rest of the
+kernel. Developers should not manually add annotations to their kfunc to prevent
+these issues. If an annotation is required to prevent such an issue with your
+kfunc, it is a bug and should be added to the definition of the macro so that
+other kfuncs are similarly protected. An example is given below::
 
         __bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid)
         {
         ...
         }
 
+Note that kfuncs must not be declared ``static``. A kfunc can be called from a
+BPF program ``*.c`` file outside the compilation unit that defines it, so its
+externally visible name must remain available for BTF ID lookup. ``static``
+linkage allows the compiler to rename the function, which can break this
+BTF-based kfunc resolution. Further note that sparse may warn that an otherwise
+unreferenced kfunc should be static. Such warnings should be ignored for kfunc
+definitions.
+
 2.5.1 KF_ACQUIRE flag
 ---------------------
 
Signature · 1 line
2.54.0
reviewer
#1 lore raw
Quoted 22 lines · JP Kobryn

The kfunc documentation mentions how the macro __bpf_kfunc prevents inlining for static functions. This makes it sound like static kfuncs are acceptable. Although static kfuncs may happen to work, it is by chance that the compiler chose not to rename these functions and BTF resolution still succeeds.

Make it clear in the documentation why kfuncs should not be declared static. First, remove wording that makes it sound like static is ok. Then point out the external naming needed for BTF resolution. Finally point out that sparse may warn on unreferenced kfuncs and that this warning can be ignored.

---
 Documentation/bpf/kfuncs.rst | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
Documentation/bpf/kfuncs.rst +0 -0
index 4c814ff6061e..1dbaff8d4805 100644

Documentation/bpf/kfuncs.rst This set encodes the BTF ID of each kfunc listed above, and encodes the flags · line 277

Quoted 2 lines
Documentation/bpf/kfuncs.rst +0 -0
@@ -276,19 +276,26 @@ This set encodes the BTF ID of each kfunc listed above, and encodes the flags
 along with it. Ofcourse, it is also allowed to specify no flags.
 

Not part of this patch, but "Ofcourse," should be "Of course," of course.

Signature · 1 line
~Randy
Acked-by on v1 1/1
#2 lore raw
In reply to JP Kobryn
Quoted 44 lines · JP Kobryn

The kfunc documentation mentions how the macro __bpf_kfunc prevents inlining for static functions. This makes it sound like static kfuncs are acceptable. Although static kfuncs may happen to work, it is by chance that the compiler chose not to rename these functions and BTF resolution still succeeds.

Make it clear in the documentation why kfuncs should not be declared static. First, remove wording that makes it sound like static is ok. Then point out the external naming needed for BTF resolution. Finally point out that sparse may warn on unreferenced kfuncs and that this warning can be ignored.

---
 Documentation/bpf/kfuncs.rst | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
Documentation/bpf/kfuncs.rst +6 -7
index 4c814ff6061e..1dbaff8d4805 100644
@@ -276,19 +276,26 @@ This set encodes the BTF ID of each kfunc listed above, and encodes the flags
 along with it. Ofcourse, it is also allowed to specify no flags.
 
 kfunc definitions should also always be annotated with the ``__bpf_kfunc``
-macro. This prevents issues such as the compiler inlining the kfunc if it's a
-static kernel function, or the function being elided in an LTO build as it's
-not used in the rest of the kernel. Developers should not manually add
-annotations to their kfunc to prevent these issues. If an annotation is
-required to prevent such an issue with your kfunc, it is a bug and should be
-added to the definition of the macro so that other kfuncs are similarly
-protected. An example is given below::
+macro. This prevents issues such as the compiler inlining the kfunc, or the
+function being elided in an LTO build as it's not used in the rest of the
+kernel. Developers should not manually add annotations to their kfunc to prevent
+these issues. If an annotation is required to prevent such an issue with your
+kfunc, it is a bug and should be added to the definition of the macro so that
+other kfuncs are similarly protected. An example is given below::
 
         __bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid)
         {
...
         }
 

Documentation/bpf/kfuncs.rst This set encodes the BTF ID of each kfunc listed above, and encodes the flags · line 300

Quoted 10 lines
Documentation/bpf/kfuncs.rst +8 -0
+Note that kfuncs must not be declared ``static``. A kfunc can be called from a
+BPF program ``*.c`` file outside the compilation unit that defines it, so its
+externally visible name must remain available for BTF ID lookup. ``static``
+linkage allows the compiler to rename the function, which can break this
+BTF-based kfunc resolution. Further note that sparse may warn that an otherwise
+unreferenced kfunc should be static. Such warnings should be ignored for kfunc
+definitions.
+
 2.5.1 KF_ACQUIRE flag
 ---------------------

Thanks

reviewer Acked-by on v1 1/1
#3 lore raw
In reply to JP Kobryn
Quoted 6 lines · JP Kobryn

The kfunc documentation mentions how the macro __bpf_kfunc prevents inlining for static functions. This makes it sound like static kfuncs are acceptable. Although static kfuncs may happen to work, it is by chance that the compiler chose not to rename these functions and BTF resolution still succeeds.

Quoted 7 lines

Make it clear in the documentation why kfuncs should not be declared static. First, remove wording that makes it sound like static is ok. Then point out the external naming needed for BTF resolution. Finally point out that sparse may warn on unreferenced kfuncs and that this warning can be ignored.

Quoted 42 lines
---
  Documentation/bpf/kfuncs.rst | 21 ++++++++++++++-------
  1 file changed, 14 insertions(+), 7 deletions(-)
Documentation/bpf/kfuncs.rst +14 -7
index 4c814ff6061e..1dbaff8d4805 100644
@@ -276,19 +276,26 @@ This set encodes the BTF ID of each kfunc listed above, and encodes the flags
  along with it. Ofcourse, it is also allowed to specify no flags.
 
  kfunc definitions should also always be annotated with the ``__bpf_kfunc``
-macro. This prevents issues such as the compiler inlining the kfunc if it's a
-static kernel function, or the function being elided in an LTO build as it's
-not used in the rest of the kernel. Developers should not manually add
-annotations to their kfunc to prevent these issues. If an annotation is
-required to prevent such an issue with your kfunc, it is a bug and should be
-added to the definition of the macro so that other kfuncs are similarly
-protected. An example is given below::
+macro. This prevents issues such as the compiler inlining the kfunc, or the
+function being elided in an LTO build as it's not used in the rest of the
+kernel. Developers should not manually add annotations to their kfunc to prevent
+these issues. If an annotation is required to prevent such an issue with your
+kfunc, it is a bug and should be added to the definition of the macro so that
+other kfuncs are similarly protected. An example is given below::
 
          __bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid)
          {
...
          }
 
+Note that kfuncs must not be declared ``static``. A kfunc can be called from a
+BPF program ``*.c`` file outside the compilation unit that defines it, so its
+externally visible name must remain available for BTF ID lookup. ``static``
+linkage allows the compiler to rename the function, which can break this
+BTF-based kfunc resolution. Further note that sparse may warn that an otherwise
+unreferenced kfunc should be static. Such warnings should be ignored for kfunc
+definitions.
+
  2.5.1 KF_ACQUIRE flag
  ---------------------
#4 lore raw
In reply to JP Kobryn
Quoted 36 lines · JP Kobryn

The kfunc documentation mentions how the macro __bpf_kfunc prevents inlining for static functions. This makes it sound like static kfuncs are acceptable. Although static kfuncs may happen to work, it is by chance that the compiler chose not to rename these functions and BTF resolution still succeeds.

Make it clear in the documentation why kfuncs should not be declared static. First, remove wording that makes it sound like static is ok. Then point out the external naming needed for BTF resolution. Finally point out that sparse may warn on unreferenced kfuncs and that this warning can be ignored.

---
 Documentation/bpf/kfuncs.rst | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
Documentation/bpf/kfuncs.rst +3 -7
index 4c814ff6061e..1dbaff8d4805 100644
@@ -276,19 +276,26 @@ This set encodes the BTF ID of each kfunc listed above, and encodes the flags
 along with it. Ofcourse, it is also allowed to specify no flags.
 
 kfunc definitions should also always be annotated with the ``__bpf_kfunc``
-macro. This prevents issues such as the compiler inlining the kfunc if it's a
-static kernel function, or the function being elided in an LTO build as it's
-not used in the rest of the kernel. Developers should not manually add
-annotations to their kfunc to prevent these issues. If an annotation is
-required to prevent such an issue with your kfunc, it is a bug and should be
-added to the definition of the macro so that other kfuncs are similarly
-protected. An example is given below::
+macro. This prevents issues such as the compiler inlining the kfunc, or the
+function being elided in an LTO build as it's not used in the rest of the
+kernel. Developers should not manually add annotations to their kfunc to prevent

Documentation/bpf/kfuncs.rst This set encodes the BTF ID of each kfunc listed above, and encodes the flags · line 291

Quoted 10 lines
Documentation/bpf/kfuncs.rst +4 -0
+these issues. If an annotation is required to prevent such an issue with your
+kfunc, it is a bug and should be added to the definition of the macro so that
+other kfuncs are similarly protected. An example is given below::
 
         __bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid)
         {
...
         }
 
+Note that kfuncs must not be declared ``static``. A kfunc can be called from a

it seems like we do have static kfuncs and they work fine... And __noclone in __bpf_kfunc is meant to prevent compiler doing .constprop/.isra and other transformations.

Quoted 13 lines
Documentation/bpf/kfuncs.rst +7 -1
+BPF program ``*.c`` file outside the compilation unit that defines it, so its
+externally visible name must remain available for BTF ID lookup. ``static``
+linkage allows the compiler to rename the function, which can break this
+BTF-based kfunc resolution. Further note that sparse may warn that an otherwise
+unreferenced kfunc should be static. Such warnings should be ignored for kfunc
+definitions.
+
 2.5.1 KF_ACQUIRE flag
 ---------------------
 
--

2.54.0

#5 lore raw
Quoted 47 lines · Andrii Nakryiko
Quoted 45 lines · JP Kobryn

The kfunc documentation mentions how the macro __bpf_kfunc prevents inlining for static functions. This makes it sound like static kfuncs are acceptable. Although static kfuncs may happen to work, it is by chance that the compiler chose not to rename these functions and BTF resolution still succeeds.

Make it clear in the documentation why kfuncs should not be declared static. First, remove wording that makes it sound like static is ok. Then point out the external naming needed for BTF resolution. Finally point out that sparse may warn on unreferenced kfuncs and that this warning can be ignored.

---
 Documentation/bpf/kfuncs.rst | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)
Documentation/bpf/kfuncs.rst +6 -7
index 4c814ff6061e..1dbaff8d4805 100644
@@ -276,19 +276,26 @@ This set encodes the BTF ID of each kfunc listed above, and encodes the flags
 along with it. Ofcourse, it is also allowed to specify no flags.
 
 kfunc definitions should also always be annotated with the ``__bpf_kfunc``
-macro. This prevents issues such as the compiler inlining the kfunc if it's a
-static kernel function, or the function being elided in an LTO build as it's
-not used in the rest of the kernel. Developers should not manually add
-annotations to their kfunc to prevent these issues. If an annotation is
-required to prevent such an issue with your kfunc, it is a bug and should be
-added to the definition of the macro so that other kfuncs are similarly
-protected. An example is given below::
+macro. This prevents issues such as the compiler inlining the kfunc, or the
+function being elided in an LTO build as it's not used in the rest of the
+kernel. Developers should not manually add annotations to their kfunc to prevent
+these issues. If an annotation is required to prevent such an issue with your
+kfunc, it is a bug and should be added to the definition of the macro so that
+other kfuncs are similarly protected. An example is given below::
 
         __bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid)
         {
...
         }
Quoted 5 lines
Quoted 1 line

+Note that kfuncs must not be declared ``static``. A kfunc can be called from a

it seems like we do have static kfuncs and they work fine... And __noclone in __bpf_kfunc is meant to prevent compiler doing .constprop/.isra and other transformations.

There is no guarantee that compilers will follow that logic, since "static" vs "__used __retain __noclone noinline" kinda conflict with each other.
Next thing, some post optimizer that only looks at the symbol table will decide to remove it.

So applied to bpf-next with typo fixed.