1bdbda395SDavid Vernet.. SPDX-License-Identifier: GPL-2.0 2bdbda395SDavid Vernet 3bdbda395SDavid Vernet.. _kfuncs-header-label: 4bdbda395SDavid Vernet 563e564ebSKumar Kartikeya Dwivedi============================= 663e564ebSKumar Kartikeya DwivediBPF Kernel Functions (kfuncs) 763e564ebSKumar Kartikeya Dwivedi============================= 863e564ebSKumar Kartikeya Dwivedi 963e564ebSKumar Kartikeya Dwivedi1. Introduction 1063e564ebSKumar Kartikeya Dwivedi=============== 1163e564ebSKumar Kartikeya Dwivedi 1263e564ebSKumar Kartikeya DwivediBPF Kernel Functions or more commonly known as kfuncs are functions in the Linux 1363e564ebSKumar Kartikeya Dwivedikernel which are exposed for use by BPF programs. Unlike normal BPF helpers, 1463e564ebSKumar Kartikeya Dwivedikfuncs do not have a stable interface and can change from one kernel release to 1563e564ebSKumar Kartikeya Dwivedianother. Hence, BPF programs need to be updated in response to changes in the 1616c294a6SDavid Vernetkernel. See :ref:`BPF_kfunc_lifecycle_expectations` for more information. 1763e564ebSKumar Kartikeya Dwivedi 1863e564ebSKumar Kartikeya Dwivedi2. Defining a kfunc 1963e564ebSKumar Kartikeya Dwivedi=================== 2063e564ebSKumar Kartikeya Dwivedi 2163e564ebSKumar Kartikeya DwivediThere are two ways to expose a kernel function to BPF programs, either make an 2263e564ebSKumar Kartikeya Dwivediexisting function in the kernel visible, or add a new wrapper for BPF. In both 2363e564ebSKumar Kartikeya Dwivedicases, care must be taken that BPF program can only call such function in a 2463e564ebSKumar Kartikeya Dwivedivalid context. To enforce this, visibility of a kfunc can be per program type. 2563e564ebSKumar Kartikeya Dwivedi 2663e564ebSKumar Kartikeya DwivediIf you are not creating a BPF wrapper for existing kernel function, skip ahead 2763e564ebSKumar Kartikeya Dwivedito :ref:`BPF_kfunc_nodef`. 2863e564ebSKumar Kartikeya Dwivedi 2963e564ebSKumar Kartikeya Dwivedi2.1 Creating a wrapper kfunc 3063e564ebSKumar Kartikeya Dwivedi---------------------------- 3163e564ebSKumar Kartikeya Dwivedi 3263e564ebSKumar Kartikeya DwivediWhen defining a wrapper kfunc, the wrapper function should have extern linkage. 3363e564ebSKumar Kartikeya DwivediThis prevents the compiler from optimizing away dead code, as this wrapper kfunc 3463e564ebSKumar Kartikeya Dwivediis not invoked anywhere in the kernel itself. It is not necessary to provide a 3563e564ebSKumar Kartikeya Dwivediprototype in a header for the wrapper kfunc. 3663e564ebSKumar Kartikeya Dwivedi 3763e564ebSKumar Kartikeya DwivediAn example is given below:: 3863e564ebSKumar Kartikeya Dwivedi 3963e564ebSKumar Kartikeya Dwivedi /* Disables missing prototype warnings */ 40391145baSDave Marchevsky __bpf_kfunc_start_defs(); 4163e564ebSKumar Kartikeya Dwivedi 4298e6ab7aSDavid Vernet __bpf_kfunc struct task_struct *bpf_find_get_task_by_vpid(pid_t nr) 4363e564ebSKumar Kartikeya Dwivedi { 4463e564ebSKumar Kartikeya Dwivedi return find_get_task_by_vpid(nr); 4563e564ebSKumar Kartikeya Dwivedi } 4663e564ebSKumar Kartikeya Dwivedi 47391145baSDave Marchevsky __bpf_kfunc_end_defs(); 4863e564ebSKumar Kartikeya Dwivedi 4963e564ebSKumar Kartikeya DwivediA wrapper kfunc is often needed when we need to annotate parameters of the 5063e564ebSKumar Kartikeya Dwivedikfunc. Otherwise one may directly make the kfunc visible to the BPF program by 5163e564ebSKumar Kartikeya Dwivediregistering it with the BPF subsystem. See :ref:`BPF_kfunc_nodef`. 5263e564ebSKumar Kartikeya Dwivedi 5363e564ebSKumar Kartikeya Dwivedi2.2 Annotating kfunc parameters 5463e564ebSKumar Kartikeya Dwivedi------------------------------- 5563e564ebSKumar Kartikeya Dwivedi 5663e564ebSKumar Kartikeya DwivediSimilar to BPF helpers, there is sometime need for additional context required 5763e564ebSKumar Kartikeya Dwivediby the verifier to make the usage of kernel functions safer and more useful. 5863e564ebSKumar Kartikeya DwivediHence, we can annotate a parameter by suffixing the name of the argument of the 5963e564ebSKumar Kartikeya Dwivedikfunc with a __tag, where tag may be one of the supported annotations. 6063e564ebSKumar Kartikeya Dwivedi 6163e564ebSKumar Kartikeya Dwivedi2.2.1 __sz Annotation 6263e564ebSKumar Kartikeya Dwivedi--------------------- 6363e564ebSKumar Kartikeya Dwivedi 6463e564ebSKumar Kartikeya DwivediThis annotation is used to indicate a memory and size pair in the argument list. 6563e564ebSKumar Kartikeya DwivediAn example is given below:: 6663e564ebSKumar Kartikeya Dwivedi 6798e6ab7aSDavid Vernet __bpf_kfunc void bpf_memzero(void *mem, int mem__sz) 6863e564ebSKumar Kartikeya Dwivedi { 6963e564ebSKumar Kartikeya Dwivedi ... 7063e564ebSKumar Kartikeya Dwivedi } 7163e564ebSKumar Kartikeya Dwivedi 7263e564ebSKumar Kartikeya DwivediHere, the verifier will treat first argument as a PTR_TO_MEM, and second 7363e564ebSKumar Kartikeya Dwivediargument as its size. By default, without __sz annotation, the size of the type 7463e564ebSKumar Kartikeya Dwivediof the pointer is used. Without __sz annotation, a kfunc cannot accept a void 7563e564ebSKumar Kartikeya Dwivedipointer. 7663e564ebSKumar Kartikeya Dwivedi 77a50388dbSKumar Kartikeya Dwivedi2.2.2 __k Annotation 78a50388dbSKumar Kartikeya Dwivedi-------------------- 79a50388dbSKumar Kartikeya Dwivedi 80a50388dbSKumar Kartikeya DwivediThis annotation is only understood for scalar arguments, where it indicates that 81a50388dbSKumar Kartikeya Dwivedithe verifier must check the scalar argument to be a known constant, which does 82a50388dbSKumar Kartikeya Dwivedinot indicate a size parameter, and the value of the constant is relevant to the 83a50388dbSKumar Kartikeya Dwivedisafety of the program. 84a50388dbSKumar Kartikeya Dwivedi 85a50388dbSKumar Kartikeya DwivediAn example is given below:: 86a50388dbSKumar Kartikeya Dwivedi 8798e6ab7aSDavid Vernet __bpf_kfunc void *bpf_obj_new(u32 local_type_id__k, ...) 88a50388dbSKumar Kartikeya Dwivedi { 89a50388dbSKumar Kartikeya Dwivedi ... 90a50388dbSKumar Kartikeya Dwivedi } 91a50388dbSKumar Kartikeya Dwivedi 92a50388dbSKumar Kartikeya DwivediHere, bpf_obj_new uses local_type_id argument to find out the size of that type 93a50388dbSKumar Kartikeya DwivediID in program's BTF and return a sized pointer to it. Each type ID will have a 94a50388dbSKumar Kartikeya Dwivedidistinct size, hence it is crucial to treat each such call as distinct when 95a50388dbSKumar Kartikeya Dwivedivalues don't match during verifier state pruning checks. 96a50388dbSKumar Kartikeya Dwivedi 97a50388dbSKumar Kartikeya DwivediHence, whenever a constant scalar argument is accepted by a kfunc which is not a 98a50388dbSKumar Kartikeya Dwivedisize parameter, and the value of the constant matters for program safety, __k 99a50388dbSKumar Kartikeya Dwivedisuffix should be used. 100a50388dbSKumar Kartikeya Dwivedi 1013bda08b6SDaniel Rosenberg2.2.3 __uninit Annotation 102db52b587SDavid Vernet------------------------- 103d96d937dSJoanne Koong 104d96d937dSJoanne KoongThis annotation is used to indicate that the argument will be treated as 105d96d937dSJoanne Koonguninitialized. 106d96d937dSJoanne Koong 107d96d937dSJoanne KoongAn example is given below:: 108d96d937dSJoanne Koong 109d96d937dSJoanne Koong __bpf_kfunc int bpf_dynptr_from_skb(..., struct bpf_dynptr_kern *ptr__uninit) 110d96d937dSJoanne Koong { 111d96d937dSJoanne Koong ... 112d96d937dSJoanne Koong } 113d96d937dSJoanne Koong 114d96d937dSJoanne KoongHere, the dynptr will be treated as an uninitialized dynptr. Without this 115d96d937dSJoanne Koongannotation, the verifier will reject the program if the dynptr passed in is 116d96d937dSJoanne Koongnot initialized. 117d96d937dSJoanne Koong 1183bda08b6SDaniel Rosenberg2.2.4 __opt Annotation 1193bda08b6SDaniel Rosenberg------------------------- 1203bda08b6SDaniel Rosenberg 1213bda08b6SDaniel RosenbergThis annotation is used to indicate that the buffer associated with an __sz or __szk 1223bda08b6SDaniel Rosenbergargument may be null. If the function is passed a nullptr in place of the buffer, 1233bda08b6SDaniel Rosenbergthe verifier will not check that length is appropriate for the buffer. The kfunc is 1243bda08b6SDaniel Rosenbergresponsible for checking if this buffer is null before using it. 1253bda08b6SDaniel Rosenberg 1263bda08b6SDaniel RosenbergAn example is given below:: 1273bda08b6SDaniel Rosenberg 1283bda08b6SDaniel Rosenberg __bpf_kfunc void *bpf_dynptr_slice(..., void *buffer__opt, u32 buffer__szk) 1293bda08b6SDaniel Rosenberg { 1303bda08b6SDaniel Rosenberg ... 1313bda08b6SDaniel Rosenberg } 1323bda08b6SDaniel Rosenberg 1333bda08b6SDaniel RosenbergHere, the buffer may be null. If buffer is not null, it at least of size buffer_szk. 1343bda08b6SDaniel RosenbergEither way, the returned buffer is either NULL, or of size buffer_szk. Without this 1353bda08b6SDaniel Rosenbergannotation, the verifier will reject the program if a null pointer is passed in with 1363bda08b6SDaniel Rosenberga nonzero size. 1373bda08b6SDaniel Rosenberg 138045edee1SSong Liu2.2.5 __str Annotation 139045edee1SSong Liu---------------------------- 140045edee1SSong LiuThis annotation is used to indicate that the argument is a constant string. 141045edee1SSong Liu 142045edee1SSong LiuAn example is given below:: 143045edee1SSong Liu 144045edee1SSong Liu __bpf_kfunc bpf_get_file_xattr(..., const char *name__str, ...) 145045edee1SSong Liu { 146045edee1SSong Liu ... 147045edee1SSong Liu } 148045edee1SSong Liu 149045edee1SSong LiuIn this case, ``bpf_get_file_xattr()`` can be called as:: 150045edee1SSong Liu 151045edee1SSong Liu bpf_get_file_xattr(..., "xattr_name", ...); 152045edee1SSong Liu 153045edee1SSong LiuOr:: 154045edee1SSong Liu 155045edee1SSong Liu const char name[] = "xattr_name"; /* This need to be global */ 156045edee1SSong Liu int BPF_PROG(...) 157045edee1SSong Liu { 158045edee1SSong Liu ... 159045edee1SSong Liu bpf_get_file_xattr(..., name, ...); 160045edee1SSong Liu ... 161045edee1SSong Liu } 1623bda08b6SDaniel Rosenberg 16363e564ebSKumar Kartikeya Dwivedi.. _BPF_kfunc_nodef: 16463e564ebSKumar Kartikeya Dwivedi 16563e564ebSKumar Kartikeya Dwivedi2.3 Using an existing kernel function 16663e564ebSKumar Kartikeya Dwivedi------------------------------------- 16763e564ebSKumar Kartikeya Dwivedi 16863e564ebSKumar Kartikeya DwivediWhen an existing function in the kernel is fit for consumption by BPF programs, 16963e564ebSKumar Kartikeya Dwivediit can be directly registered with the BPF subsystem. However, care must still 17063e564ebSKumar Kartikeya Dwivedibe taken to review the context in which it will be invoked by the BPF program 17163e564ebSKumar Kartikeya Dwivediand whether it is safe to do so. 17263e564ebSKumar Kartikeya Dwivedi 17363e564ebSKumar Kartikeya Dwivedi2.4 Annotating kfuncs 17463e564ebSKumar Kartikeya Dwivedi--------------------- 17563e564ebSKumar Kartikeya Dwivedi 17663e564ebSKumar Kartikeya DwivediIn addition to kfuncs' arguments, verifier may need more information about the 17763e564ebSKumar Kartikeya Dwiveditype of kfunc(s) being registered with the BPF subsystem. To do so, we define 17863e564ebSKumar Kartikeya Dwivediflags on a set of kfuncs as follows:: 17963e564ebSKumar Kartikeya Dwivedi 180*6f3189f3SDaniel Xu BTF_KFUNCS_START(bpf_task_set) 18163e564ebSKumar Kartikeya Dwivedi BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL) 18263e564ebSKumar Kartikeya Dwivedi BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE) 183*6f3189f3SDaniel Xu BTF_KFUNCS_END(bpf_task_set) 18463e564ebSKumar Kartikeya Dwivedi 18563e564ebSKumar Kartikeya DwivediThis set encodes the BTF ID of each kfunc listed above, and encodes the flags 18663e564ebSKumar Kartikeya Dwivedialong with it. Ofcourse, it is also allowed to specify no flags. 18763e564ebSKumar Kartikeya Dwivedi 18898e6ab7aSDavid Vernetkfunc definitions should also always be annotated with the ``__bpf_kfunc`` 18998e6ab7aSDavid Vernetmacro. This prevents issues such as the compiler inlining the kfunc if it's a 19098e6ab7aSDavid Vernetstatic kernel function, or the function being elided in an LTO build as it's 19198e6ab7aSDavid Vernetnot used in the rest of the kernel. Developers should not manually add 19298e6ab7aSDavid Vernetannotations to their kfunc to prevent these issues. If an annotation is 19398e6ab7aSDavid Vernetrequired to prevent such an issue with your kfunc, it is a bug and should be 19498e6ab7aSDavid Vernetadded to the definition of the macro so that other kfuncs are similarly 19598e6ab7aSDavid Vernetprotected. An example is given below:: 19698e6ab7aSDavid Vernet 19798e6ab7aSDavid Vernet __bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid) 19898e6ab7aSDavid Vernet { 19998e6ab7aSDavid Vernet ... 20098e6ab7aSDavid Vernet } 20198e6ab7aSDavid Vernet 20263e564ebSKumar Kartikeya Dwivedi2.4.1 KF_ACQUIRE flag 20363e564ebSKumar Kartikeya Dwivedi--------------------- 20463e564ebSKumar Kartikeya Dwivedi 20563e564ebSKumar Kartikeya DwivediThe KF_ACQUIRE flag is used to indicate that the kfunc returns a pointer to a 20663e564ebSKumar Kartikeya Dwivedirefcounted object. The verifier will then ensure that the pointer to the object 20763e564ebSKumar Kartikeya Dwivediis eventually released using a release kfunc, or transferred to a map using a 20863e564ebSKumar Kartikeya Dwivedireferenced kptr (by invoking bpf_kptr_xchg). If not, the verifier fails the 20963e564ebSKumar Kartikeya Dwivediloading of the BPF program until no lingering references remain in all possible 21063e564ebSKumar Kartikeya Dwivediexplored states of the program. 21163e564ebSKumar Kartikeya Dwivedi 21263e564ebSKumar Kartikeya Dwivedi2.4.2 KF_RET_NULL flag 21363e564ebSKumar Kartikeya Dwivedi---------------------- 21463e564ebSKumar Kartikeya Dwivedi 21563e564ebSKumar Kartikeya DwivediThe KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc 21663e564ebSKumar Kartikeya Dwivedimay be NULL. Hence, it forces the user to do a NULL check on the pointer 21763e564ebSKumar Kartikeya Dwivedireturned from the kfunc before making use of it (dereferencing or passing to 21863e564ebSKumar Kartikeya Dwivedianother helper). This flag is often used in pairing with KF_ACQUIRE flag, but 21963e564ebSKumar Kartikeya Dwivediboth are orthogonal to each other. 22063e564ebSKumar Kartikeya Dwivedi 22163e564ebSKumar Kartikeya Dwivedi2.4.3 KF_RELEASE flag 22263e564ebSKumar Kartikeya Dwivedi--------------------- 22363e564ebSKumar Kartikeya Dwivedi 22463e564ebSKumar Kartikeya DwivediThe KF_RELEASE flag is used to indicate that the kfunc releases the pointer 2256c831c46SDavid Vernetpassed in to it. There can be only one referenced pointer that can be passed 2266c831c46SDavid Vernetin. All copies of the pointer being released are invalidated as a result of 2276c831c46SDavid Vernetinvoking kfunc with this flag. KF_RELEASE kfuncs automatically receive the 2286c831c46SDavid Vernetprotection afforded by the KF_TRUSTED_ARGS flag described below. 22963e564ebSKumar Kartikeya Dwivedi 230530474e6SDavid Vernet2.4.4 KF_TRUSTED_ARGS flag 23163e564ebSKumar Kartikeya Dwivedi-------------------------- 23263e564ebSKumar Kartikeya Dwivedi 23363e564ebSKumar Kartikeya DwivediThe KF_TRUSTED_ARGS flag is used for kfuncs taking pointer arguments. It 2343f00c523SDavid Vernetindicates that the all pointer arguments are valid, and that all pointers to 2353f00c523SDavid VernetBTF objects have been passed in their unmodified form (that is, at a zero 236d94cbde2SDavid Vernetoffset, and without having been obtained from walking another pointer, with one 237d94cbde2SDavid Vernetexception described below). 238eed807f6SKumar Kartikeya Dwivedi 2393f00c523SDavid VernetThere are two types of pointers to kernel objects which are considered "valid": 240eed807f6SKumar Kartikeya Dwivedi 2413f00c523SDavid Vernet1. Pointers which are passed as tracepoint or struct_ops callback arguments. 242530474e6SDavid Vernet2. Pointers which were returned from a KF_ACQUIRE kfunc. 243eed807f6SKumar Kartikeya Dwivedi 2443f00c523SDavid VernetPointers to non-BTF objects (e.g. scalar pointers) may also be passed to 2453f00c523SDavid VernetKF_TRUSTED_ARGS kfuncs, and may have a non-zero offset. 2463f00c523SDavid Vernet 2473f00c523SDavid VernetThe definition of "valid" pointers is subject to change at any time, and has 2483f00c523SDavid Vernetabsolutely no ABI stability guarantees. 24963e564ebSKumar Kartikeya Dwivedi 250d94cbde2SDavid VernetAs mentioned above, a nested pointer obtained from walking a trusted pointer is 251d94cbde2SDavid Vernetno longer trusted, with one exception. If a struct type has a field that is 252fbc5669dSAnton Protopopovguaranteed to be valid (trusted or rcu, as in KF_RCU description below) as long 253fbc5669dSAnton Protopopovas its parent pointer is valid, the following macros can be used to express 254fbc5669dSAnton Protopopovthat to the verifier: 255fbc5669dSAnton Protopopov 256fbc5669dSAnton Protopopov* ``BTF_TYPE_SAFE_TRUSTED`` 257fbc5669dSAnton Protopopov* ``BTF_TYPE_SAFE_RCU`` 258fbc5669dSAnton Protopopov* ``BTF_TYPE_SAFE_RCU_OR_NULL`` 259fbc5669dSAnton Protopopov 260fbc5669dSAnton ProtopopovFor example, 261d94cbde2SDavid Vernet 262d94cbde2SDavid Vernet.. code-block:: c 263d94cbde2SDavid Vernet 264fbc5669dSAnton Protopopov BTF_TYPE_SAFE_TRUSTED(struct socket) { 265fbc5669dSAnton Protopopov struct sock *sk; 266fbc5669dSAnton Protopopov }; 267fbc5669dSAnton Protopopov 268fbc5669dSAnton Protopopovor 269fbc5669dSAnton Protopopov 270fbc5669dSAnton Protopopov.. code-block:: c 271fbc5669dSAnton Protopopov 272fbc5669dSAnton Protopopov BTF_TYPE_SAFE_RCU(struct task_struct) { 273d94cbde2SDavid Vernet const cpumask_t *cpus_ptr; 274fbc5669dSAnton Protopopov struct css_set __rcu *cgroups; 275fbc5669dSAnton Protopopov struct task_struct __rcu *real_parent; 276fbc5669dSAnton Protopopov struct task_struct *group_leader; 277d94cbde2SDavid Vernet }; 278d94cbde2SDavid Vernet 279d94cbde2SDavid VernetIn other words, you must: 280d94cbde2SDavid Vernet 281fbc5669dSAnton Protopopov1. Wrap the valid pointer type in a ``BTF_TYPE_SAFE_*`` macro. 282d94cbde2SDavid Vernet 283fbc5669dSAnton Protopopov2. Specify the type and name of the valid nested field. This field must match 284d94cbde2SDavid Vernet the field in the original type definition exactly. 285d94cbde2SDavid Vernet 286fbc5669dSAnton ProtopopovA new type declared by a ``BTF_TYPE_SAFE_*`` macro also needs to be emitted so 287fbc5669dSAnton Protopopovthat it appears in BTF. For example, ``BTF_TYPE_SAFE_TRUSTED(struct socket)`` 288fbc5669dSAnton Protopopovis emitted in the ``type_is_trusted()`` function as follows: 289fbc5669dSAnton Protopopov 290fbc5669dSAnton Protopopov.. code-block:: c 291fbc5669dSAnton Protopopov 292fbc5669dSAnton Protopopov BTF_TYPE_EMIT(BTF_TYPE_SAFE_TRUSTED(struct socket)); 293fbc5669dSAnton Protopopov 294fbc5669dSAnton Protopopov 295530474e6SDavid Vernet2.4.5 KF_SLEEPABLE flag 296fa96b242SBenjamin Tissoires----------------------- 297fa96b242SBenjamin Tissoires 298fa96b242SBenjamin TissoiresThe KF_SLEEPABLE flag is used for kfuncs that may sleep. Such kfuncs can only 299fa96b242SBenjamin Tissoiresbe called by sleepable BPF programs (BPF_F_SLEEPABLE). 300fa96b242SBenjamin Tissoires 301530474e6SDavid Vernet2.4.6 KF_DESTRUCTIVE flag 3024dd48c6fSArtem Savkov-------------------------- 3034dd48c6fSArtem Savkov 3044dd48c6fSArtem SavkovThe KF_DESTRUCTIVE flag is used to indicate functions calling which is 3054dd48c6fSArtem Savkovdestructive to the system. For example such a call can result in system 3064dd48c6fSArtem Savkovrebooting or panicking. Due to this additional restrictions apply to these 3074dd48c6fSArtem Savkovcalls. At the moment they only require CAP_SYS_BOOT capability, but more can be 3084dd48c6fSArtem Savkovadded later. 3094dd48c6fSArtem Savkov 310530474e6SDavid Vernet2.4.7 KF_RCU flag 311f5362564SYonghong Song----------------- 312f5362564SYonghong Song 31320c09d92SAlexei StarovoitovThe KF_RCU flag is a weaker version of KF_TRUSTED_ARGS. The kfuncs marked with 31420c09d92SAlexei StarovoitovKF_RCU expect either PTR_TRUSTED or MEM_RCU arguments. The verifier guarantees 31520c09d92SAlexei Starovoitovthat the objects are valid and there is no use-after-free. The pointers are not 31620c09d92SAlexei StarovoitovNULL, but the object's refcount could have reached zero. The kfuncs need to 31720c09d92SAlexei Starovoitovconsider doing refcnt != 0 check, especially when returning a KF_ACQUIRE 31820c09d92SAlexei Starovoitovpointer. Note as well that a KF_ACQUIRE kfunc that is KF_RCU should very likely 31920c09d92SAlexei Starovoitovalso be KF_RET_NULL. 320f5362564SYonghong Song 32116c294a6SDavid Vernet.. _KF_deprecated_flag: 32216c294a6SDavid Vernet 323530474e6SDavid Vernet2.4.8 KF_DEPRECATED flag 32416c294a6SDavid Vernet------------------------ 32516c294a6SDavid Vernet 32616c294a6SDavid VernetThe KF_DEPRECATED flag is used for kfuncs which are scheduled to be 32716c294a6SDavid Vernetchanged or removed in a subsequent kernel release. A kfunc that is 32816c294a6SDavid Vernetmarked with KF_DEPRECATED should also have any relevant information 32916c294a6SDavid Vernetcaptured in its kernel doc. Such information typically includes the 33016c294a6SDavid Vernetkfunc's expected remaining lifespan, a recommendation for new 33116c294a6SDavid Vernetfunctionality that can replace it if any is available, and possibly a 33216c294a6SDavid Vernetrationale for why it is being removed. 33316c294a6SDavid Vernet 33416c294a6SDavid VernetNote that while on some occasions, a KF_DEPRECATED kfunc may continue to be 33516c294a6SDavid Vernetsupported and have its KF_DEPRECATED flag removed, it is likely to be far more 33616c294a6SDavid Vernetdifficult to remove a KF_DEPRECATED flag after it's been added than it is to 33716c294a6SDavid Vernetprevent it from being added in the first place. As described in 33816c294a6SDavid Vernet:ref:`BPF_kfunc_lifecycle_expectations`, users that rely on specific kfuncs are 33916c294a6SDavid Vernetencouraged to make their use-cases known as early as possible, and participate 34016c294a6SDavid Vernetin upstream discussions regarding whether to keep, change, deprecate, or remove 34116c294a6SDavid Vernetthose kfuncs if and when such discussions occur. 34216c294a6SDavid Vernet 34363e564ebSKumar Kartikeya Dwivedi2.5 Registering the kfuncs 34463e564ebSKumar Kartikeya Dwivedi-------------------------- 34563e564ebSKumar Kartikeya Dwivedi 34663e564ebSKumar Kartikeya DwivediOnce the kfunc is prepared for use, the final step to making it visible is 34763e564ebSKumar Kartikeya Dwivediregistering it with the BPF subsystem. Registration is done per BPF program 34863e564ebSKumar Kartikeya Dwiveditype. An example is shown below:: 34963e564ebSKumar Kartikeya Dwivedi 350*6f3189f3SDaniel Xu BTF_KFUNCS_START(bpf_task_set) 35163e564ebSKumar Kartikeya Dwivedi BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL) 35263e564ebSKumar Kartikeya Dwivedi BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE) 353*6f3189f3SDaniel Xu BTF_KFUNCS_END(bpf_task_set) 35463e564ebSKumar Kartikeya Dwivedi 35563e564ebSKumar Kartikeya Dwivedi static const struct btf_kfunc_id_set bpf_task_kfunc_set = { 35663e564ebSKumar Kartikeya Dwivedi .owner = THIS_MODULE, 35763e564ebSKumar Kartikeya Dwivedi .set = &bpf_task_set, 35863e564ebSKumar Kartikeya Dwivedi }; 35963e564ebSKumar Kartikeya Dwivedi 36063e564ebSKumar Kartikeya Dwivedi static int init_subsystem(void) 36163e564ebSKumar Kartikeya Dwivedi { 36263e564ebSKumar Kartikeya Dwivedi return register_btf_kfunc_id_set(BPF_PROG_TYPE_TRACING, &bpf_task_kfunc_set); 36363e564ebSKumar Kartikeya Dwivedi } 36463e564ebSKumar Kartikeya Dwivedi late_initcall(init_subsystem); 36525c5e92dSDavid Vernet 366027bdec8SDavid Vernet2.6 Specifying no-cast aliases with ___init 367027bdec8SDavid Vernet-------------------------------------------- 368027bdec8SDavid Vernet 369027bdec8SDavid VernetThe verifier will always enforce that the BTF type of a pointer passed to a 370027bdec8SDavid Vernetkfunc by a BPF program, matches the type of pointer specified in the kfunc 371027bdec8SDavid Vernetdefinition. The verifier, does, however, allow types that are equivalent 372027bdec8SDavid Vernetaccording to the C standard to be passed to the same kfunc arg, even if their 373027bdec8SDavid VernetBTF_IDs differ. 374027bdec8SDavid Vernet 375027bdec8SDavid VernetFor example, for the following type definition: 376027bdec8SDavid Vernet 377027bdec8SDavid Vernet.. code-block:: c 378027bdec8SDavid Vernet 379027bdec8SDavid Vernet struct bpf_cpumask { 380027bdec8SDavid Vernet cpumask_t cpumask; 381027bdec8SDavid Vernet refcount_t usage; 382027bdec8SDavid Vernet }; 383027bdec8SDavid Vernet 384027bdec8SDavid VernetThe verifier would allow a ``struct bpf_cpumask *`` to be passed to a kfunc 385027bdec8SDavid Vernettaking a ``cpumask_t *`` (which is a typedef of ``struct cpumask *``). For 386027bdec8SDavid Vernetinstance, both ``struct cpumask *`` and ``struct bpf_cpmuask *`` can be passed 387027bdec8SDavid Vernetto bpf_cpumask_test_cpu(). 388027bdec8SDavid Vernet 389027bdec8SDavid VernetIn some cases, this type-aliasing behavior is not desired. ``struct 390027bdec8SDavid Vernetnf_conn___init`` is one such example: 391027bdec8SDavid Vernet 392027bdec8SDavid Vernet.. code-block:: c 393027bdec8SDavid Vernet 394027bdec8SDavid Vernet struct nf_conn___init { 395027bdec8SDavid Vernet struct nf_conn ct; 396027bdec8SDavid Vernet }; 397027bdec8SDavid Vernet 398027bdec8SDavid VernetThe C standard would consider these types to be equivalent, but it would not 399027bdec8SDavid Vernetalways be safe to pass either type to a trusted kfunc. ``struct 400027bdec8SDavid Vernetnf_conn___init`` represents an allocated ``struct nf_conn`` object that has 401027bdec8SDavid Vernet*not yet been initialized*, so it would therefore be unsafe to pass a ``struct 402027bdec8SDavid Vernetnf_conn___init *`` to a kfunc that's expecting a fully initialized ``struct 403027bdec8SDavid Vernetnf_conn *`` (e.g. ``bpf_ct_change_timeout()``). 404027bdec8SDavid Vernet 405027bdec8SDavid VernetIn order to accommodate such requirements, the verifier will enforce strict 406027bdec8SDavid VernetPTR_TO_BTF_ID type matching if two types have the exact same name, with one 407027bdec8SDavid Vernetbeing suffixed with ``___init``. 408027bdec8SDavid Vernet 40916c294a6SDavid Vernet.. _BPF_kfunc_lifecycle_expectations: 41016c294a6SDavid Vernet 41116c294a6SDavid Vernet3. kfunc lifecycle expectations 41216c294a6SDavid Vernet=============================== 41316c294a6SDavid Vernet 41416c294a6SDavid Vernetkfuncs provide a kernel <-> kernel API, and thus are not bound by any of the 41516c294a6SDavid Vernetstrict stability restrictions associated with kernel <-> user UAPIs. This means 41616c294a6SDavid Vernetthey can be thought of as similar to EXPORT_SYMBOL_GPL, and can therefore be 41716c294a6SDavid Vernetmodified or removed by a maintainer of the subsystem they're defined in when 41816c294a6SDavid Vernetit's deemed necessary. 41916c294a6SDavid Vernet 42016c294a6SDavid VernetLike any other change to the kernel, maintainers will not change or remove a 42116c294a6SDavid Vernetkfunc without having a reasonable justification. Whether or not they'll choose 42216c294a6SDavid Vernetto change a kfunc will ultimately depend on a variety of factors, such as how 42316c294a6SDavid Vernetwidely used the kfunc is, how long the kfunc has been in the kernel, whether an 42416c294a6SDavid Vernetalternative kfunc exists, what the norm is in terms of stability for the 42516c294a6SDavid Vernetsubsystem in question, and of course what the technical cost is of continuing 42616c294a6SDavid Vernetto support the kfunc. 42716c294a6SDavid Vernet 42816c294a6SDavid VernetThere are several implications of this: 42916c294a6SDavid Vernet 43016c294a6SDavid Verneta) kfuncs that are widely used or have been in the kernel for a long time will 43116c294a6SDavid Vernet be more difficult to justify being changed or removed by a maintainer. In 43216c294a6SDavid Vernet other words, kfuncs that are known to have a lot of users and provide 43316c294a6SDavid Vernet significant value provide stronger incentives for maintainers to invest the 43416c294a6SDavid Vernet time and complexity in supporting them. It is therefore important for 43516c294a6SDavid Vernet developers that are using kfuncs in their BPF programs to communicate and 43616c294a6SDavid Vernet explain how and why those kfuncs are being used, and to participate in 43716c294a6SDavid Vernet discussions regarding those kfuncs when they occur upstream. 43816c294a6SDavid Vernet 43916c294a6SDavid Vernetb) Unlike regular kernel symbols marked with EXPORT_SYMBOL_GPL, BPF programs 44016c294a6SDavid Vernet that call kfuncs are generally not part of the kernel tree. This means that 44116c294a6SDavid Vernet refactoring cannot typically change callers in-place when a kfunc changes, 44216c294a6SDavid Vernet as is done for e.g. an upstreamed driver being updated in place when a 44316c294a6SDavid Vernet kernel symbol is changed. 44416c294a6SDavid Vernet 44516c294a6SDavid Vernet Unlike with regular kernel symbols, this is expected behavior for BPF 44616c294a6SDavid Vernet symbols, and out-of-tree BPF programs that use kfuncs should be considered 44716c294a6SDavid Vernet relevant to discussions and decisions around modifying and removing those 44816c294a6SDavid Vernet kfuncs. The BPF community will take an active role in participating in 44916c294a6SDavid Vernet upstream discussions when necessary to ensure that the perspectives of such 45016c294a6SDavid Vernet users are taken into account. 45116c294a6SDavid Vernet 45216c294a6SDavid Vernetc) A kfunc will never have any hard stability guarantees. BPF APIs cannot and 45316c294a6SDavid Vernet will not ever hard-block a change in the kernel purely for stability 45416c294a6SDavid Vernet reasons. That being said, kfuncs are features that are meant to solve 45516c294a6SDavid Vernet problems and provide value to users. The decision of whether to change or 45616c294a6SDavid Vernet remove a kfunc is a multivariate technical decision that is made on a 45716c294a6SDavid Vernet case-by-case basis, and which is informed by data points such as those 45816c294a6SDavid Vernet mentioned above. It is expected that a kfunc being removed or changed with 45916c294a6SDavid Vernet no warning will not be a common occurrence or take place without sound 46016c294a6SDavid Vernet justification, but it is a possibility that must be accepted if one is to 46116c294a6SDavid Vernet use kfuncs. 46216c294a6SDavid Vernet 46316c294a6SDavid Vernet3.1 kfunc deprecation 46416c294a6SDavid Vernet--------------------- 46516c294a6SDavid Vernet 46616c294a6SDavid VernetAs described above, while sometimes a maintainer may find that a kfunc must be 46716c294a6SDavid Vernetchanged or removed immediately to accommodate some changes in their subsystem, 46816c294a6SDavid Vernetusually kfuncs will be able to accommodate a longer and more measured 46916c294a6SDavid Vernetdeprecation process. For example, if a new kfunc comes along which provides 47016c294a6SDavid Vernetsuperior functionality to an existing kfunc, the existing kfunc may be 47116c294a6SDavid Vernetdeprecated for some period of time to allow users to migrate their BPF programs 47216c294a6SDavid Vernetto use the new one. Or, if a kfunc has no known users, a decision may be made 47316c294a6SDavid Vernetto remove the kfunc (without providing an alternative API) after some 47416c294a6SDavid Vernetdeprecation period so as to provide users with a window to notify the kfunc 47516c294a6SDavid Vernetmaintainer if it turns out that the kfunc is actually being used. 47616c294a6SDavid Vernet 47716c294a6SDavid VernetIt's expected that the common case will be that kfuncs will go through a 47816c294a6SDavid Vernetdeprecation period rather than being changed or removed without warning. As 47916c294a6SDavid Vernetdescribed in :ref:`KF_deprecated_flag`, the kfunc framework provides the 48016c294a6SDavid VernetKF_DEPRECATED flag to kfunc developers to signal to users that a kfunc has been 48116c294a6SDavid Vernetdeprecated. Once a kfunc has been marked with KF_DEPRECATED, the following 48216c294a6SDavid Vernetprocedure is followed for removal: 48316c294a6SDavid Vernet 48416c294a6SDavid Vernet1. Any relevant information for deprecated kfuncs is documented in the kfunc's 48516c294a6SDavid Vernet kernel docs. This documentation will typically include the kfunc's expected 48616c294a6SDavid Vernet remaining lifespan, a recommendation for new functionality that can replace 48716c294a6SDavid Vernet the usage of the deprecated function (or an explanation as to why no such 48816c294a6SDavid Vernet replacement exists), etc. 48916c294a6SDavid Vernet 49016c294a6SDavid Vernet2. The deprecated kfunc is kept in the kernel for some period of time after it 49116c294a6SDavid Vernet was first marked as deprecated. This time period will be chosen on a 49216c294a6SDavid Vernet case-by-case basis, and will typically depend on how widespread the use of 49316c294a6SDavid Vernet the kfunc is, how long it has been in the kernel, and how hard it is to move 49416c294a6SDavid Vernet to alternatives. This deprecation time period is "best effort", and as 49516c294a6SDavid Vernet described :ref:`above<BPF_kfunc_lifecycle_expectations>`, circumstances may 49616c294a6SDavid Vernet sometimes dictate that the kfunc be removed before the full intended 49716c294a6SDavid Vernet deprecation period has elapsed. 49816c294a6SDavid Vernet 49916c294a6SDavid Vernet3. After the deprecation period the kfunc will be removed. At this point, BPF 50016c294a6SDavid Vernet programs calling the kfunc will be rejected by the verifier. 50116c294a6SDavid Vernet 50216c294a6SDavid Vernet4. Core kfuncs 50325c5e92dSDavid Vernet============== 50425c5e92dSDavid Vernet 50525c5e92dSDavid VernetThe BPF subsystem provides a number of "core" kfuncs that are potentially 50625c5e92dSDavid Vernetapplicable to a wide variety of different possible use cases and programs. 50725c5e92dSDavid VernetThose kfuncs are documented here. 50825c5e92dSDavid Vernet 50916c294a6SDavid Vernet4.1 struct task_struct * kfuncs 51025c5e92dSDavid Vernet------------------------------- 51125c5e92dSDavid Vernet 51225c5e92dSDavid VernetThere are a number of kfuncs that allow ``struct task_struct *`` objects to be 51325c5e92dSDavid Vernetused as kptrs: 51425c5e92dSDavid Vernet 51525c5e92dSDavid Vernet.. kernel-doc:: kernel/bpf/helpers.c 51625c5e92dSDavid Vernet :identifiers: bpf_task_acquire bpf_task_release 51725c5e92dSDavid Vernet 51825c5e92dSDavid VernetThese kfuncs are useful when you want to acquire or release a reference to a 51925c5e92dSDavid Vernet``struct task_struct *`` that was passed as e.g. a tracepoint arg, or a 52025c5e92dSDavid Vernetstruct_ops callback arg. For example: 52125c5e92dSDavid Vernet 52225c5e92dSDavid Vernet.. code-block:: c 52325c5e92dSDavid Vernet 52425c5e92dSDavid Vernet /** 52525c5e92dSDavid Vernet * A trivial example tracepoint program that shows how to 52625c5e92dSDavid Vernet * acquire and release a struct task_struct * pointer. 52725c5e92dSDavid Vernet */ 52825c5e92dSDavid Vernet SEC("tp_btf/task_newtask") 52925c5e92dSDavid Vernet int BPF_PROG(task_acquire_release_example, struct task_struct *task, u64 clone_flags) 53025c5e92dSDavid Vernet { 53125c5e92dSDavid Vernet struct task_struct *acquired; 53225c5e92dSDavid Vernet 53325c5e92dSDavid Vernet acquired = bpf_task_acquire(task); 534db9d479aSDavid Vernet if (acquired) 53525c5e92dSDavid Vernet /* 53625c5e92dSDavid Vernet * In a typical program you'd do something like store 53725c5e92dSDavid Vernet * the task in a map, and the map will automatically 53825c5e92dSDavid Vernet * release it later. Here, we release it manually. 53925c5e92dSDavid Vernet */ 54025c5e92dSDavid Vernet bpf_task_release(acquired); 54125c5e92dSDavid Vernet return 0; 54225c5e92dSDavid Vernet } 54325c5e92dSDavid Vernet 544db9d479aSDavid Vernet 545db9d479aSDavid VernetReferences acquired on ``struct task_struct *`` objects are RCU protected. 546db9d479aSDavid VernetTherefore, when in an RCU read region, you can obtain a pointer to a task 547db9d479aSDavid Vernetembedded in a map value without having to acquire a reference: 548db9d479aSDavid Vernet 549db9d479aSDavid Vernet.. code-block:: c 550db9d479aSDavid Vernet 551db9d479aSDavid Vernet #define private(name) SEC(".data." #name) __hidden __attribute__((aligned(8))) 552db9d479aSDavid Vernet private(TASK) static struct task_struct *global; 553db9d479aSDavid Vernet 554db9d479aSDavid Vernet /** 555db9d479aSDavid Vernet * A trivial example showing how to access a task stored 556db9d479aSDavid Vernet * in a map using RCU. 557db9d479aSDavid Vernet */ 558db9d479aSDavid Vernet SEC("tp_btf/task_newtask") 559db9d479aSDavid Vernet int BPF_PROG(task_rcu_read_example, struct task_struct *task, u64 clone_flags) 560db9d479aSDavid Vernet { 561db9d479aSDavid Vernet struct task_struct *local_copy; 562db9d479aSDavid Vernet 563db9d479aSDavid Vernet bpf_rcu_read_lock(); 564db9d479aSDavid Vernet local_copy = global; 565db9d479aSDavid Vernet if (local_copy) 566db9d479aSDavid Vernet /* 567db9d479aSDavid Vernet * We could also pass local_copy to kfuncs or helper functions here, 568db9d479aSDavid Vernet * as we're guaranteed that local_copy will be valid until we exit 569db9d479aSDavid Vernet * the RCU read region below. 570db9d479aSDavid Vernet */ 571db9d479aSDavid Vernet bpf_printk("Global task %s is valid", local_copy->comm); 572db9d479aSDavid Vernet else 573db9d479aSDavid Vernet bpf_printk("No global task found"); 574db9d479aSDavid Vernet bpf_rcu_read_unlock(); 575db9d479aSDavid Vernet 576db9d479aSDavid Vernet /* At this point we can no longer reference local_copy. */ 577db9d479aSDavid Vernet 578db9d479aSDavid Vernet return 0; 579db9d479aSDavid Vernet } 580db9d479aSDavid Vernet 58125c5e92dSDavid Vernet---- 58225c5e92dSDavid Vernet 58325c5e92dSDavid VernetA BPF program can also look up a task from a pid. This can be useful if the 58425c5e92dSDavid Vernetcaller doesn't have a trusted pointer to a ``struct task_struct *`` object that 58525c5e92dSDavid Vernetit can acquire a reference on with bpf_task_acquire(). 58625c5e92dSDavid Vernet 58725c5e92dSDavid Vernet.. kernel-doc:: kernel/bpf/helpers.c 58825c5e92dSDavid Vernet :identifiers: bpf_task_from_pid 58925c5e92dSDavid Vernet 59025c5e92dSDavid VernetHere is an example of it being used: 59125c5e92dSDavid Vernet 59225c5e92dSDavid Vernet.. code-block:: c 59325c5e92dSDavid Vernet 59425c5e92dSDavid Vernet SEC("tp_btf/task_newtask") 59525c5e92dSDavid Vernet int BPF_PROG(task_get_pid_example, struct task_struct *task, u64 clone_flags) 59625c5e92dSDavid Vernet { 59725c5e92dSDavid Vernet struct task_struct *lookup; 59825c5e92dSDavid Vernet 59925c5e92dSDavid Vernet lookup = bpf_task_from_pid(task->pid); 60025c5e92dSDavid Vernet if (!lookup) 60125c5e92dSDavid Vernet /* A task should always be found, as %task is a tracepoint arg. */ 60225c5e92dSDavid Vernet return -ENOENT; 60325c5e92dSDavid Vernet 60425c5e92dSDavid Vernet if (lookup->pid != task->pid) { 60525c5e92dSDavid Vernet /* bpf_task_from_pid() looks up the task via its 60625c5e92dSDavid Vernet * globally-unique pid from the init_pid_ns. Thus, 60725c5e92dSDavid Vernet * the pid of the lookup task should always be the 60825c5e92dSDavid Vernet * same as the input task. 60925c5e92dSDavid Vernet */ 61025c5e92dSDavid Vernet bpf_task_release(lookup); 61125c5e92dSDavid Vernet return -EINVAL; 61225c5e92dSDavid Vernet } 61325c5e92dSDavid Vernet 61425c5e92dSDavid Vernet /* bpf_task_from_pid() returns an acquired reference, 61525c5e92dSDavid Vernet * so it must be dropped before returning from the 61625c5e92dSDavid Vernet * tracepoint handler. 61725c5e92dSDavid Vernet */ 61825c5e92dSDavid Vernet bpf_task_release(lookup); 61925c5e92dSDavid Vernet return 0; 62025c5e92dSDavid Vernet } 62136aa10ffSDavid Vernet 62216c294a6SDavid Vernet4.2 struct cgroup * kfuncs 62336aa10ffSDavid Vernet-------------------------- 62436aa10ffSDavid Vernet 62536aa10ffSDavid Vernet``struct cgroup *`` objects also have acquire and release functions: 62636aa10ffSDavid Vernet 62736aa10ffSDavid Vernet.. kernel-doc:: kernel/bpf/helpers.c 62836aa10ffSDavid Vernet :identifiers: bpf_cgroup_acquire bpf_cgroup_release 62936aa10ffSDavid Vernet 63036aa10ffSDavid VernetThese kfuncs are used in exactly the same manner as bpf_task_acquire() and 63136aa10ffSDavid Vernetbpf_task_release() respectively, so we won't provide examples for them. 63236aa10ffSDavid Vernet 63336aa10ffSDavid Vernet---- 63436aa10ffSDavid Vernet 635332ea1f6STejun HeoOther kfuncs available for interacting with ``struct cgroup *`` objects are 636332ea1f6STejun Heobpf_cgroup_ancestor() and bpf_cgroup_from_id(), allowing callers to access 637332ea1f6STejun Heothe ancestor of a cgroup and find a cgroup by its ID, respectively. Both 638332ea1f6STejun Heoreturn a cgroup kptr. 63936aa10ffSDavid Vernet 64036aa10ffSDavid Vernet.. kernel-doc:: kernel/bpf/helpers.c 64136aa10ffSDavid Vernet :identifiers: bpf_cgroup_ancestor 64236aa10ffSDavid Vernet 643332ea1f6STejun Heo.. kernel-doc:: kernel/bpf/helpers.c 644332ea1f6STejun Heo :identifiers: bpf_cgroup_from_id 645332ea1f6STejun Heo 64636aa10ffSDavid VernetEventually, BPF should be updated to allow this to happen with a normal memory 64736aa10ffSDavid Vernetload in the program itself. This is currently not possible without more work in 64836aa10ffSDavid Vernetthe verifier. bpf_cgroup_ancestor() can be used as follows: 64936aa10ffSDavid Vernet 65036aa10ffSDavid Vernet.. code-block:: c 65136aa10ffSDavid Vernet 65236aa10ffSDavid Vernet /** 65336aa10ffSDavid Vernet * Simple tracepoint example that illustrates how a cgroup's 65436aa10ffSDavid Vernet * ancestor can be accessed using bpf_cgroup_ancestor(). 65536aa10ffSDavid Vernet */ 65636aa10ffSDavid Vernet SEC("tp_btf/cgroup_mkdir") 65736aa10ffSDavid Vernet int BPF_PROG(cgrp_ancestor_example, struct cgroup *cgrp, const char *path) 65836aa10ffSDavid Vernet { 65936aa10ffSDavid Vernet struct cgroup *parent; 66036aa10ffSDavid Vernet 66136aa10ffSDavid Vernet /* The parent cgroup resides at the level before the current cgroup's level. */ 66236aa10ffSDavid Vernet parent = bpf_cgroup_ancestor(cgrp, cgrp->level - 1); 66336aa10ffSDavid Vernet if (!parent) 66436aa10ffSDavid Vernet return -ENOENT; 66536aa10ffSDavid Vernet 66636aa10ffSDavid Vernet bpf_printk("Parent id is %d", parent->self.id); 66736aa10ffSDavid Vernet 66836aa10ffSDavid Vernet /* Return the parent cgroup that was acquired above. */ 66936aa10ffSDavid Vernet bpf_cgroup_release(parent); 67036aa10ffSDavid Vernet return 0; 67136aa10ffSDavid Vernet } 672bdbda395SDavid Vernet 67316c294a6SDavid Vernet4.3 struct cpumask * kfuncs 674bdbda395SDavid Vernet--------------------------- 675bdbda395SDavid Vernet 676bdbda395SDavid VernetBPF provides a set of kfuncs that can be used to query, allocate, mutate, and 677bdbda395SDavid Vernetdestroy struct cpumask * objects. Please refer to :ref:`cpumasks-header-label` 678bdbda395SDavid Vernetfor more details. 679