Lines Matching +full:- +full:a +full:-
1 .. SPDX-License-Identifier: GPL-2.0
3 .. _kfuncs-header-label:
14 kfuncs do not have a stable interface and can change from one kernel release to
18 2. Defining a kfunc
21 There are two ways to expose a kernel function to BPF programs, either make an
22 existing function in the kernel visible, or add a new wrapper for BPF. In both
23 cases, care must be taken that BPF program can only call such function in a
24 valid context. To enforce this, visibility of a kfunc can be per program type.
26 If you are not creating a BPF wrapper for existing kernel function, skip ahead
29 2.1 Creating a wrapper kfunc
30 ----------------------------
32 When defining a wrapper kfunc, the wrapper function should have extern linkage.
34 is not invoked anywhere in the kernel itself. It is not necessary to provide a
35 prototype in a header for the wrapper kfunc.
49 A wrapper kfunc is often needed when we need to annotate parameters of the
54 -------------------------------
58 Hence, we can annotate a parameter by suffixing the name of the argument of the
59 kfunc with a __tag, where tag may be one of the supported annotations.
62 ---------------------
64 This annotation is used to indicate a memory and size pair in the argument list.
72 Here, the verifier will treat first argument as a PTR_TO_MEM, and second
74 of the pointer is used. Without __sz annotation, a kfunc cannot accept a void
78 --------------------
81 the verifier must check the scalar argument to be a known constant, which does
82 not indicate a size parameter, and the value of the constant is relevant to the
93 ID in program's BTF and return a sized pointer to it. Each type ID will have a
97 Hence, whenever a constant scalar argument is accepted by a kfunc which is not a
102 -------------------------
119 -------------------------
122 argument may be null. If the function is passed a nullptr in place of the buffer,
135 annotation, the verifier will reject the program if a null pointer is passed in with
136 a nonzero size.
139 ----------------------------
140 This annotation is used to indicate that the argument is a constant string.
166 -------------------------------------
174 ---------------------
178 flags on a set of kfuncs as follows::
189 macro. This prevents issues such as the compiler inlining the kfunc if it's a
193 required to prevent such an issue with your kfunc, it is a bug and should be
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 ----------------------
216 may be NULL. Hence, it forces the user to do a NULL check on the pointer
222 ---------------------
226 in. All copies of the pointer being released are invalidated as a result of
231 --------------------------
235 BTF objects have been passed in their unmodified form (that is, at a zero
242 2. Pointers which were returned from a KF_ACQUIRE kfunc.
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.
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
262 .. code-block:: c
270 .. code-block:: c
281 1. Wrap the valid pointer type in a ``BTF_TYPE_SAFE_*`` macro.
286 A new type declared by a ``BTF_TYPE_SAFE_*`` macro also needs to be emitted so
290 .. code-block:: c
296 -----------------------
302 --------------------------
305 destructive to the system. For example such a call can result in system
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
317 consider doing refcnt != 0 check, especially when returning a KF_ACQUIRE
318 pointer. Note as well that a KF_ACQUIRE kfunc that is KF_RCU should very likely
324 ------------------------
327 changed or removed in a subsequent kernel release. A kfunc that is
330 kfunc's expected remaining lifespan, a recommendation for new
331 functionality that can replace it if any is available, and possibly a
334 Note that while on some occasions, a KF_DEPRECATED kfunc may continue to be
336 difficult to remove a KF_DEPRECATED flag after it's been added than it is to
339 encouraged to make their use-cases known as early as possible, and participate
344 --------------------------
366 2.6 Specifying no-cast aliases with ___init
367 --------------------------------------------
369 The verifier will always enforce that the BTF type of a pointer passed to a
370 kfunc by a BPF program, matches the type of pointer specified in the kfunc
377 .. code-block:: c
384 The verifier would allow a ``struct bpf_cpumask *`` to be passed to a kfunc
385 taking a ``cpumask_t *`` (which is a typedef of ``struct cpumask *``). For
389 In some cases, this type-aliasing behavior is not desired. ``struct
392 .. code-block:: c
399 always be safe to pass either type to a trusted kfunc. ``struct
401 *not yet been initialized*, so it would therefore be unsafe to pass a ``struct
402 nf_conn___init *`` to a kfunc that's expecting a fully initialized ``struct
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
417 modified or removed by a maintainer of the subsystem they're defined in when
420 Like any other change to the kernel, maintainers will not change or remove a
421 kfunc without having a reasonable justification. Whether or not they'll choose
422 to change a kfunc will ultimately depend on a variety of factors, such as how
430 a) kfuncs that are widely used or have been in the kernel for a long time will
431 be more difficult to justify being changed or removed by a maintainer. In
432 other words, kfuncs that are known to have a lot of users and provide
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
446 symbols, and out-of-tree BPF programs that use kfuncs should be considered
452 c) A kfunc will never have any hard stability guarantees. BPF APIs cannot and
453 will not ever hard-block a change in the kernel purely for stability
456 remove a kfunc is a multivariate technical decision that is made on a
457 case-by-case basis, and which is informed by data points such as those
458 mentioned above. It is expected that a kfunc being removed or changed with
459 no warning will not be a common occurrence or take place without sound
460 justification, but it is a possibility that must be accepted if one is to
464 ---------------------
466 As described above, while sometimes a maintainer may find that a kfunc must be
468 usually kfuncs will be able to accommodate a longer and more measured
469 deprecation process. For example, if a new kfunc comes along which provides
472 to use the new one. Or, if a kfunc has no known users, a decision may be made
474 deprecation period so as to provide users with a window to notify the kfunc
477 It's expected that the common case will be that kfuncs will go through a
480 KF_DEPRECATED flag to kfunc developers to signal to users that a kfunc has been
481 deprecated. Once a kfunc has been marked with KF_DEPRECATED, the following
486 remaining lifespan, a recommendation for new functionality that can replace
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
505 The BPF subsystem provides a number of "core" kfuncs that are potentially
506 applicable to a wide variety of different possible use cases and programs.
510 -------------------------------
512 There are a number of kfuncs that allow ``struct task_struct *`` objects to be
515 .. kernel-doc:: kernel/bpf/helpers.c
518 These kfuncs are useful when you want to acquire or release a reference to a
519 ``struct task_struct *`` that was passed as e.g. a tracepoint arg, or a
522 .. code-block:: c
525 * A trivial example tracepoint program that shows how to
526 * acquire and release a struct task_struct * pointer.
536 * In a typical program you'd do something like store
537 * the task in a map, and the map will automatically
546 Therefore, when in an RCU read region, you can obtain a pointer to a task
547 embedded in a map value without having to acquire a reference:
549 .. code-block:: c
555 * A trivial example showing how to access a task stored
556 * in a map using RCU.
571 bpf_printk("Global task %s is valid", local_copy->comm);
581 ----
583 A BPF program can also look up a task from a pid. This can be useful if the
584 caller doesn't have a trusted pointer to a ``struct task_struct *`` object that
585 it can acquire a reference on with bpf_task_acquire().
587 .. kernel-doc:: kernel/bpf/helpers.c
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,
611 return -EINVAL;
623 --------------------------
627 .. kernel-doc:: kernel/bpf/helpers.c
633 ----
637 the ancestor of a cgroup and find a cgroup by its ID, respectively. Both
638 return a cgroup kptr.
640 .. kernel-doc:: kernel/bpf/helpers.c
643 .. kernel-doc:: kernel/bpf/helpers.c
646 Eventually, BPF should be updated to allow this to happen with a normal memory
650 .. code-block:: c
653 * Simple tracepoint example that illustrates how a cgroup's
662 parent = bpf_cgroup_ancestor(cgrp, cgrp->level - 1);
664 return -ENOENT;
666 bpf_printk("Parent id is %d", parent->self.id);
674 ---------------------------
676 BPF provides a set of kfuncs that can be used to query, allocate, mutate, and
677 destroy struct cpumask * objects. Please refer to :ref:`cpumasks-header-label`