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