KFuncs

v5.13

KFunc (Kernel Function) refers to functions in the kernel that are specially annotated and explicitly allowed to be called from eBPF programs. KFuncs complement traditional eBPF helper functions, providing a new way to achieve similar functionality.

Formally, KFuncs are unstable. Unlike helper functions, KFuncs do not have a User Space Application Programming Interface (UAPI) guarantee. In practice, this means that KFuncs may change or be removed between different kernel versions. However, like all features, the kernel community strives to avoid significant changes and provides deprecation warnings whenever possible. Therefore, users of KFuncs need to pay closer attention to kernel changes and be prepared to update their programs more frequently or write complex code that is compatible with multiple kernel versions.

Usage

Using KFunc is quite simple. The first step is to copy the function signature (return type, name, and parameters) of the KFunc we want to call. These function signatures can usually be found in the kernel source code or KFunc documentation pages. The second step is to add the extern keyword to inform the compiler that this function is not defined in our compilation unit. Finally, we add the __ksym attribute to indicate to the loader that this function reference should be resolved to the actual address of the kernel symbol (i.e., the kernel function).

KFunc Documentation

https://docs.ebpf.io/linux/kfuncs/

After completing these steps, we can call KFunc just like a regular function.

#include <vmlinux.h>
#include <bpf/bpf_helpers.h>

extern struct task_struct *bpf_task_acquire(struct task_struct *p) __ksym;

extern void bpf_task_release(struct task_struct *p) __ksym;

SEC("tp_btf/task_newtask")
int BPF_PROG(task_acquire_release_example, struct task_struct *task, u64 clone_flags)
{
    struct task_struct *acquired;

    acquired = bpf_task_acquire(task);
    if (acquired)
          /*
           * In a typical program, you might store the task in a
           * map, which would then automatically release this task.
           * Here, we manually release it.
           */ 
            bpf_task_release(acquired);
    return 0;
}

char _license[] SEC("license") = "GPL";

Note

__ksym is defined as #define __ksym __attribute__((section(".ksyms")))

Kernel Modules

The KFunc index contains all KFuncs defined in the Linux kernel source code. Not all of these KFuncs are available depending on the KConfig configuration used to compile the kernel; some may require kernel modules to be used.

KFunc Index

https://docs.ebpf.io/linux/kfuncs/

KFuncs can be dynamically added to the kernel through kernel modules, allowing both built-in and third-party modules to add KFuncs. The mechanism is the same, but you may need to handle the case of “module not loaded”.

Parameter Annotations

Parameters of KFuncs can be annotated with certain suffixes that indicate how the parameters are to be used. The verifier recognizes these annotations and enforces the rules implied by them.

`__sz` Annotation

v5.18

Parameters with the __sz suffix are used to indicate the size of the memory pointed to by the pointer.

For example:

void bpf_memzero(void *mem, int mem__sz)

In this case, mem__sz indicates the size of the memory pointed to by mem. The verifier will ensure that mem is a valid pointer and that mem__sz does not lead to out-of-bounds access.

`__szk` Annotation

v6.4

Parameters with the __szk suffix are similar to __sz, but their value must be a constant at compile time. This annotation is typically used when the preceding parameter is a pointer to a kernel structure, and the size of that kernel structure may change between different kernel versions. In this case, the sizeof() value of the structure should be used.

`__k` Annotation

v6.2

Parameters with the __k suffix indicate that their value must be a scalar (just a number) and a known constant. This is typically used for BTF IDs.

For example:

void *bpf_obj_new_impl(u64 local_type_id__k, void *meta__ign)

bpf_obj_new_impl KFunc will create a new object with the given BTF type shape, which could be a structure. Since the size of the returned object depends on local_type_id__k, the verifier will ensure that local_type_id__k is a valid BTF ID and knows the size of the returned object.

For other functions, different types of constants may be used.

`__ign` Annotation

v6.2

Parameters with the __ign suffix indicate that this parameter will be ignored during type checking. Therefore, any type can be passed to it without restrictions.

`__uninit` Annotation

v6.4

Parameters with the __uninit suffix indicate that this parameter will be treated as uninitialized. Typically, without this annotation, the verifier requires all parameters to be initialized before use.

