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.
51 A wrapper kfunc is often needed when we need to annotate parameters of the
52 kfunc. Otherwise one may directly make the kfunc visible to the BPF program by
55 2.2 Annotating kfunc parameters
61 kfunc with a __tag, where tag may be one of the supported annotations.
76 of the pointer is used. Without __sz annotation, a kfunc cannot accept a void
99 Hence, whenever a constant scalar argument is accepted by a kfunc which is not a
125 the verifier will not check that length is appropriate for the buffer. The kfunc is
155 type of kfunc(s) being registered with the BPF subsystem. To do so, we define
163 This set encodes the BTF ID of each kfunc listed above, and encodes the flags
166 kfunc definitions should also always be annotated with the ``__bpf_kfunc``
167 macro. This prevents issues such as the compiler inlining the kfunc if it's a
170 annotations to their kfunc to prevent these issues. If an annotation is
171 required to prevent such an issue with your kfunc, it is a bug and should be
183 The KF_ACQUIRE flag is used to indicate that the kfunc returns a pointer to a
185 is eventually released using a release kfunc, or transferred to a map using a
193 The KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc
195 returned from the kfunc before making use of it (dereferencing or passing to
202 The KF_RELEASE flag is used to indicate that the kfunc releases the pointer
205 invoking kfunc with this flag. KF_RELEASE kfuncs automatically receive the
220 2. Pointers which were returned from a KF_ACQUIRE kfunc.
296 pointer. Note as well that a KF_ACQUIRE kfunc that is KF_RCU should very likely
305 changed or removed in a subsequent kernel release. A kfunc that is
308 kfunc's expected remaining lifespan, a recommendation for new
312 Note that while on some occasions, a KF_DEPRECATED kfunc may continue to be
324 Once the kfunc is prepared for use, the final step to making it visible is
348 kfunc by a BPF program, matches the type of pointer specified in the kfunc
350 according to the C standard to be passed to the same kfunc arg, even if their
362 The verifier would allow a ``struct bpf_cpumask *`` to be passed to a kfunc
377 always be safe to pass either type to a trusted kfunc. ``struct
380 nf_conn___init *`` to a kfunc that's expecting a fully initialized ``struct
389 3. kfunc lifecycle expectations
399 kfunc without having a reasonable justification.  Whether or not they'll choose
400 to change a kfunc will ultimately depend on a variety of factors, such as how
401 widely used the kfunc is, how long the kfunc has been in the kernel, whether an
402 alternative kfunc exists, what the norm is in terms of stability for the
404 to support the kfunc.
419    refactoring cannot typically change callers in-place when a kfunc changes,
430 c) A kfunc will never have any hard stability guarantees. BPF APIs cannot and
434    remove a kfunc is a multivariate technical decision that is made on a
436    mentioned above. It is expected that a kfunc being removed or changed with
441 3.1 kfunc deprecation
444 As described above, while sometimes a maintainer may find that a kfunc must be
447 deprecation process. For example, if a new kfunc comes along which provides
448 superior functionality to an existing kfunc, the existing kfunc may be
450 to use the new one. Or, if a kfunc has no known users, a decision may be made
451 to remove the kfunc (without providing an alternative API) after some
452 deprecation period so as to provide users with a window to notify the kfunc
453 maintainer if it turns out that the kfunc is actually being used.
457 described in :ref:`KF_deprecated_flag`, the kfunc framework provides the
458 KF_DEPRECATED flag to kfunc developers to signal to users that a kfunc has been
459 deprecated. Once a kfunc has been marked with KF_DEPRECATED, the following
462 1. Any relevant information for deprecated kfuncs is documented in the kfunc's
463    kernel docs. This documentation will typically include the kfunc's expected
468 2. The deprecated kfunc is kept in the kernel for some period of time after it
471    the kfunc is, how long it has been in the kernel, and how hard it is to move
474    sometimes dictate that the kfunc be removed before the full intended
477 3. After the deprecation period the kfunc will be removed. At this point, BPF
478    programs calling the kfunc will be rejected by the verifier.