1============================= 2BPF Kernel Functions (kfuncs) 3============================= 4 51. Introduction 6=============== 7 8BPF Kernel Functions or more commonly known as kfuncs are functions in the Linux 9kernel which are exposed for use by BPF programs. Unlike normal BPF helpers, 10kfuncs do not have a stable interface and can change from one kernel release to 11another. Hence, BPF programs need to be updated in response to changes in the 12kernel. 13 142. Defining a kfunc 15=================== 16 17There are two ways to expose a kernel function to BPF programs, either make an 18existing function in the kernel visible, or add a new wrapper for BPF. In both 19cases, care must be taken that BPF program can only call such function in a 20valid context. To enforce this, visibility of a kfunc can be per program type. 21 22If you are not creating a BPF wrapper for existing kernel function, skip ahead 23to :ref:`BPF_kfunc_nodef`. 24 252.1 Creating a wrapper kfunc 26---------------------------- 27 28When defining a wrapper kfunc, the wrapper function should have extern linkage. 29This prevents the compiler from optimizing away dead code, as this wrapper kfunc 30is not invoked anywhere in the kernel itself. It is not necessary to provide a 31prototype in a header for the wrapper kfunc. 32 33An example is given below:: 34 35 /* Disables missing prototype warnings */ 36 __diag_push(); 37 __diag_ignore_all("-Wmissing-prototypes", 38 "Global kfuncs as their definitions will be in BTF"); 39 40 struct task_struct *bpf_find_get_task_by_vpid(pid_t nr) 41 { 42 return find_get_task_by_vpid(nr); 43 } 44 45 __diag_pop(); 46 47A wrapper kfunc is often needed when we need to annotate parameters of the 48kfunc. Otherwise one may directly make the kfunc visible to the BPF program by 49registering it with the BPF subsystem. See :ref:`BPF_kfunc_nodef`. 50 512.2 Annotating kfunc parameters 52------------------------------- 53 54Similar to BPF helpers, there is sometime need for additional context required 55by the verifier to make the usage of kernel functions safer and more useful. 56Hence, we can annotate a parameter by suffixing the name of the argument of the 57kfunc with a __tag, where tag may be one of the supported annotations. 58 592.2.1 __sz Annotation 60--------------------- 61 62This annotation is used to indicate a memory and size pair in the argument list. 63An example is given below:: 64 65 void bpf_memzero(void *mem, int mem__sz) 66 { 67 ... 68 } 69 70Here, the verifier will treat first argument as a PTR_TO_MEM, and second 71argument as its size. By default, without __sz annotation, the size of the type 72of the pointer is used. Without __sz annotation, a kfunc cannot accept a void 73pointer. 74 75.. _BPF_kfunc_nodef: 76 772.3 Using an existing kernel function 78------------------------------------- 79 80When an existing function in the kernel is fit for consumption by BPF programs, 81it can be directly registered with the BPF subsystem. However, care must still 82be taken to review the context in which it will be invoked by the BPF program 83and whether it is safe to do so. 84 852.4 Annotating kfuncs 86--------------------- 87 88In addition to kfuncs' arguments, verifier may need more information about the 89type of kfunc(s) being registered with the BPF subsystem. To do so, we define 90flags on a set of kfuncs as follows:: 91 92 BTF_SET8_START(bpf_task_set) 93 BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL) 94 BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE) 95 BTF_SET8_END(bpf_task_set) 96 97This set encodes the BTF ID of each kfunc listed above, and encodes the flags 98along with it. Ofcourse, it is also allowed to specify no flags. 99 1002.4.1 KF_ACQUIRE flag 101--------------------- 102 103The KF_ACQUIRE flag is used to indicate that the kfunc returns a pointer to a 104refcounted object. The verifier will then ensure that the pointer to the object 105is eventually released using a release kfunc, or transferred to a map using a 106referenced kptr (by invoking bpf_kptr_xchg). If not, the verifier fails the 107loading of the BPF program until no lingering references remain in all possible 108explored states of the program. 109 1102.4.2 KF_RET_NULL flag 111---------------------- 112 113The KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc 114may be NULL. Hence, it forces the user to do a NULL check on the pointer 115returned from the kfunc before making use of it (dereferencing or passing to 116another helper). This flag is often used in pairing with KF_ACQUIRE flag, but 117both are orthogonal to each other. 118 1192.4.3 KF_RELEASE flag 120--------------------- 121 122The KF_RELEASE flag is used to indicate that the kfunc releases the pointer 123passed in to it. There can be only one referenced pointer that can be passed in. 124All copies of the pointer being released are invalidated as a result of invoking 125kfunc with this flag. 126 1272.4.4 KF_KPTR_GET flag 128---------------------- 129 130The KF_KPTR_GET flag is used to indicate that the kfunc takes the first argument 131as a pointer to kptr, safely increments the refcount of the object it points to, 132and returns a reference to the user. The rest of the arguments may be normal 133arguments of a kfunc. The KF_KPTR_GET flag should be used in conjunction with 134KF_ACQUIRE and KF_RET_NULL flags. 135 1362.4.5 KF_TRUSTED_ARGS flag 137-------------------------- 138 139The KF_TRUSTED_ARGS flag is used for kfuncs taking pointer arguments. It 140indicates that the all pointer arguments will always have a guaranteed lifetime, 141and pointers to kernel objects are always passed to helpers in their unmodified 142form (as obtained from acquire kfuncs). 143 144It can be used to enforce that a pointer to a refcounted object acquired from a 145kfunc or BPF helper is passed as an argument to this kfunc without any 146modifications (e.g. pointer arithmetic) such that it is trusted and points to 147the original object. 148 149Meanwhile, it is also allowed pass pointers to normal memory to such kfuncs, 150but those can have a non-zero offset. 151 152This flag is often used for kfuncs that operate (change some property, perform 153some operation) on an object that was obtained using an acquire kfunc. Such 154kfuncs need an unchanged pointer to ensure the integrity of the operation being 155performed on the expected object. 156 1572.4.6 KF_SLEEPABLE flag 158----------------------- 159 160The KF_SLEEPABLE flag is used for kfuncs that may sleep. Such kfuncs can only 161be called by sleepable BPF programs (BPF_F_SLEEPABLE). 162 1632.4.7 KF_DESTRUCTIVE flag 164-------------------------- 165 166The KF_DESTRUCTIVE flag is used to indicate functions calling which is 167destructive to the system. For example such a call can result in system 168rebooting or panicking. Due to this additional restrictions apply to these 169calls. At the moment they only require CAP_SYS_BOOT capability, but more can be 170added later. 171 1722.5 Registering the kfuncs 173-------------------------- 174 175Once the kfunc is prepared for use, the final step to making it visible is 176registering it with the BPF subsystem. Registration is done per BPF program 177type. An example is shown below:: 178 179 BTF_SET8_START(bpf_task_set) 180 BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL) 181 BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE) 182 BTF_SET8_END(bpf_task_set) 183 184 static const struct btf_kfunc_id_set bpf_task_kfunc_set = { 185 .owner = THIS_MODULE, 186 .set = &bpf_task_set, 187 }; 188 189 static int init_subsystem(void) 190 { 191 return register_btf_kfunc_id_set(BPF_PROG_TYPE_TRACING, &bpf_task_kfunc_set); 192 } 193 late_initcall(init_subsystem); 194