Lines Matching +full:as +full:- +full:is
1 .. SPDX-License-Identifier: GPL-2.0
3 .. _kfuncs-header-label:
12 BPF Kernel Functions or more commonly known as kfuncs are functions in the Linux
30 ----------------------------
33 This prevents the compiler from optimizing away dead code, as this wrapper kfunc
34 is not invoked anywhere in the kernel itself. It is not necessary to provide a
37 An example is given below::
49 A wrapper kfunc is often needed when we need to annotate parameters of the
54 -------------------------------
56 Similar to BPF helpers, there is sometime need for additional context required
62 ---------------------
64 This annotation is used to indicate a memory and size pair in the argument list.
65 An example is given below::
72 Here, the verifier will treat first argument as a PTR_TO_MEM, and second
73 argument as its size. By default, without __sz annotation, the size of the type
74 of the pointer is used. Without __sz annotation, a kfunc cannot accept a void
78 --------------------
80 This annotation is only understood for scalar arguments, where it indicates that
82 not indicate a size parameter, and the value of the constant is relevant to the
85 An example is given below::
94 distinct size, hence it is crucial to treat each such call as distinct when
97 Hence, whenever a constant scalar argument is accepted by a kfunc which is not a
102 -------------------------
104 This annotation is used to indicate that the argument will be treated as
107 An example is given below::
114 Here, the dynptr will be treated as an uninitialized dynptr. Without this
115 annotation, the verifier will reject the program if the dynptr passed in is
119 -------------------------
121 This annotation is used to indicate that the buffer associated with an __sz or __szk
122 argument may be null. If the function is passed a nullptr in place of the buffer,
123 the verifier will not check that length is appropriate for the buffer. The kfunc is
124 responsible for checking if this buffer is null before using it.
126 An example is given below::
133 Here, the buffer may be null. If buffer is not null, it at least of size buffer_szk.
134 Either way, the returned buffer is either NULL, or of size buffer_szk. Without this
135 annotation, the verifier will reject the program if a null pointer is passed in with
139 ----------------------------
140 This annotation is used to indicate that the argument is a constant string.
142 An example is given below::
149 In this case, ``bpf_get_file_xattr()`` can be called as::
166 -------------------------------------
168 When an existing function in the kernel is fit for consumption by BPF programs,
171 and whether it is safe to do so.
174 ---------------------
178 flags on a set of kfuncs as follows::
186 along with it. Ofcourse, it is also allowed to specify no flags.
189 macro. This prevents issues such as the compiler inlining the kfunc if it's a
190 static kernel function, or the function being elided in an LTO build as it's
192 annotations to their kfunc to prevent these issues. If an annotation is
193 required to prevent such an issue with your kfunc, it is a bug and should be
195 protected. An example is given below::
203 ---------------------
205 The KF_ACQUIRE flag is used to indicate that the kfunc returns a pointer to a
207 is eventually released using a release kfunc, or transferred to a map using a
213 ----------------------
215 The KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc
218 another helper). This flag is often used in pairing with KF_ACQUIRE flag, but
222 ---------------------
224 The KF_RELEASE flag is used to indicate that the kfunc releases the pointer
226 in. All copies of the pointer being released are invalidated as a result of
231 --------------------------
233 The KF_TRUSTED_ARGS flag is used for kfuncs taking pointer arguments. It
235 BTF objects have been passed in their unmodified form (that is, at a zero
241 1. Pointers which are passed as tracepoint or struct_ops callback arguments.
244 Pointers to non-BTF objects (e.g. scalar pointers) may also be passed to
245 KF_TRUSTED_ARGS kfuncs, and may have a non-zero offset.
247 The definition of "valid" pointers is subject to change at any time, and has
250 As mentioned above, a nested pointer obtained from walking a trusted pointer is
251 no longer trusted, with one exception. If a struct type has a field that is
252 guaranteed to be valid (trusted or rcu, as in KF_RCU description below) as long
253 as its parent pointer is valid, the following macros can be used to express
262 .. code-block:: c
270 .. code-block:: c
288 is emitted in the ``type_is_trusted()`` function as follows:
290 .. code-block:: c
296 -----------------------
298 The KF_SLEEPABLE flag is used for kfuncs that may sleep. Such kfuncs can only
302 --------------------------
304 The KF_DESTRUCTIVE flag is used to indicate functions calling which is
311 -----------------
313 The KF_RCU flag is a weaker version of KF_TRUSTED_ARGS. The kfuncs marked with
315 that the objects are valid and there is no use-after-free. The pointers are not
318 pointer. Note as well that a KF_ACQUIRE kfunc that is KF_RCU should very likely
324 ------------------------
326 The KF_DEPRECATED flag is used for kfuncs which are scheduled to be
327 changed or removed in a subsequent kernel release. A kfunc that is
331 functionality that can replace it if any is available, and possibly a
332 rationale for why it is being removed.
335 supported and have its KF_DEPRECATED flag removed, it is likely to be far more
336 difficult to remove a KF_DEPRECATED flag after it's been added than it is to
337 prevent it from being added in the first place. As described in
339 encouraged to make their use-cases known as early as possible, and participate
344 --------------------------
346 Once the kfunc is prepared for use, the final step to making it visible is
347 registering it with the BPF subsystem. Registration is done per BPF program
348 type. An example is shown below::
366 2.6 Specifying no-cast aliases with ___init
367 --------------------------------------------
377 .. code-block:: c
385 taking a ``cpumask_t *`` (which is a typedef of ``struct cpumask *``). For
389 In some cases, this type-aliasing behavior is not desired. ``struct
390 nf_conn___init`` is one such example:
392 .. code-block:: c
414 kfuncs provide a kernel <-> kernel API, and thus are not bound by any of the
415 strict stability restrictions associated with kernel <-> user UAPIs. This means
416 they can be thought of as similar to EXPORT_SYMBOL_GPL, and can therefore be
422 to change a kfunc will ultimately depend on a variety of factors, such as how
423 widely used the kfunc is, how long the kfunc has been in the kernel, whether an
424 alternative kfunc exists, what the norm is in terms of stability for the
425 subsystem in question, and of course what the technical cost is of continuing
434 time and complexity in supporting them. It is therefore important for
441 refactoring cannot typically change callers in-place when a kfunc changes,
442 as is done for e.g. an upstreamed driver being updated in place when a
443 kernel symbol is changed.
445 Unlike with regular kernel symbols, this is expected behavior for BPF
446 symbols, and out-of-tree BPF programs that use kfuncs should be considered
453 will not ever hard-block a change in the kernel purely for stability
456 remove a kfunc is a multivariate technical decision that is made on a
457 case-by-case basis, and which is informed by data points such as those
458 mentioned above. It is expected that a kfunc being removed or changed with
460 justification, but it is a possibility that must be accepted if one is to
464 ---------------------
466 As described above, while sometimes a maintainer may find that a kfunc must be
474 deprecation period so as to provide users with a window to notify the kfunc
475 maintainer if it turns out that the kfunc is actually being used.
478 deprecation period rather than being changed or removed without warning. As
482 procedure is followed for removal:
484 1. Any relevant information for deprecated kfuncs is documented in the kfunc's
487 the usage of the deprecated function (or an explanation as to why no such
490 2. The deprecated kfunc is kept in the kernel for some period of time after it
491 was first marked as deprecated. This time period will be chosen on a
492 case-by-case basis, and will typically depend on how widespread the use of
493 the kfunc is, how long it has been in the kernel, and how hard it is to move
494 to alternatives. This deprecation time period is "best effort", and as
510 -------------------------------
513 used as kptrs:
515 .. kernel-doc:: kernel/bpf/helpers.c
519 ``struct task_struct *`` that was passed as e.g. a tracepoint arg, or a
522 .. code-block:: c
549 .. code-block:: c
568 * as we're guaranteed that local_copy will be valid until we exit
571 bpf_printk("Global task %s is valid", local_copy->comm);
581 ----
587 .. kernel-doc:: kernel/bpf/helpers.c
590 Here is an example of it being used:
592 .. code-block:: c
599 lookup = bpf_task_from_pid(task->pid);
601 /* A task should always be found, as %task is a tracepoint arg. */
602 return -ENOENT;
604 if (lookup->pid != task->pid) {
606 * globally-unique pid from the init_pid_ns. Thus,
608 * same as the input task.
611 return -EINVAL;
623 --------------------------
627 .. kernel-doc:: kernel/bpf/helpers.c
630 These kfuncs are used in exactly the same manner as bpf_task_acquire() and
633 ----
640 .. kernel-doc:: kernel/bpf/helpers.c
643 .. kernel-doc:: kernel/bpf/helpers.c
647 load in the program itself. This is currently not possible without more work in
648 the verifier. bpf_cgroup_ancestor() can be used as follows:
650 .. code-block:: c
662 parent = bpf_cgroup_ancestor(cgrp, cgrp->level - 1);
664 return -ENOENT;
666 bpf_printk("Parent id is %d", parent->self.id);
674 ---------------------------
677 destroy struct cpumask * objects. Please refer to :ref:`cpumasks-header-label`