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
117 type of kfunc(s) being registered with the BPF subsystem. To do so, we define
125 This set encodes the BTF ID of each kfunc listed above, and encodes the flags
128 kfunc definitions should also always be annotated with the ``__bpf_kfunc``
129 macro. This prevents issues such as the compiler inlining the kfunc if it's a
132 annotations to their kfunc to prevent these issues. If an annotation is
133 required to prevent such an issue with your kfunc, it is a bug and should be
145 The KF_ACQUIRE flag is used to indicate that the kfunc returns a pointer to a
147 is eventually released using a release kfunc, or transferred to a map using a
155 The KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc
157 returned from the kfunc before making use of it (dereferencing or passing to
164 The KF_RELEASE flag is used to indicate that the kfunc releases the pointer
167 kfunc with this flag.
172 The KF_KPTR_GET flag is used to indicate that the kfunc takes the first argument
175 arguments of a kfunc. The KF_KPTR_GET flag should be used in conjunction with
190 2. Pointers which were returned from a KF_ACQUIRE or KF_KPTR_GET kfunc.
236 When used together with KF_ACQUIRE, it indicates the kfunc should have a
238 The argument may have reference count of 0 and the kfunc must take this
247 changed or removed in a subsequent kernel release. A kfunc that is
250 kfunc's expected remaining lifespan, a recommendation for new
254 Note that while on some occasions, a KF_DEPRECATED kfunc may continue to be
266 Once the kfunc is prepared for use, the final step to making it visible is
290 kfunc by a BPF program, matches the type of pointer specified in the kfunc
292 according to the C standard to be passed to the same kfunc arg, even if their
304 The verifier would allow a ``struct bpf_cpumask *`` to be passed to a kfunc
319 always be safe to pass either type to a trusted kfunc. ``struct
322 nf_conn___init *`` to a kfunc that's expecting a fully initialized ``struct
331 3. kfunc lifecycle expectations
341 kfunc without having a reasonable justification. Whether or not they'll choose
342 to change a kfunc will ultimately depend on a variety of factors, such as how
343 widely used the kfunc is, how long the kfunc has been in the kernel, whether an
344 alternative kfunc exists, what the norm is in terms of stability for the
346 to support the kfunc.
361 refactoring cannot typically change callers in-place when a kfunc changes,
372 c) A kfunc will never have any hard stability guarantees. BPF APIs cannot and
376 remove a kfunc is a multivariate technical decision that is made on a
378 mentioned above. It is expected that a kfunc being removed or changed with
383 3.1 kfunc deprecation
386 As described above, while sometimes a maintainer may find that a kfunc must be
389 deprecation process. For example, if a new kfunc comes along which provides
390 superior functionality to an existing kfunc, the existing kfunc may be
392 to use the new one. Or, if a kfunc has no known users, a decision may be made
393 to remove the kfunc (without providing an alternative API) after some
394 deprecation period so as to provide users with a window to notify the kfunc
395 maintainer if it turns out that the kfunc is actually being used.
399 described in :ref:`KF_deprecated_flag`, the kfunc framework provides the
400 KF_DEPRECATED flag to kfunc developers to signal to users that a kfunc has been
401 deprecated. Once a kfunc has been marked with KF_DEPRECATED, the following
404 1. Any relevant information for deprecated kfuncs is documented in the kfunc's
405 kernel docs. This documentation will typically include the kfunc's expected
410 2. The deprecated kfunc is kept in the kernel for some period of time after it
413 the kfunc is, how long it has been in the kernel, and how hard it is to move
416 sometimes dictate that the kfunc be removed before the full intended
419 3. After the deprecation period the kfunc will be removed. At this point, BPF
420 programs calling the kfunc will be rejected by the verifier.
546 * be acquired using the bpf_cgroup_kptr_get() kfunc.
569 * present in the map by the time we invoke the kfunc.
586 Another kfunc available for interacting with ``struct cgroup *`` objects is