Commit | Line | Data |
---|---|---|
bdbda395 DV |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | .. _kfuncs-header-label: | |
4 | ||
63e564eb KKD |
5 | ============================= |
6 | BPF Kernel Functions (kfuncs) | |
7 | ============================= | |
8 | ||
9 | 1. Introduction | |
10 | =============== | |
11 | ||
12 | BPF Kernel Functions or more commonly known as kfuncs are functions in the Linux | |
13 | kernel which are exposed for use by BPF programs. Unlike normal BPF helpers, | |
14 | kfuncs do not have a stable interface and can change from one kernel release to | |
15 | another. Hence, BPF programs need to be updated in response to changes in the | |
16c294a6 | 16 | kernel. See :ref:`BPF_kfunc_lifecycle_expectations` for more information. |
63e564eb KKD |
17 | |
18 | 2. Defining a kfunc | |
19 | =================== | |
20 | ||
21 | There are two ways to expose a kernel function to BPF programs, either make an | |
22 | existing function in the kernel visible, or add a new wrapper for BPF. In both | |
23 | cases, care must be taken that BPF program can only call such function in a | |
24 | valid context. To enforce this, visibility of a kfunc can be per program type. | |
25 | ||
26 | If you are not creating a BPF wrapper for existing kernel function, skip ahead | |
27 | to :ref:`BPF_kfunc_nodef`. | |
28 | ||
29 | 2.1 Creating a wrapper kfunc | |
30 | ---------------------------- | |
31 | ||
32 | When defining a wrapper kfunc, the wrapper function should have extern linkage. | |
33 | This prevents the compiler from optimizing away dead code, as this wrapper kfunc | |
34 | is not invoked anywhere in the kernel itself. It is not necessary to provide a | |
35 | prototype in a header for the wrapper kfunc. | |
36 | ||
37 | An example is given below:: | |
38 | ||
39 | /* Disables missing prototype warnings */ | |
391145ba | 40 | __bpf_kfunc_start_defs(); |
63e564eb | 41 | |
98e6ab7a | 42 | __bpf_kfunc struct task_struct *bpf_find_get_task_by_vpid(pid_t nr) |
63e564eb KKD |
43 | { |
44 | return find_get_task_by_vpid(nr); | |
45 | } | |
46 | ||
391145ba | 47 | __bpf_kfunc_end_defs(); |
63e564eb KKD |
48 | |
49 | A wrapper kfunc is often needed when we need to annotate parameters of the | |
50 | kfunc. Otherwise one may directly make the kfunc visible to the BPF program by | |
51 | registering it with the BPF subsystem. See :ref:`BPF_kfunc_nodef`. | |
52 | ||
53 | 2.2 Annotating kfunc parameters | |
54 | ------------------------------- | |
55 | ||
56 | Similar to BPF helpers, there is sometime need for additional context required | |
57 | by the verifier to make the usage of kernel functions safer and more useful. | |
58 | Hence, we can annotate a parameter by suffixing the name of the argument of the | |
59 | kfunc with a __tag, where tag may be one of the supported annotations. | |
60 | ||
61 | 2.2.1 __sz Annotation | |
62 | --------------------- | |
63 | ||
64 | This annotation is used to indicate a memory and size pair in the argument list. | |
65 | An example is given below:: | |
66 | ||
98e6ab7a | 67 | __bpf_kfunc void bpf_memzero(void *mem, int mem__sz) |
63e564eb KKD |
68 | { |
69 | ... | |
70 | } | |
71 | ||
72 | Here, the verifier will treat first argument as a PTR_TO_MEM, and second | |
73 | argument as its size. By default, without __sz annotation, the size of the type | |
74 | of the pointer is used. Without __sz annotation, a kfunc cannot accept a void | |
75 | pointer. | |
76 | ||
a50388db KKD |
77 | 2.2.2 __k Annotation |
78 | -------------------- | |
79 | ||
80 | This annotation is only understood for scalar arguments, where it indicates that | |
81 | the verifier must check the scalar argument to be a known constant, which does | |
82 | not indicate a size parameter, and the value of the constant is relevant to the | |
83 | safety of the program. | |
84 | ||
85 | An example is given below:: | |
86 | ||
98e6ab7a | 87 | __bpf_kfunc void *bpf_obj_new(u32 local_type_id__k, ...) |
a50388db KKD |
88 | { |
89 | ... | |
90 | } | |
91 | ||
92 | Here, bpf_obj_new uses local_type_id argument to find out the size of that type | |
93 | ID in program's BTF and return a sized pointer to it. Each type ID will have a | |
94 | distinct size, hence it is crucial to treat each such call as distinct when | |
95 | values don't match during verifier state pruning checks. | |
96 | ||
97 | Hence, whenever a constant scalar argument is accepted by a kfunc which is not a | |
98 | size parameter, and the value of the constant matters for program safety, __k | |
99 | suffix should be used. | |
100 | ||
3bda08b6 | 101 | 2.2.3 __uninit Annotation |
db52b587 | 102 | ------------------------- |
d96d937d JK |
103 | |
104 | This annotation is used to indicate that the argument will be treated as | |
105 | uninitialized. | |
106 | ||
107 | An example is given below:: | |
108 | ||
109 | __bpf_kfunc int bpf_dynptr_from_skb(..., struct bpf_dynptr_kern *ptr__uninit) | |
110 | { | |
111 | ... | |
112 | } | |
113 | ||
114 | Here, the dynptr will be treated as an uninitialized dynptr. Without this | |
115 | annotation, the verifier will reject the program if the dynptr passed in is | |
116 | not initialized. | |
117 | ||
3bda08b6 DR |
118 | 2.2.4 __opt Annotation |
119 | ------------------------- | |
120 | ||
121 | This annotation is used to indicate that the buffer associated with an __sz or __szk | |
122 | argument may be null. If the function is passed a nullptr in place of the buffer, | |
123 | the verifier will not check that length is appropriate for the buffer. The kfunc is | |
124 | responsible for checking if this buffer is null before using it. | |
125 | ||
126 | An example is given below:: | |
127 | ||
128 | __bpf_kfunc void *bpf_dynptr_slice(..., void *buffer__opt, u32 buffer__szk) | |
129 | { | |
130 | ... | |
131 | } | |
132 | ||
133 | Here, the buffer may be null. If buffer is not null, it at least of size buffer_szk. | |
134 | Either way, the returned buffer is either NULL, or of size buffer_szk. Without this | |
135 | annotation, the verifier will reject the program if a null pointer is passed in with | |
136 | a nonzero size. | |
137 | ||
045edee1 SL |
138 | 2.2.5 __str Annotation |
139 | ---------------------------- | |
140 | This annotation is used to indicate that the argument is a constant string. | |
141 | ||
142 | An example is given below:: | |
143 | ||
144 | __bpf_kfunc bpf_get_file_xattr(..., const char *name__str, ...) | |
145 | { | |
146 | ... | |
147 | } | |
148 | ||
149 | In this case, ``bpf_get_file_xattr()`` can be called as:: | |
150 | ||
151 | bpf_get_file_xattr(..., "xattr_name", ...); | |
152 | ||
153 | Or:: | |
154 | ||
155 | const char name[] = "xattr_name"; /* This need to be global */ | |
156 | int BPF_PROG(...) | |
157 | { | |
158 | ... | |
159 | bpf_get_file_xattr(..., name, ...); | |
160 | ... | |
161 | } | |
3bda08b6 | 162 | |
63e564eb KKD |
163 | .. _BPF_kfunc_nodef: |
164 | ||
165 | 2.3 Using an existing kernel function | |
166 | ------------------------------------- | |
167 | ||
168 | When an existing function in the kernel is fit for consumption by BPF programs, | |
169 | it can be directly registered with the BPF subsystem. However, care must still | |
170 | be taken to review the context in which it will be invoked by the BPF program | |
171 | and whether it is safe to do so. | |
172 | ||
173 | 2.4 Annotating kfuncs | |
174 | --------------------- | |
175 | ||
176 | In addition to kfuncs' arguments, verifier may need more information about the | |
177 | type of kfunc(s) being registered with the BPF subsystem. To do so, we define | |
178 | flags on a set of kfuncs as follows:: | |
179 | ||
6f3189f3 | 180 | BTF_KFUNCS_START(bpf_task_set) |
63e564eb KKD |
181 | BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL) |
182 | BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE) | |
6f3189f3 | 183 | BTF_KFUNCS_END(bpf_task_set) |
63e564eb KKD |
184 | |
185 | This set encodes the BTF ID of each kfunc listed above, and encodes the flags | |
186 | along with it. Ofcourse, it is also allowed to specify no flags. | |
187 | ||
98e6ab7a DV |
188 | kfunc definitions should also always be annotated with the ``__bpf_kfunc`` |
189 | macro. This prevents issues such as the compiler inlining the kfunc if it's a | |
190 | static kernel function, or the function being elided in an LTO build as it's | |
191 | not used in the rest of the kernel. Developers should not manually add | |
192 | annotations to their kfunc to prevent these issues. If an annotation is | |
193 | required to prevent such an issue with your kfunc, it is a bug and should be | |
194 | added to the definition of the macro so that other kfuncs are similarly | |
195 | protected. An example is given below:: | |
196 | ||
197 | __bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid) | |
198 | { | |
199 | ... | |
200 | } | |
201 | ||
63e564eb KKD |
202 | 2.4.1 KF_ACQUIRE flag |
203 | --------------------- | |
204 | ||
205 | The KF_ACQUIRE flag is used to indicate that the kfunc returns a pointer to a | |
206 | refcounted object. The verifier will then ensure that the pointer to the object | |
207 | is eventually released using a release kfunc, or transferred to a map using a | |
208 | referenced kptr (by invoking bpf_kptr_xchg). If not, the verifier fails the | |
209 | loading of the BPF program until no lingering references remain in all possible | |
210 | explored states of the program. | |
211 | ||
212 | 2.4.2 KF_RET_NULL flag | |
213 | ---------------------- | |
214 | ||
215 | The KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc | |
216 | may be NULL. Hence, it forces the user to do a NULL check on the pointer | |
217 | returned from the kfunc before making use of it (dereferencing or passing to | |
218 | another helper). This flag is often used in pairing with KF_ACQUIRE flag, but | |
219 | both are orthogonal to each other. | |
220 | ||
221 | 2.4.3 KF_RELEASE flag | |
222 | --------------------- | |
223 | ||
224 | The KF_RELEASE flag is used to indicate that the kfunc releases the pointer | |
6c831c46 DV |
225 | passed in to it. There can be only one referenced pointer that can be passed |
226 | in. All copies of the pointer being released are invalidated as a result of | |
227 | invoking kfunc with this flag. KF_RELEASE kfuncs automatically receive the | |
228 | protection afforded by the KF_TRUSTED_ARGS flag described below. | |
63e564eb | 229 | |
530474e6 | 230 | 2.4.4 KF_TRUSTED_ARGS flag |
63e564eb KKD |
231 | -------------------------- |
232 | ||
233 | The KF_TRUSTED_ARGS flag is used for kfuncs taking pointer arguments. It | |
3f00c523 DV |
234 | indicates that the all pointer arguments are valid, and that all pointers to |
235 | BTF objects have been passed in their unmodified form (that is, at a zero | |
d94cbde2 DV |
236 | offset, and without having been obtained from walking another pointer, with one |
237 | exception described below). | |
3f00c523 DV |
238 | |
239 | There are two types of pointers to kernel objects which are considered "valid": | |
240 | ||
241 | 1. Pointers which are passed as tracepoint or struct_ops callback arguments. | |
530474e6 | 242 | 2. Pointers which were returned from a KF_ACQUIRE kfunc. |
3f00c523 DV |
243 | |
244 | Pointers to non-BTF objects (e.g. scalar pointers) may also be passed to | |
245 | KF_TRUSTED_ARGS kfuncs, and may have a non-zero offset. | |
246 | ||
247 | The definition of "valid" pointers is subject to change at any time, and has | |
248 | absolutely no ABI stability guarantees. | |
63e564eb | 249 | |
d94cbde2 DV |
250 | As mentioned above, a nested pointer obtained from walking a trusted pointer is |
251 | no longer trusted, with one exception. If a struct type has a field that is | |
fbc5669d AP |
252 | guaranteed to be valid (trusted or rcu, as in KF_RCU description below) as long |
253 | as its parent pointer is valid, the following macros can be used to express | |
254 | that to the verifier: | |
255 | ||
256 | * ``BTF_TYPE_SAFE_TRUSTED`` | |
257 | * ``BTF_TYPE_SAFE_RCU`` | |
258 | * ``BTF_TYPE_SAFE_RCU_OR_NULL`` | |
259 | ||
260 | For example, | |
261 | ||
262 | .. code-block:: c | |
263 | ||
264 | BTF_TYPE_SAFE_TRUSTED(struct socket) { | |
265 | struct sock *sk; | |
266 | }; | |
267 | ||
268 | or | |
d94cbde2 DV |
269 | |
270 | .. code-block:: c | |
271 | ||
fbc5669d | 272 | BTF_TYPE_SAFE_RCU(struct task_struct) { |
d94cbde2 | 273 | const cpumask_t *cpus_ptr; |
fbc5669d AP |
274 | struct css_set __rcu *cgroups; |
275 | struct task_struct __rcu *real_parent; | |
276 | struct task_struct *group_leader; | |
d94cbde2 DV |
277 | }; |
278 | ||
279 | In other words, you must: | |
280 | ||
fbc5669d | 281 | 1. Wrap the valid pointer type in a ``BTF_TYPE_SAFE_*`` macro. |
d94cbde2 | 282 | |
fbc5669d | 283 | 2. Specify the type and name of the valid nested field. This field must match |
d94cbde2 DV |
284 | the field in the original type definition exactly. |
285 | ||
fbc5669d AP |
286 | A new type declared by a ``BTF_TYPE_SAFE_*`` macro also needs to be emitted so |
287 | that it appears in BTF. For example, ``BTF_TYPE_SAFE_TRUSTED(struct socket)`` | |
288 | is emitted in the ``type_is_trusted()`` function as follows: | |
289 | ||
290 | .. code-block:: c | |
291 | ||
292 | BTF_TYPE_EMIT(BTF_TYPE_SAFE_TRUSTED(struct socket)); | |
293 | ||
294 | ||
530474e6 | 295 | 2.4.5 KF_SLEEPABLE flag |
fa96b242 BT |
296 | ----------------------- |
297 | ||
298 | The KF_SLEEPABLE flag is used for kfuncs that may sleep. Such kfuncs can only | |
299 | be called by sleepable BPF programs (BPF_F_SLEEPABLE). | |
300 | ||
530474e6 | 301 | 2.4.6 KF_DESTRUCTIVE flag |
4dd48c6f AS |
302 | -------------------------- |
303 | ||
304 | The KF_DESTRUCTIVE flag is used to indicate functions calling which is | |
305 | destructive to the system. For example such a call can result in system | |
306 | rebooting or panicking. Due to this additional restrictions apply to these | |
307 | calls. At the moment they only require CAP_SYS_BOOT capability, but more can be | |
308 | added later. | |
309 | ||
530474e6 | 310 | 2.4.7 KF_RCU flag |
f5362564 YS |
311 | ----------------- |
312 | ||
20c09d92 AS |
313 | The KF_RCU flag is a weaker version of KF_TRUSTED_ARGS. The kfuncs marked with |
314 | KF_RCU expect either PTR_TRUSTED or MEM_RCU arguments. The verifier guarantees | |
315 | that the objects are valid and there is no use-after-free. The pointers are not | |
316 | NULL, but the object's refcount could have reached zero. The kfuncs need to | |
317 | consider doing refcnt != 0 check, especially when returning a KF_ACQUIRE | |
318 | pointer. Note as well that a KF_ACQUIRE kfunc that is KF_RCU should very likely | |
319 | also be KF_RET_NULL. | |
f5362564 | 320 | |
16c294a6 DV |
321 | .. _KF_deprecated_flag: |
322 | ||
530474e6 | 323 | 2.4.8 KF_DEPRECATED flag |
16c294a6 DV |
324 | ------------------------ |
325 | ||
326 | The KF_DEPRECATED flag is used for kfuncs which are scheduled to be | |
327 | changed or removed in a subsequent kernel release. A kfunc that is | |
328 | marked with KF_DEPRECATED should also have any relevant information | |
329 | captured in its kernel doc. Such information typically includes the | |
330 | kfunc's expected remaining lifespan, a recommendation for new | |
331 | functionality that can replace it if any is available, and possibly a | |
332 | rationale for why it is being removed. | |
333 | ||
334 | Note that while on some occasions, a KF_DEPRECATED kfunc may continue to be | |
335 | supported and have its KF_DEPRECATED flag removed, it is likely to be far more | |
336 | difficult to remove a KF_DEPRECATED flag after it's been added than it is to | |
337 | prevent it from being added in the first place. As described in | |
338 | :ref:`BPF_kfunc_lifecycle_expectations`, users that rely on specific kfuncs are | |
339 | encouraged to make their use-cases known as early as possible, and participate | |
340 | in upstream discussions regarding whether to keep, change, deprecate, or remove | |
341 | those kfuncs if and when such discussions occur. | |
342 | ||
63e564eb KKD |
343 | 2.5 Registering the kfuncs |
344 | -------------------------- | |
345 | ||
346 | Once the kfunc is prepared for use, the final step to making it visible is | |
347 | registering it with the BPF subsystem. Registration is done per BPF program | |
348 | type. An example is shown below:: | |
349 | ||
6f3189f3 | 350 | BTF_KFUNCS_START(bpf_task_set) |
63e564eb KKD |
351 | BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL) |
352 | BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE) | |
6f3189f3 | 353 | BTF_KFUNCS_END(bpf_task_set) |
63e564eb KKD |
354 | |
355 | static const struct btf_kfunc_id_set bpf_task_kfunc_set = { | |
356 | .owner = THIS_MODULE, | |
357 | .set = &bpf_task_set, | |
358 | }; | |
359 | ||
360 | static int init_subsystem(void) | |
361 | { | |
362 | return register_btf_kfunc_id_set(BPF_PROG_TYPE_TRACING, &bpf_task_kfunc_set); | |
363 | } | |
364 | late_initcall(init_subsystem); | |
25c5e92d | 365 | |
027bdec8 DV |
366 | 2.6 Specifying no-cast aliases with ___init |
367 | -------------------------------------------- | |
368 | ||
369 | The verifier will always enforce that the BTF type of a pointer passed to a | |
370 | kfunc by a BPF program, matches the type of pointer specified in the kfunc | |
371 | definition. The verifier, does, however, allow types that are equivalent | |
372 | according to the C standard to be passed to the same kfunc arg, even if their | |
373 | BTF_IDs differ. | |
374 | ||
375 | For example, for the following type definition: | |
376 | ||
377 | .. code-block:: c | |
378 | ||
379 | struct bpf_cpumask { | |
380 | cpumask_t cpumask; | |
381 | refcount_t usage; | |
382 | }; | |
383 | ||
384 | The verifier would allow a ``struct bpf_cpumask *`` to be passed to a kfunc | |
385 | taking a ``cpumask_t *`` (which is a typedef of ``struct cpumask *``). For | |
386 | instance, both ``struct cpumask *`` and ``struct bpf_cpmuask *`` can be passed | |
387 | to bpf_cpumask_test_cpu(). | |
388 | ||
389 | In some cases, this type-aliasing behavior is not desired. ``struct | |
390 | nf_conn___init`` is one such example: | |
391 | ||
392 | .. code-block:: c | |
393 | ||
394 | struct nf_conn___init { | |
395 | struct nf_conn ct; | |
396 | }; | |
397 | ||
398 | The C standard would consider these types to be equivalent, but it would not | |
399 | always be safe to pass either type to a trusted kfunc. ``struct | |
400 | nf_conn___init`` represents an allocated ``struct nf_conn`` object that has | |
401 | *not yet been initialized*, so it would therefore be unsafe to pass a ``struct | |
402 | nf_conn___init *`` to a kfunc that's expecting a fully initialized ``struct | |
403 | nf_conn *`` (e.g. ``bpf_ct_change_timeout()``). | |
404 | ||
405 | In order to accommodate such requirements, the verifier will enforce strict | |
406 | PTR_TO_BTF_ID type matching if two types have the exact same name, with one | |
407 | being suffixed with ``___init``. | |
408 | ||
16c294a6 DV |
409 | .. _BPF_kfunc_lifecycle_expectations: |
410 | ||
411 | 3. kfunc lifecycle expectations | |
412 | =============================== | |
413 | ||
414 | kfuncs provide a kernel <-> kernel API, and thus are not bound by any of the | |
415 | strict stability restrictions associated with kernel <-> user UAPIs. This means | |
416 | they can be thought of as similar to EXPORT_SYMBOL_GPL, and can therefore be | |
417 | modified or removed by a maintainer of the subsystem they're defined in when | |
418 | it's deemed necessary. | |
419 | ||
420 | Like any other change to the kernel, maintainers will not change or remove a | |
421 | kfunc without having a reasonable justification. Whether or not they'll choose | |
422 | to change a kfunc will ultimately depend on a variety of factors, such as how | |
423 | widely used the kfunc is, how long the kfunc has been in the kernel, whether an | |
424 | alternative kfunc exists, what the norm is in terms of stability for the | |
425 | subsystem in question, and of course what the technical cost is of continuing | |
426 | to support the kfunc. | |
427 | ||
428 | There are several implications of this: | |
429 | ||
430 | a) kfuncs that are widely used or have been in the kernel for a long time will | |
431 | be more difficult to justify being changed or removed by a maintainer. In | |
432 | other words, kfuncs that are known to have a lot of users and provide | |
433 | significant value provide stronger incentives for maintainers to invest the | |
434 | time and complexity in supporting them. It is therefore important for | |
435 | developers that are using kfuncs in their BPF programs to communicate and | |
436 | explain how and why those kfuncs are being used, and to participate in | |
437 | discussions regarding those kfuncs when they occur upstream. | |
438 | ||
439 | b) Unlike regular kernel symbols marked with EXPORT_SYMBOL_GPL, BPF programs | |
440 | that call kfuncs are generally not part of the kernel tree. This means that | |
441 | refactoring cannot typically change callers in-place when a kfunc changes, | |
442 | as is done for e.g. an upstreamed driver being updated in place when a | |
443 | kernel symbol is changed. | |
444 | ||
445 | Unlike with regular kernel symbols, this is expected behavior for BPF | |
446 | symbols, and out-of-tree BPF programs that use kfuncs should be considered | |
447 | relevant to discussions and decisions around modifying and removing those | |
448 | kfuncs. The BPF community will take an active role in participating in | |
449 | upstream discussions when necessary to ensure that the perspectives of such | |
450 | users are taken into account. | |
451 | ||
452 | c) A kfunc will never have any hard stability guarantees. BPF APIs cannot and | |
453 | will not ever hard-block a change in the kernel purely for stability | |
454 | reasons. That being said, kfuncs are features that are meant to solve | |
455 | problems and provide value to users. The decision of whether to change or | |
456 | remove a kfunc is a multivariate technical decision that is made on a | |
457 | case-by-case basis, and which is informed by data points such as those | |
458 | mentioned above. It is expected that a kfunc being removed or changed with | |
459 | no warning will not be a common occurrence or take place without sound | |
460 | justification, but it is a possibility that must be accepted if one is to | |
461 | use kfuncs. | |
462 | ||
463 | 3.1 kfunc deprecation | |
464 | --------------------- | |
465 | ||
466 | As described above, while sometimes a maintainer may find that a kfunc must be | |
467 | changed or removed immediately to accommodate some changes in their subsystem, | |
468 | usually kfuncs will be able to accommodate a longer and more measured | |
469 | deprecation process. For example, if a new kfunc comes along which provides | |
470 | superior functionality to an existing kfunc, the existing kfunc may be | |
471 | deprecated for some period of time to allow users to migrate their BPF programs | |
472 | to use the new one. Or, if a kfunc has no known users, a decision may be made | |
473 | to remove the kfunc (without providing an alternative API) after some | |
474 | deprecation period so as to provide users with a window to notify the kfunc | |
475 | maintainer if it turns out that the kfunc is actually being used. | |
476 | ||
477 | It's expected that the common case will be that kfuncs will go through a | |
478 | deprecation period rather than being changed or removed without warning. As | |
479 | described in :ref:`KF_deprecated_flag`, the kfunc framework provides the | |
480 | KF_DEPRECATED flag to kfunc developers to signal to users that a kfunc has been | |
481 | deprecated. Once a kfunc has been marked with KF_DEPRECATED, the following | |
482 | procedure is followed for removal: | |
483 | ||
484 | 1. Any relevant information for deprecated kfuncs is documented in the kfunc's | |
485 | kernel docs. This documentation will typically include the kfunc's expected | |
486 | remaining lifespan, a recommendation for new functionality that can replace | |
487 | the usage of the deprecated function (or an explanation as to why no such | |
488 | replacement exists), etc. | |
489 | ||
490 | 2. The deprecated kfunc is kept in the kernel for some period of time after it | |
491 | was first marked as deprecated. This time period will be chosen on a | |
492 | case-by-case basis, and will typically depend on how widespread the use of | |
493 | the kfunc is, how long it has been in the kernel, and how hard it is to move | |
494 | to alternatives. This deprecation time period is "best effort", and as | |
495 | described :ref:`above<BPF_kfunc_lifecycle_expectations>`, circumstances may | |
496 | sometimes dictate that the kfunc be removed before the full intended | |
497 | deprecation period has elapsed. | |
498 | ||
499 | 3. After the deprecation period the kfunc will be removed. At this point, BPF | |
500 | programs calling the kfunc will be rejected by the verifier. | |
501 | ||
502 | 4. Core kfuncs | |
25c5e92d DV |
503 | ============== |
504 | ||
505 | The BPF subsystem provides a number of "core" kfuncs that are potentially | |
506 | applicable to a wide variety of different possible use cases and programs. | |
507 | Those kfuncs are documented here. | |
508 | ||
16c294a6 | 509 | 4.1 struct task_struct * kfuncs |
25c5e92d DV |
510 | ------------------------------- |
511 | ||
512 | There are a number of kfuncs that allow ``struct task_struct *`` objects to be | |
513 | used as kptrs: | |
514 | ||
515 | .. kernel-doc:: kernel/bpf/helpers.c | |
516 | :identifiers: bpf_task_acquire bpf_task_release | |
517 | ||
518 | These kfuncs are useful when you want to acquire or release a reference to a | |
519 | ``struct task_struct *`` that was passed as e.g. a tracepoint arg, or a | |
520 | struct_ops callback arg. For example: | |
521 | ||
522 | .. code-block:: c | |
523 | ||
524 | /** | |
525 | * A trivial example tracepoint program that shows how to | |
526 | * acquire and release a struct task_struct * pointer. | |
527 | */ | |
528 | SEC("tp_btf/task_newtask") | |
529 | int BPF_PROG(task_acquire_release_example, struct task_struct *task, u64 clone_flags) | |
530 | { | |
531 | struct task_struct *acquired; | |
532 | ||
533 | acquired = bpf_task_acquire(task); | |
db9d479a DV |
534 | if (acquired) |
535 | /* | |
536 | * In a typical program you'd do something like store | |
537 | * the task in a map, and the map will automatically | |
538 | * release it later. Here, we release it manually. | |
539 | */ | |
540 | bpf_task_release(acquired); | |
541 | return 0; | |
542 | } | |
543 | ||
544 | ||
545 | References acquired on ``struct task_struct *`` objects are RCU protected. | |
546 | Therefore, when in an RCU read region, you can obtain a pointer to a task | |
547 | embedded in a map value without having to acquire a reference: | |
548 | ||
549 | .. code-block:: c | |
550 | ||
551 | #define private(name) SEC(".data." #name) __hidden __attribute__((aligned(8))) | |
552 | private(TASK) static struct task_struct *global; | |
553 | ||
554 | /** | |
555 | * A trivial example showing how to access a task stored | |
556 | * in a map using RCU. | |
557 | */ | |
558 | SEC("tp_btf/task_newtask") | |
559 | int BPF_PROG(task_rcu_read_example, struct task_struct *task, u64 clone_flags) | |
560 | { | |
561 | struct task_struct *local_copy; | |
562 | ||
563 | bpf_rcu_read_lock(); | |
564 | local_copy = global; | |
565 | if (local_copy) | |
566 | /* | |
567 | * We could also pass local_copy to kfuncs or helper functions here, | |
568 | * as we're guaranteed that local_copy will be valid until we exit | |
569 | * the RCU read region below. | |
570 | */ | |
571 | bpf_printk("Global task %s is valid", local_copy->comm); | |
572 | else | |
573 | bpf_printk("No global task found"); | |
574 | bpf_rcu_read_unlock(); | |
575 | ||
576 | /* At this point we can no longer reference local_copy. */ | |
25c5e92d | 577 | |
25c5e92d DV |
578 | return 0; |
579 | } | |
580 | ||
581 | ---- | |
582 | ||
583 | A BPF program can also look up a task from a pid. This can be useful if the | |
584 | caller doesn't have a trusted pointer to a ``struct task_struct *`` object that | |
585 | it can acquire a reference on with bpf_task_acquire(). | |
586 | ||
587 | .. kernel-doc:: kernel/bpf/helpers.c | |
588 | :identifiers: bpf_task_from_pid | |
589 | ||
590 | Here is an example of it being used: | |
591 | ||
592 | .. code-block:: c | |
593 | ||
594 | SEC("tp_btf/task_newtask") | |
595 | int BPF_PROG(task_get_pid_example, struct task_struct *task, u64 clone_flags) | |
596 | { | |
597 | struct task_struct *lookup; | |
598 | ||
599 | lookup = bpf_task_from_pid(task->pid); | |
600 | if (!lookup) | |
601 | /* A task should always be found, as %task is a tracepoint arg. */ | |
602 | return -ENOENT; | |
603 | ||
604 | if (lookup->pid != task->pid) { | |
605 | /* bpf_task_from_pid() looks up the task via its | |
606 | * globally-unique pid from the init_pid_ns. Thus, | |
607 | * the pid of the lookup task should always be the | |
608 | * same as the input task. | |
609 | */ | |
610 | bpf_task_release(lookup); | |
611 | return -EINVAL; | |
612 | } | |
613 | ||
614 | /* bpf_task_from_pid() returns an acquired reference, | |
615 | * so it must be dropped before returning from the | |
616 | * tracepoint handler. | |
617 | */ | |
618 | bpf_task_release(lookup); | |
619 | return 0; | |
620 | } | |
36aa10ff | 621 | |
16c294a6 | 622 | 4.2 struct cgroup * kfuncs |
36aa10ff DV |
623 | -------------------------- |
624 | ||
625 | ``struct cgroup *`` objects also have acquire and release functions: | |
626 | ||
627 | .. kernel-doc:: kernel/bpf/helpers.c | |
628 | :identifiers: bpf_cgroup_acquire bpf_cgroup_release | |
629 | ||
630 | These kfuncs are used in exactly the same manner as bpf_task_acquire() and | |
631 | bpf_task_release() respectively, so we won't provide examples for them. | |
632 | ||
633 | ---- | |
634 | ||
332ea1f6 TH |
635 | Other kfuncs available for interacting with ``struct cgroup *`` objects are |
636 | bpf_cgroup_ancestor() and bpf_cgroup_from_id(), allowing callers to access | |
637 | the ancestor of a cgroup and find a cgroup by its ID, respectively. Both | |
638 | return a cgroup kptr. | |
36aa10ff DV |
639 | |
640 | .. kernel-doc:: kernel/bpf/helpers.c | |
641 | :identifiers: bpf_cgroup_ancestor | |
642 | ||
332ea1f6 TH |
643 | .. kernel-doc:: kernel/bpf/helpers.c |
644 | :identifiers: bpf_cgroup_from_id | |
645 | ||
36aa10ff DV |
646 | Eventually, BPF should be updated to allow this to happen with a normal memory |
647 | load in the program itself. This is currently not possible without more work in | |
648 | the verifier. bpf_cgroup_ancestor() can be used as follows: | |
649 | ||
650 | .. code-block:: c | |
651 | ||
652 | /** | |
653 | * Simple tracepoint example that illustrates how a cgroup's | |
654 | * ancestor can be accessed using bpf_cgroup_ancestor(). | |
655 | */ | |
656 | SEC("tp_btf/cgroup_mkdir") | |
657 | int BPF_PROG(cgrp_ancestor_example, struct cgroup *cgrp, const char *path) | |
658 | { | |
659 | struct cgroup *parent; | |
660 | ||
661 | /* The parent cgroup resides at the level before the current cgroup's level. */ | |
662 | parent = bpf_cgroup_ancestor(cgrp, cgrp->level - 1); | |
663 | if (!parent) | |
664 | return -ENOENT; | |
665 | ||
666 | bpf_printk("Parent id is %d", parent->self.id); | |
667 | ||
668 | /* Return the parent cgroup that was acquired above. */ | |
669 | bpf_cgroup_release(parent); | |
670 | return 0; | |
671 | } | |
bdbda395 | 672 | |
16c294a6 | 673 | 4.3 struct cpumask * kfuncs |
bdbda395 DV |
674 | --------------------------- |
675 | ||
676 | BPF provides a set of kfuncs that can be used to query, allocate, mutate, and | |
677 | destroy struct cpumask * objects. Please refer to :ref:`cpumasks-header-label` | |
678 | for more details. |