Lines Matching refs:kfunc

18 2. Defining a kfunc
24 valid context. To enforce this, visibility of a kfunc can be per program type.
29 2.1 Creating a wrapper kfunc
32 When defining a wrapper kfunc, the wrapper function should have extern linkage.
33 This prevents the compiler from optimizing away dead code, as this wrapper kfunc
35 prototype in a header for the wrapper kfunc.
49 A wrapper kfunc is often needed when we need to annotate parameters of the
50 kfunc. Otherwise one may directly make the kfunc visible to the BPF program by
53 2.2 Annotating kfunc parameters
59 kfunc with a __tag, where tag may be one of the supported annotations.
74 of the pointer is used. Without __sz annotation, a kfunc cannot accept a void
97 Hence, whenever a constant scalar argument is accepted by a kfunc which is not a
123 the verifier will not check that length is appropriate for the buffer. The kfunc is
177 type of kfunc(s) being registered with the BPF subsystem. To do so, we define
185 This set encodes the BTF ID of each kfunc listed above, and encodes the flags
188 kfunc definitions should also always be annotated with the ``__bpf_kfunc``
189 macro. This prevents issues such as the compiler inlining the kfunc if it's a
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
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
215 The KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc
217 returned from the kfunc before making use of it (dereferencing or passing to
224 The KF_RELEASE flag is used to indicate that the kfunc releases the pointer
227 invoking kfunc with this flag. KF_RELEASE kfuncs automatically receive the
242 2. Pointers which were returned from a KF_ACQUIRE kfunc.
318 pointer. Note as well that a KF_ACQUIRE kfunc that is KF_RCU should very likely
327 changed or removed in a subsequent kernel release. A kfunc that is
330 kfunc's expected remaining lifespan, a recommendation for new
334 Note that while on some occasions, a KF_DEPRECATED kfunc may continue to be
346 Once the kfunc is prepared for use, the final step to making it visible is
370 kfunc by a BPF program, matches the type of pointer specified in the kfunc
372 according to the C standard to be passed to the same kfunc arg, even if their
384 The verifier would allow a ``struct bpf_cpumask *`` to be passed to a kfunc
399 always be safe to pass either type to a trusted kfunc. ``struct
402 nf_conn___init *`` to a kfunc that's expecting a fully initialized ``struct
411 3. kfunc lifecycle expectations
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
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
426 to support the kfunc.
441    refactoring cannot typically change callers in-place when a kfunc changes,
452 c) A kfunc will never have any hard stability guarantees. BPF APIs cannot and
456    remove a kfunc is a multivariate technical decision that is made on a
458    mentioned above. It is expected that a kfunc being removed or changed with
463 3.1 kfunc deprecation
466 As described above, while sometimes a maintainer may find that a kfunc must be
469 deprecation process. For example, if a new kfunc comes along which provides
470 superior functionality to an existing kfunc, the existing kfunc may be
472 to use the new one. Or, if a kfunc has no known users, a decision may be made
473 to remove the kfunc (without providing an alternative API) after some
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.
479 described in :ref:`KF_deprecated_flag`, the kfunc framework provides the
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
484 1. Any relevant information for deprecated kfuncs is documented in the kfunc's
485    kernel docs. This documentation will typically include the kfunc's expected
490 2. The deprecated kfunc is kept in the kernel for some period of time after it
493    the kfunc is, how long it has been in the kernel, and how hard it is to move
496    sometimes dictate that the kfunc be removed before the full intended
499 3. After the deprecation period the kfunc will be removed. At this point, BPF
500    programs calling the kfunc will be rejected by the verifier.