Thus, it is often used in scenarios where KFunc initializes objects.

__alloc Annotation

v6.2

Parameters with the __alloc suffix indicate that this parameter is a pointer to a memory area that was allocated at some point by KFunc.

This is typically used for KFuncs like bpf_obj_drop_impl, which is used to free memory allocated by bpf_obj_new_impl. Here, we want to prevent passing pointers to stack or map values.

`__opt` Annotation

v6.5

Parameters with the __opt suffix indicate that this parameter, associated with __sz or __szk, is optional. This means that this parameter can be NULL.

void *bpf_dynptr_slice(..., void *buffer__opt, u32 buffer__szk)

`__refcounted_kptr` Annotation

v6.4

Parameters with the __refcounted_kptr suffix indicate that the value passed to this parameter must be a reference-counted kernel pointer.

Documentation to be improved

This part of the documentation is incomplete, and contributions are welcome.

`__nullable` Annotation

v6.7

Parameters with the __nullable suffix indicate that this parameter can be NULL. Typically, typed pointers must be non-NULL, but with this annotation, the verifier will allow passing NULL.

For example:

int bpf_iter_task_new(struct bpf_iter_task *it, struct task_struct *task__nullable, unsigned int flags)

`__str` Annotation

v6.8

Parameters with the __str suffix indicate that this parameter is a constant string.

For example:

bpf_get_file_xattr(..., const char *name__str, ...)

This can be called as:

bpf_get_file_xattr(..., "xattr_name", ...);

Or:

const char name[] = "xattr_name";  /* This must be a global variable */
int BPF_PROG(...)
{
        ...
        bpf_get_file_xattr(..., name, ...);
        ...
}

But it cannot use a string that is unknown at compile time.

__map Annotation

v6.9

Parameters with the __map suffix indicate that this parameter is a pointer to a map. This allows kernel functions (kfuncs) to operate on the map.

For example, the bpf_arena_alloc_pages kernel function:

void *bpf_arena_alloc_pages(void *p__map, void *addr__ign, u32 page_cnt, int node_id, u64 flags)

__prog Annotation

v6.16

This annotation indicates that this parameter needs to be corrected to the caller’s BPF program’s bpf_prog_aux. Any value passed to this parameter will be ignored and rewritten by the verifier.

Kernel Function Flags

Kernel functions can be associated with certain flags. These flags are not visible in the function signature but indicate certain characteristics of the function. If a flag significantly affects the behavior of the function, it will be documented on the kernel function documentation page.

A function can have multiple flags at the same time, and in most cases, these flags are not mutually exclusive.

For completeness, this section will document the available flags.

KF_ACQUIRE

v6.0

KF_ACQUIRE flag indicates that the kernel function returns a reference to a kernel object. This means that the caller is responsible for releasing it after use.

Typically, kernel functions with the KF_ACQUIRE flag will have a corresponding kernel function with the KF_RELEASE flag, making such paired functions easy to identify.

KF_RELEASE

v6.0

KF_RELEASE flag indicates that the kernel function receives a reference to a kernel object and releases it.

Typically, kernel functions with the KF_ACQUIRE flag will have a corresponding kernel function with the KF_RELEASE flag, making such paired functions easy to identify.

KF_RET_NULL

v6.0

KF_RET_NULL flag indicates that the kernel function may return NULL. The verifier will enforce that the return value is checked for NULL before being passed to another kernel function that does not accept nullable values or dereferenced.

KF_TRUSTED_ARGS

v6.0

KF_TRUSTED_ARGS flag indicates that pointers to kernel objects passed to this kernel function must be “valid” and all pointers to BTF objects must be in their unmodified form.

Being a “valid” kernel pointer means satisfying one of the following conditions:

Pointer passed as a tracepoint or struct_ops callback parameter.
Pointer returned from a kernel function with the KF_ACQUIRE flag.

Documentation to be improved

This part of the documentation is incomplete, and contributions are welcome.

KF_SLEEPABLE

v6.1

KF_SLEEPABLE flag indicates that the kernel function may sleep. This means that this kernel function can only be called from programs loaded in a sleepable manner (loaded with the BPF_F_SLEEPABLE flag).

KF_DESTRUCTIVE

v6.1

