[PATCH bpf-next 2/3] bpf: Document usage of the new __bpf_kfunc macro

David Vernet
2023-01-06T19:53:05Z

Now that the __bpf_kfunc macro has been added to linux/btf.h, include a
blurb about it in the kfuncs.rst file. In order for the macro to
successfully render with .. kernel-doc, we'll also need to add it to the
c_id_attributes array.

Signed-off-by: David Vernet <void@manifault.com>
---
Documentation/bpf/kfuncs.rst | 18 ++++++++++++++++++
Documentation/conf.py | 3 +++
2 files changed, 21 insertions(+)

diff --git a/Documentation/bpf/kfuncs.rst b/Documentation/bpf/kfuncs.rst
index 9fd7fb539f85..900f6b96487c 100644
--- a/Documentation/bpf/kfuncs.rst
+++ b/Documentation/bpf/kfuncs.rst
@@ -37,6 +37,7 @@ An example is given below::
__diag_ignore_all("-Wmissing-prototypes",
"Global kfuncs as their definitions will be in BTF");

+ __bpf_kfunc
struct task_struct *bpf_find_get_task_by_vpid(pid_t nr)
{
return find_get_task_by_vpid(nr);
@@ -62,6 +63,7 @@ kfunc with a __tag, where tag may be one of the supported annotations.
This annotation is used to indicate a memory and size pair in the argument list.
An example is given below::

+ __bpf_kfunc
void bpf_memzero(void *mem, int mem__sz)
{
...
@@ -82,6 +84,7 @@ safety of the program.

An example is given below::

+ __bpf_kfunc
void *bpf_obj_new(u32 local_type_id__k, ...)
{
...
@@ -121,6 +124,21 @@ flags on a set of kfuncs as follows::
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::
+
+ __bpf_kfunc
+ struct task_struct *bpf_get_task_pid(s32 pid)
+ {
+ ...
+ }
+
2.4.1 KF_ACQUIRE flag
---------------------

diff --git a/Documentation/conf.py b/Documentation/conf.py
index a5c45df0bd83..05ff3186b243 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -110,6 +110,9 @@ if major >= 3:

# include/linux/linkage.h:
"asmlinkage",
+
+ # include/linux/btf.h
+ "__bpf_kfunc",
]

else:
--
2.39.0