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