KF_DESTRUCTIVE flag indicates that the kernel function is destructive to the system. For example, a single call may cause the kernel to crash or reboot. Due to the risks, only programs loaded by users with CAP_SYS_BOOT permission can call such kernel functions.

KF_RCU

v6.4

KF_RCU flag indicates that parameters passed to this kernel function must be protected by RCU (Read-Copy-Update).

Documentation to be improved

This part of the documentation is incomplete, and contributions are welcome.

KF_ITER_NEW

v6.4

KF_ITER_NEW flag indicates that the kernel function is used to initialize an iterator. This means that this kernel function will return a pointer to an iterator that can be used to traverse a set of objects.

The verifier will ensure that the iterator is destroyed by a function with the KF_ITER_DESTROY flag. Typically, kernel functions with the KF_ITER_NEW flag will have a corresponding kernel function with the KF_ITER_DESTROY flag, making such paired functions easy to identify.

KF_ITER_NEXT

v6.4

KF_ITER_NEXT flag indicates that the kernel function is used to advance an iterator. This means that this kernel function will receive a pointer to an iterator and advance it to the next object.

The verifier will enforce that the KF_ITER_NEXT kernel function can only be called with iterators created by the KF_ITER_NEW kernel function. Typically, kernel functions with the KF_ITER_NEW flag will have a corresponding kernel function with the KF_ITER_NEXT flag, making such paired functions easy to identify.

KF_ITER_DESTROY

v6.4

KF_ITER_DESTROY flag indicates that the kernel function is used to destroy an iterator. This means that this kernel function will receive a pointer to an iterator and destroy it.

KF_RCU_PROTECTED

v6.7

KF_RCU_PROTECTED flag indicates that this kernel function can only be used within an RCU critical section. This means that sleepable programs must explicitly use bpf_rcu_read_lock and bpf_rcu_read_unlock<code> to protect calls to such kernel functions. Programs running in the context of an RCU critical section can call these kernel functions without any additional protection.

Source

https://docs.ebpf.io/linux/concepts/kfuncs/

Last updated: August 16, 2025

Understanding KFuncs in Linux eBPF

KFuncs

Usage

Kernel Modules

Parameter Annotations

`<span>__sz</span>` Annotation

`<span>__szk</span>` Annotation

`<span>__k</span>` Annotation

`<span>__ign</span>` Annotation

`<span>__uninit</span>` Annotation

__alloc Annotation

`<span>__opt</span>` Annotation

`<span>__refcounted_kptr</span>` Annotation

`<span>__nullable</span>` Annotation

`<span>__str</span>` Annotation

__map Annotation

__prog Annotation

Kernel Function Flags

KF_ACQUIRE

KF_RELEASE

KF_RET_NULL

KF_TRUSTED_ARGS

KF_SLEEPABLE

KF_DESTRUCTIVE

KF_RCU

KF_ITER_NEW

KF_ITER_NEXT

KF_ITER_DESTROY

KF_RCU_PROTECTED

Source

Leave a Comment Cancel reply

KFuncs

Usage

Kernel Modules

Parameter Annotations

<span>__sz</span> Annotation

<span>__szk</span> Annotation

<span>__k</span> Annotation

<span>__ign</span> Annotation

<span>__uninit</span> Annotation

__alloc Annotation

<span>__opt</span> Annotation

<span>__refcounted_kptr</span> Annotation

<span>__nullable</span> Annotation

<span>__str</span> Annotation

__map Annotation

__prog Annotation

Kernel Function Flags

KF_ACQUIRE

KF_RELEASE

KF_RET_NULL

KF_TRUSTED_ARGS

KF_SLEEPABLE

KF_DESTRUCTIVE

KF_RCU

KF_ITER_NEW

KF_ITER_NEXT

KF_ITER_DESTROY

KF_RCU_PROTECTED

Source

Related posts

Leave a Comment Cancel reply

`<span>__sz</span>` Annotation

`<span>__szk</span>` Annotation

`<span>__k</span>` Annotation

`<span>__ign</span>` Annotation

`<span>__uninit</span>` Annotation

`<span>__opt</span>` Annotation

`<span>__refcounted_kptr</span>` Annotation

`<span>__nullable</span>` Annotation

`<span>__str</span>` Annotation