<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>BPF Kernel Functions (kfuncs) — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="BPF cpumask kfuncs" href="cpumasks.html" />
<link rel="prev" title="Helper functions" href="helpers.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#core-subsystems">Core subsystems</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#human-interfaces">Human interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#networking-interfaces">Networking interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="../subsystem-apis.html#storage-interfaces">Storage interfaces</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../subsystem-apis.html#other-subsystems">Other subsystems</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../accounting/index.html">Accounting</a></li>
<li class="toctree-l3"><a class="reference internal" href="../cpu-freq/index.html">CPUFreq - CPU frequency and voltage scaling code in the Linux(TM) kernel</a></li>
<li class="toctree-l3"><a class="reference internal" href="../edac/index.html">EDAC Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../fpga/index.html">FPGA</a></li>
<li class="toctree-l3"><a class="reference internal" href="../i2c/index.html">I2C/SMBus Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../iio/index.html">Industrial I/O</a></li>
<li class="toctree-l3"><a class="reference internal" href="../pcmcia/index.html">PCMCIA</a></li>
<li class="toctree-l3"><a class="reference internal" href="../spi/index.html">Serial Peripheral Interface (SPI)</a></li>
<li class="toctree-l3"><a class="reference internal" href="../w1/index.html">1-Wire Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../watchdog/index.html">Watchdog Support</a></li>
<li class="toctree-l3"><a class="reference internal" href="../virt/index.html">Virtualization Support</a></li>
<li class="toctree-l3"><a class="reference internal" href="../hwmon/index.html">Hardware Monitoring</a></li>
<li class="toctree-l3"><a class="reference internal" href="../accel/index.html">Compute Accelerators</a></li>
<li class="toctree-l3"><a class="reference internal" href="../security/index.html">Security Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../crypto/index.html">Crypto API</a></li>
<li class="toctree-l3 current"><a class="reference internal" href="index.html">BPF Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../usb/index.html">USB support</a></li>
<li class="toctree-l3"><a class="reference internal" href="../PCI/index.html">PCI Bus Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../misc-devices/index.html">Assorted Miscellaneous Devices Documentation</a></li>
<li class="toctree-l3"><a class="reference internal" href="../peci/index.html">PECI Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../wmi/index.html">WMI Subsystem</a></li>
<li class="toctree-l3"><a class="reference internal" href="../tee/index.html">TEE Subsystem</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1"><a class="reference internal" href="../rust/index.html">Rust</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/bpf/kfuncs.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="bpf-kernel-functions-kfuncs">
<span id="kfuncs-header-label"></span><h1>BPF Kernel Functions (kfuncs)<a class="headerlink" href="#bpf-kernel-functions-kfuncs" title="Link to this heading">¶</a></h1>
<section id="introduction">
<h2>1. Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>
<p>BPF Kernel Functions or more commonly known as kfuncs are functions in the Linux
kernel which are exposed for use by BPF programs. Unlike normal BPF helpers,
kfuncs do not have a stable interface and can change from one kernel release to
another. Hence, BPF programs need to be updated in response to changes in the
kernel. See <a class="reference internal" href="#bpf-kfunc-lifecycle-expectations"><span class="std std-ref">3. kfunc lifecycle expectations</span></a> for more information.</p>
</section>
<section id="defining-a-kfunc">
<h2>2. Defining a kfunc<a class="headerlink" href="#defining-a-kfunc" title="Link to this heading">¶</a></h2>
<p>There are two ways to expose a kernel function to BPF programs, either make an
existing function in the kernel visible, or add a new wrapper for BPF. In both
cases, care must be taken that BPF program can only call such function in a
valid context. To enforce this, visibility of a kfunc can be per program type.</p>
<p>If you are not creating a BPF wrapper for existing kernel function, skip ahead
to <a class="reference internal" href="#bpf-kfunc-nodef"><span class="std std-ref">2.3 Using an existing kernel function</span></a>.</p>
<section id="creating-a-wrapper-kfunc">
<h3>2.1 Creating a wrapper kfunc<a class="headerlink" href="#creating-a-wrapper-kfunc" title="Link to this heading">¶</a></h3>
<p>When defining a wrapper kfunc, the wrapper function should have extern linkage.
This prevents the compiler from optimizing away dead code, as this wrapper kfunc
is not invoked anywhere in the kernel itself. It is not necessary to provide a
prototype in a header for the wrapper kfunc.</p>
<p>An example is given below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/* Disables missing prototype warnings */
__bpf_kfunc_start_defs();
__bpf_kfunc struct task_struct *bpf_find_get_task_by_vpid(pid_t nr)
{
return find_get_task_by_vpid(nr);
}
__bpf_kfunc_end_defs();
</pre></div>
</div>
<p>A wrapper kfunc is often needed when we need to annotate parameters of the
kfunc. Otherwise one may directly make the kfunc visible to the BPF program by
registering it with the BPF subsystem. See <a class="reference internal" href="#bpf-kfunc-nodef"><span class="std std-ref">2.3 Using an existing kernel function</span></a>.</p>
</section>
<section id="annotating-kfunc-parameters">
<h3>2.2 Annotating kfunc parameters<a class="headerlink" href="#annotating-kfunc-parameters" title="Link to this heading">¶</a></h3>
<p>Similar to BPF helpers, there is sometime need for additional context required
by the verifier to make the usage of kernel functions safer and more useful.
Hence, we can annotate a parameter by suffixing the name of the argument of the
kfunc with a __tag, where tag may be one of the supported annotations.</p>
</section>
<section id="sz-annotation">
<h3>2.2.1 __sz Annotation<a class="headerlink" href="#sz-annotation" title="Link to this heading">¶</a></h3>
<p>This annotation is used to indicate a memory and size pair in the argument list.
An example is given below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>__bpf_kfunc void bpf_memzero(void *mem, int mem__sz)
{
...
}
</pre></div>
</div>
<p>Here, the verifier will treat first argument as a PTR_TO_MEM, and second
argument as its size. By default, without __sz annotation, the size of the type
of the pointer is used. Without __sz annotation, a kfunc cannot accept a void
pointer.</p>
</section>
<section id="k-annotation">
<h3>2.2.2 __k Annotation<a class="headerlink" href="#k-annotation" title="Link to this heading">¶</a></h3>
<p>This annotation is only understood for scalar arguments, where it indicates that
the verifier must check the scalar argument to be a known constant, which does
not indicate a size parameter, and the value of the constant is relevant to the
safety of the program.</p>
<p>An example is given below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>__bpf_kfunc void *bpf_obj_new(u32 local_type_id__k, ...)
{
...
}
</pre></div>
</div>
<p>Here, bpf_obj_new uses local_type_id argument to find out the size of that type
ID in program’s BTF and return a sized pointer to it. Each type ID will have a
distinct size, hence it is crucial to treat each such call as distinct when
values don’t match during verifier state pruning checks.</p>
<p>Hence, whenever a constant scalar argument is accepted by a kfunc which is not a
size parameter, and the value of the constant matters for program safety, __k
suffix should be used.</p>
</section>
<section id="uninit-annotation">
<h3>2.2.3 __uninit Annotation<a class="headerlink" href="#uninit-annotation" title="Link to this heading">¶</a></h3>
<p>This annotation is used to indicate that the argument will be treated as
uninitialized.</p>
<p>An example is given below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>__bpf_kfunc int bpf_dynptr_from_skb(..., struct bpf_dynptr_kern *ptr__uninit)
{
...
}
</pre></div>
</div>
<p>Here, the dynptr will be treated as an uninitialized dynptr. Without this
annotation, the verifier will reject the program if the dynptr passed in is
not initialized.</p>
</section>
<section id="opt-annotation">
<h3>2.2.4 __opt Annotation<a class="headerlink" href="#opt-annotation" title="Link to this heading">¶</a></h3>
<p>This annotation is used to indicate that the buffer associated with an __sz or __szk
argument may be null. If the function is passed a nullptr in place of the buffer,
the verifier will not check that length is appropriate for the buffer. The kfunc is
responsible for checking if this buffer is null before using it.</p>
<p>An example is given below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>__bpf_kfunc void *bpf_dynptr_slice(..., void *buffer__opt, u32 buffer__szk)
{
...
}
</pre></div>
</div>
<p>Here, the buffer may be null. If buffer is not null, it at least of size buffer_szk.
Either way, the returned buffer is either NULL, or of size buffer_szk. Without this
annotation, the verifier will reject the program if a null pointer is passed in with
a nonzero size.</p>
</section>
<section id="str-annotation">
<h3>2.2.5 __str Annotation<a class="headerlink" href="#str-annotation" title="Link to this heading">¶</a></h3>
<p>This annotation is used to indicate that the argument is a constant string.</p>
<p>An example is given below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>__bpf_kfunc bpf_get_file_xattr(..., const char *name__str, ...)
{
...
}
</pre></div>
</div>
<p>In this case, <code class="docutils literal notranslate"><span class="pre">bpf_get_file_xattr()</span></code> can be called as:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>bpf_get_file_xattr(..., "xattr_name", ...);
</pre></div>
</div>
<p>Or:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>const char name[] = "xattr_name"; /* This need to be global */
int BPF_PROG(...)
{
...
bpf_get_file_xattr(..., name, ...);
...
}
</pre></div>
</div>
</section>
<section id="prog-annotation">
<h3>2.2.6 __prog Annotation<a class="headerlink" href="#prog-annotation" title="Link to this heading">¶</a></h3>
<p>This annotation is used to indicate that the argument needs to be fixed up to
the bpf_prog_aux of the caller BPF program. Any value passed into this argument
is ignored, and rewritten by the verifier.</p>
<p>An example is given below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>__bpf_kfunc int bpf_wq_set_callback_impl(struct bpf_wq *wq,
int (callback_fn)(void *map, int *key, void *value),
unsigned int flags,
void *aux__prog)
{
struct bpf_prog_aux *aux = aux__prog;
...
}
</pre></div>
</div>
</section>
<section id="using-an-existing-kernel-function">
<span id="bpf-kfunc-nodef"></span><h3>2.3 Using an existing kernel function<a class="headerlink" href="#using-an-existing-kernel-function" title="Link to this heading">¶</a></h3>
<p>When an existing function in the kernel is fit for consumption by BPF programs,
it can be directly registered with the BPF subsystem. However, care must still
be taken to review the context in which it will be invoked by the BPF program
and whether it is safe to do so.</p>
</section>
<section id="annotating-kfuncs">
<h3>2.4 Annotating kfuncs<a class="headerlink" href="#annotating-kfuncs" title="Link to this heading">¶</a></h3>
<p>In addition to kfuncs’ arguments, verifier may need more information about the
type of kfunc(s) being registered with the BPF subsystem. To do so, we define
flags on a set of kfuncs as follows:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>BTF_KFUNCS_START(bpf_task_set)
BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL)
BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE)
BTF_KFUNCS_END(bpf_task_set)
</pre></div>
</div>
<p>This set encodes the BTF ID of each kfunc listed above, and encodes the flags
along with it. Ofcourse, it is also allowed to specify no flags.</p>
<p>kfunc definitions should also always be annotated with the <code class="docutils literal notranslate"><span class="pre">__bpf_kfunc</span></code>
macro. This prevents issues such as the compiler inlining the kfunc if it’s a
static kernel function, or the function being elided in an LTO build as it’s
not used in the rest of the kernel. Developers should not manually add
annotations to their kfunc to prevent these issues. If an annotation is
required to prevent such an issue with your kfunc, it is a bug and should be
added to the definition of the macro so that other kfuncs are similarly
protected. An example is given below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>__bpf_kfunc struct task_struct *bpf_get_task_pid(s32 pid)
{
...
}
</pre></div>
</div>
</section>
<section id="kf-acquire-flag">
<h3>2.4.1 KF_ACQUIRE flag<a class="headerlink" href="#kf-acquire-flag" title="Link to this heading">¶</a></h3>
<p>The KF_ACQUIRE flag is used to indicate that the kfunc returns a pointer to a
refcounted object. The verifier will then ensure that the pointer to the object
is eventually released using a release kfunc, or transferred to a map using a
referenced kptr (by invoking bpf_kptr_xchg). If not, the verifier fails the
loading of the BPF program until no lingering references remain in all possible
explored states of the program.</p>
</section>
<section id="kf-ret-null-flag">
<h3>2.4.2 KF_RET_NULL flag<a class="headerlink" href="#kf-ret-null-flag" title="Link to this heading">¶</a></h3>
<p>The KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc
may be NULL. Hence, it forces the user to do a NULL check on the pointer
returned from the kfunc before making use of it (dereferencing or passing to
another helper). This flag is often used in pairing with KF_ACQUIRE flag, but
both are orthogonal to each other.</p>
</section>
<section id="kf-release-flag">
<h3>2.4.3 KF_RELEASE flag<a class="headerlink" href="#kf-release-flag" title="Link to this heading">¶</a></h3>
<p>The KF_RELEASE flag is used to indicate that the kfunc releases the pointer
passed in to it. There can be only one referenced pointer that can be passed
in. All copies of the pointer being released are invalidated as a result of
invoking kfunc with this flag. KF_RELEASE kfuncs automatically receive the
protection afforded by the KF_TRUSTED_ARGS flag described below.</p>
</section>
<section id="kf-trusted-args-flag">
<h3>2.4.4 KF_TRUSTED_ARGS flag<a class="headerlink" href="#kf-trusted-args-flag" title="Link to this heading">¶</a></h3>
<p>The KF_TRUSTED_ARGS flag is used for kfuncs taking pointer arguments. It
indicates that the all pointer arguments are valid, and that all pointers to
BTF objects have been passed in their unmodified form (that is, at a zero
offset, and without having been obtained from walking another pointer, with one
exception described below).</p>
<p>There are two types of pointers to kernel objects which are considered “valid”:</p>
<ol class="arabic simple">
<li><p>Pointers which are passed as tracepoint or struct_ops callback arguments.</p></li>
<li><p>Pointers which were returned from a KF_ACQUIRE kfunc.</p></li>
</ol>
<p>Pointers to non-BTF objects (e.g. scalar pointers) may also be passed to
KF_TRUSTED_ARGS kfuncs, and may have a non-zero offset.</p>
<p>The definition of “valid” pointers is subject to change at any time, and has
absolutely no ABI stability guarantees.</p>
<p>As mentioned above, a nested pointer obtained from walking a trusted pointer is
no longer trusted, with one exception. If a <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">type</span></code> has a field that is
guaranteed to be valid (trusted or rcu, as in KF_RCU description below) as long
as its parent pointer is valid, the following macros can be used to express
that to the verifier:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">BTF_TYPE_SAFE_TRUSTED</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">BTF_TYPE_SAFE_RCU</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">BTF_TYPE_SAFE_RCU_OR_NULL</span></code></p></li>
</ul>
<p>For example,</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">BTF_TYPE_SAFE_TRUSTED</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">socket</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">sock</span><span class="w"> </span><span class="o">*</span><span class="n">sk</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>or</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">BTF_TYPE_SAFE_RCU</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">cpumask_t</span><span class="w"> </span><span class="o">*</span><span class="n">cpus_ptr</span><span class="p">;</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">css_set</span><span class="w"> </span><span class="n">__rcu</span><span class="w"> </span><span class="o">*</span><span class="n">cgroups</span><span class="p">;</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="n">__rcu</span><span class="w"> </span><span class="o">*</span><span class="n">real_parent</span><span class="p">;</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="o">*</span><span class="n">group_leader</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>In other words, you must:</p>
<ol class="arabic simple">
<li><p>Wrap the valid pointer type in a <code class="docutils literal notranslate"><span class="pre">BTF_TYPE_SAFE_*</span></code> macro.</p></li>
<li><p>Specify the type and name of the valid nested field. This field must match
the field in the original type definition exactly.</p></li>
</ol>
<p>A new type declared by a <code class="docutils literal notranslate"><span class="pre">BTF_TYPE_SAFE_*</span></code> macro also needs to be emitted so
that it appears in BTF. For example, <code class="docutils literal notranslate"><span class="pre">BTF_TYPE_SAFE_TRUSTED(struct</span> <span class="pre">socket)</span></code>
is emitted in the <code class="docutils literal notranslate"><span class="pre">type_is_trusted()</span></code> function as follows:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">BTF_TYPE_EMIT</span><span class="p">(</span><span class="n">BTF_TYPE_SAFE_TRUSTED</span><span class="p">(</span><span class="k">struct</span><span class="w"> </span><span class="nc">socket</span><span class="p">));</span>
</pre></div>
</div>
</section>
<section id="kf-sleepable-flag">
<h3>2.4.5 KF_SLEEPABLE flag<a class="headerlink" href="#kf-sleepable-flag" title="Link to this heading">¶</a></h3>
<p>The KF_SLEEPABLE flag is used for kfuncs that may sleep. Such kfuncs can only
be called by sleepable BPF programs (BPF_F_SLEEPABLE).</p>
</section>
<section id="kf-destructive-flag">
<h3>2.4.6 KF_DESTRUCTIVE flag<a class="headerlink" href="#kf-destructive-flag" title="Link to this heading">¶</a></h3>
<p>The KF_DESTRUCTIVE flag is used to indicate functions calling which is
destructive to the system. For example such a call can result in system
rebooting or panicking. Due to this additional restrictions apply to these
calls. At the moment they only require CAP_SYS_BOOT capability, but more can be
added later.</p>
</section>
<section id="kf-rcu-flag">
<h3>2.4.7 KF_RCU flag<a class="headerlink" href="#kf-rcu-flag" title="Link to this heading">¶</a></h3>
<p>The KF_RCU flag is a weaker version of KF_TRUSTED_ARGS. The kfuncs marked with
KF_RCU expect either PTR_TRUSTED or MEM_RCU arguments. The verifier guarantees
that the objects are valid and there is no use-after-free. The pointers are not
NULL, but the object’s refcount could have reached zero. The kfuncs need to
consider doing refcnt != 0 check, especially when returning a KF_ACQUIRE
pointer. Note as well that a KF_ACQUIRE kfunc that is KF_RCU should very likely
also be KF_RET_NULL.</p>
</section>
<section id="kf-rcu-protected-flag">
<h3>2.4.8 KF_RCU_PROTECTED flag<a class="headerlink" href="#kf-rcu-protected-flag" title="Link to this heading">¶</a></h3>
<p>The KF_RCU_PROTECTED flag is used to indicate that the kfunc must be invoked in
an RCU critical section. This is assumed by default in non-sleepable programs,
and must be explicitly ensured by calling <code class="docutils literal notranslate"><span class="pre">bpf_rcu_read_lock</span></code> for sleepable
ones.</p>
<p>If the kfunc returns a pointer value, this flag also enforces that the returned
pointer is RCU protected, and can only be used while the RCU critical section is
active.</p>
<p>The flag is distinct from the <code class="docutils literal notranslate"><span class="pre">KF_RCU</span></code> flag, which only ensures that its
arguments are at least RCU protected pointers. This may transitively imply that
RCU protection is ensured, but it does not work in cases of kfuncs which require
RCU protection but do not take RCU protected arguments.</p>
</section>
<section id="kf-deprecated-flag">
<span id="id1"></span><h3>2.4.9 KF_DEPRECATED flag<a class="headerlink" href="#kf-deprecated-flag" title="Link to this heading">¶</a></h3>
<p>The KF_DEPRECATED flag is used for kfuncs which are scheduled to be
changed or removed in a subsequent kernel release. A kfunc that is
marked with KF_DEPRECATED should also have any relevant information
captured in its kernel doc. Such information typically includes the
kfunc’s expected remaining lifespan, a recommendation for new
functionality that can replace it if any is available, and possibly a
rationale for why it is being removed.</p>
<p>Note that while on some occasions, a KF_DEPRECATED kfunc may continue to be
supported and have its KF_DEPRECATED flag removed, it is likely to be far more
difficult to remove a KF_DEPRECATED flag after it’s been added than it is to
prevent it from being added in the first place. As described in
<a class="reference internal" href="#bpf-kfunc-lifecycle-expectations"><span class="std std-ref">3. kfunc lifecycle expectations</span></a>, users that rely on specific kfuncs are
encouraged to make their use-cases known as early as possible, and participate
in upstream discussions regarding whether to keep, change, deprecate, or remove
those kfuncs if and when such discussions occur.</p>
</section>
<section id="registering-the-kfuncs">
<h3>2.5 Registering the kfuncs<a class="headerlink" href="#registering-the-kfuncs" title="Link to this heading">¶</a></h3>
<p>Once the kfunc is prepared for use, the final step to making it visible is
registering it with the BPF subsystem. Registration is done per BPF program
type. An example is shown below:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>BTF_KFUNCS_START(bpf_task_set)
BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL)
BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE)
BTF_KFUNCS_END(bpf_task_set)
static const struct btf_kfunc_id_set bpf_task_kfunc_set = {
.owner = THIS_MODULE,
.set = &bpf_task_set,
};
static int init_subsystem(void)
{
return register_btf_kfunc_id_set(BPF_PROG_TYPE_TRACING, &bpf_task_kfunc_set);
}
late_initcall(init_subsystem);
</pre></div>
</div>
</section>
<section id="specifying-no-cast-aliases-with-init">
<h3>2.6 Specifying no-cast aliases with ___init<a class="headerlink" href="#specifying-no-cast-aliases-with-init" title="Link to this heading">¶</a></h3>
<p>The verifier will always enforce that the BTF type of a pointer passed to a
kfunc by a BPF program, matches the type of pointer specified in the kfunc
definition. The verifier, does, however, allow types that are equivalent
according to the C standard to be passed to the same kfunc arg, even if their
BTF_IDs differ.</p>
<p>For example, for the following type definition:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">bpf_cpumask</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kt">cpumask_t</span><span class="w"> </span><span class="n">cpumask</span><span class="p">;</span>
<span class="w"> </span><span class="n">refcount_t</span><span class="w"> </span><span class="n">usage</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>The verifier would allow a <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">bpf_cpumask</span> <span class="pre">*</span></code> to be passed to a kfunc
taking a <code class="docutils literal notranslate"><span class="pre">cpumask_t</span> <span class="pre">*</span></code> (which is a <code class="xref c c-type broken_xref docutils literal notranslate"><span class="pre">typedef</span> <span class="pre">of</span></code> <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">cpumask</span> <span class="pre">*</span></code>). For
instance, both <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">cpumask</span> <span class="pre">*</span></code> and <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">bpf_cpmuask</span> <span class="pre">*</span></code> can be passed
to <a class="reference internal" href="cpumasks.html#c.bpf_cpumask_test_cpu" title="bpf_cpumask_test_cpu"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_cpumask_test_cpu()</span></code></a>.</p>
<p>In some cases, this type-aliasing behavior is not desired. <code class="docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">nf_conn___init</span></code> is one such example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="k">struct</span><span class="w"> </span><span class="nc">nf_conn___init</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">nf_conn</span><span class="w"> </span><span class="n">ct</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>The C standard would consider these types to be equivalent, but it would not
always be safe to pass either type to a trusted kfunc. <code class="docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">nf_conn___init</span></code> represents an allocated <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">nf_conn</span></code> object that has
<em>not yet been initialized</em>, so it would therefore be unsafe to pass a <code class="docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">nf_conn___init</span> <span class="pre">*</span></code> to a kfunc that’s expecting a fully initialized <code class="docutils literal notranslate"><span class="pre">struct</span>
<span class="pre">nf_conn</span> <span class="pre">*</span></code> (e.g. <code class="docutils literal notranslate"><span class="pre">bpf_ct_change_timeout()</span></code>).</p>
<p>In order to accommodate such requirements, the verifier will enforce strict
PTR_TO_BTF_ID type matching if two types have the exact same name, with one
being suffixed with <code class="docutils literal notranslate"><span class="pre">___init</span></code>.</p>
</section>
</section>
<section id="kfunc-lifecycle-expectations">
<span id="bpf-kfunc-lifecycle-expectations"></span><h2>3. kfunc lifecycle expectations<a class="headerlink" href="#kfunc-lifecycle-expectations" title="Link to this heading">¶</a></h2>
<p>kfuncs provide a kernel <-> kernel API, and thus are not bound by any of the
strict stability restrictions associated with kernel <-> user UAPIs. This means
they can be thought of as similar to EXPORT_SYMBOL_GPL, and can therefore be
modified or removed by a maintainer of the subsystem they’re defined in when
it’s deemed necessary.</p>
<p>Like any other change to the kernel, maintainers will not change or remove a
kfunc without having a reasonable justification. Whether or not they’ll choose
to change a kfunc will ultimately depend on a variety of factors, such as how
widely used the kfunc is, how long the kfunc has been in the kernel, whether an
alternative kfunc exists, what the norm is in terms of stability for the
subsystem in question, and of course what the technical cost is of continuing
to support the kfunc.</p>
<p>There are several implications of this:</p>
<ol class="loweralpha">
<li><p>kfuncs that are widely used or have been in the kernel for a long time will
be more difficult to justify being changed or removed by a maintainer. In
other words, kfuncs that are known to have a lot of users and provide
significant value provide stronger incentives for maintainers to invest the
time and complexity in supporting them. It is therefore important for
developers that are using kfuncs in their BPF programs to communicate and
explain how and why those kfuncs are being used, and to participate in
discussions regarding those kfuncs when they occur upstream.</p></li>
<li><p>Unlike regular kernel symbols marked with EXPORT_SYMBOL_GPL, BPF programs
that call kfuncs are generally not part of the kernel tree. This means that
refactoring cannot typically change callers in-place when a kfunc changes,
as is done for e.g. an upstreamed driver being updated in place when a
kernel symbol is changed.</p>
<p>Unlike with regular kernel symbols, this is expected behavior for BPF
symbols, and out-of-tree BPF programs that use kfuncs should be considered
relevant to discussions and decisions around modifying and removing those
kfuncs. The BPF community will take an active role in participating in
upstream discussions when necessary to ensure that the perspectives of such
users are taken into account.</p>
</li>
<li><p>A kfunc will never have any hard stability guarantees. BPF APIs cannot and
will not ever hard-block a change in the kernel purely for stability
reasons. That being said, kfuncs are features that are meant to solve
problems and provide value to users. The decision of whether to change or
remove a kfunc is a multivariate technical decision that is made on a
case-by-case basis, and which is informed by data points such as those
mentioned above. It is expected that a kfunc being removed or changed with
no warning will not be a common occurrence or take place without sound
justification, but it is a possibility that must be accepted if one is to
use kfuncs.</p></li>
</ol>
<section id="kfunc-deprecation">
<h3>3.1 kfunc deprecation<a class="headerlink" href="#kfunc-deprecation" title="Link to this heading">¶</a></h3>
<p>As described above, while sometimes a maintainer may find that a kfunc must be
changed or removed immediately to accommodate some changes in their subsystem,
usually kfuncs will be able to accommodate a longer and more measured
deprecation process. For example, if a new kfunc comes along which provides
superior functionality to an existing kfunc, the existing kfunc may be
deprecated for some period of time to allow users to migrate their BPF programs
to use the new one. Or, if a kfunc has no known users, a decision may be made
to remove the kfunc (without providing an alternative API) after some
deprecation period so as to provide users with a window to notify the kfunc
maintainer if it turns out that the kfunc is actually being used.</p>
<p>It’s expected that the common case will be that kfuncs will go through a
deprecation period rather than being changed or removed without warning. As
described in <a class="reference internal" href="#kf-deprecated-flag"><span class="std std-ref">2.4.9 KF_DEPRECATED flag</span></a>, the kfunc framework provides the
KF_DEPRECATED flag to kfunc developers to signal to users that a kfunc has been
deprecated. Once a kfunc has been marked with KF_DEPRECATED, the following
procedure is followed for removal:</p>
<ol class="arabic simple">
<li><p>Any relevant information for deprecated kfuncs is documented in the kfunc’s
kernel docs. This documentation will typically include the kfunc’s expected
remaining lifespan, a recommendation for new functionality that can replace
the usage of the deprecated function (or an explanation as to why no such
replacement exists), etc.</p></li>
<li><p>The deprecated kfunc is kept in the kernel for some period of time after it
was first marked as deprecated. This time period will be chosen on a
case-by-case basis, and will typically depend on how widespread the use of
the kfunc is, how long it has been in the kernel, and how hard it is to move
to alternatives. This deprecation time period is “best effort”, and as
described <a class="reference internal" href="#bpf-kfunc-lifecycle-expectations"><span class="std std-ref">above</span></a>, circumstances may
sometimes dictate that the kfunc be removed before the full intended
deprecation period has elapsed.</p></li>
<li><p>After the deprecation period the kfunc will be removed. At this point, BPF
programs calling the kfunc will be rejected by the verifier.</p></li>
</ol>
</section>
</section>
<section id="core-kfuncs">
<h2>4. Core kfuncs<a class="headerlink" href="#core-kfuncs" title="Link to this heading">¶</a></h2>
<p>The BPF subsystem provides a number of “core” kfuncs that are potentially
applicable to a wide variety of different possible use cases and programs.
Those kfuncs are documented here.</p>
<section id="struct-task-struct-kfuncs">
<h3>4.1 struct task_struct * kfuncs<a class="headerlink" href="#struct-task-struct-kfuncs" title="Link to this heading">¶</a></h3>
<p>There are a number of kfuncs that allow <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">task_struct</span> <span class="pre">*</span></code> objects to be
used as kptrs:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.bpf_task_acquire">
<span class="pre">__bpf_kfunc</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">task_struct</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">bpf_task_acquire</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">task_struct</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">p</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.bpf_task_acquire" title="Link to this definition">¶</a><br /></dt>
<dd><p>Acquire a reference to a task. A task acquired by this kfunc which is not stored in a map as a kptr, must be released by calling <a class="reference internal" href="#c.bpf_task_release" title="bpf_task_release"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_task_release()</span></code></a>.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">task_struct</span> <span class="pre">*p</span></code></dt><dd><p>The task on which a reference is being acquired.</p>
</dd>
</dl>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.bpf_task_release">
<span class="pre">__bpf_kfunc</span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">bpf_task_release</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">task_struct</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">p</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.bpf_task_release" title="Link to this definition">¶</a><br /></dt>
<dd><p>Release the reference acquired on a task.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">task_struct</span> <span class="pre">*p</span></code></dt><dd><p>The task on which a reference is being released.</p>
</dd>
</dl>
</div>
<p>These kfuncs are useful when you want to acquire or release a reference to a
<code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">task_struct</span> <span class="pre">*</span></code> that was passed as e.g. a tracepoint arg, or a
struct_ops callback arg. For example:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/**</span>
<span class="cm"> * A trivial example tracepoint program that shows how to</span>
<span class="cm"> * acquire and release a struct task_struct * pointer.</span>
<span class="cm"> */</span>
<span class="n">SEC</span><span class="p">(</span><span class="s">"tp_btf/task_newtask"</span><span class="p">)</span>
<span class="kt">int</span><span class="w"> </span><span class="n">BPF_PROG</span><span class="p">(</span><span class="n">task_acquire_release_example</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="o">*</span><span class="n">task</span><span class="p">,</span><span class="w"> </span><span class="n">u64</span><span class="w"> </span><span class="n">clone_flags</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="o">*</span><span class="n">acquired</span><span class="p">;</span>
<span class="w"> </span><span class="n">acquired</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bpf_task_acquire</span><span class="p">(</span><span class="n">task</span><span class="p">);</span>
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">acquired</span><span class="p">)</span>
<span class="w"> </span><span class="cm">/*</span>
<span class="cm"> * In a typical program you'd do something like store</span>
<span class="cm"> * the task in a map, and the map will automatically</span>
<span class="cm"> * release it later. Here, we release it manually.</span>
<span class="cm"> */</span>
<span class="w"> </span><span class="n">bpf_task_release</span><span class="p">(</span><span class="n">acquired</span><span class="p">);</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>References acquired on <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">task_struct</span> <span class="pre">*</span></code> objects are RCU protected.
Therefore, when in an RCU read region, you can obtain a pointer to a task
embedded in a map value without having to acquire a reference:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cp">#define private(name) SEC(".data." #name) __hidden __attribute__((aligned(8)))</span>
<span class="n">private</span><span class="p">(</span><span class="n">TASK</span><span class="p">)</span><span class="w"> </span><span class="k">static</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="o">*</span><span class="n">global</span><span class="p">;</span>
<span class="cm">/**</span>
<span class="cm"> * A trivial example showing how to access a task stored</span>
<span class="cm"> * in a map using RCU.</span>
<span class="cm"> */</span>
<span class="n">SEC</span><span class="p">(</span><span class="s">"tp_btf/task_newtask"</span><span class="p">)</span>
<span class="kt">int</span><span class="w"> </span><span class="n">BPF_PROG</span><span class="p">(</span><span class="n">task_rcu_read_example</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="o">*</span><span class="n">task</span><span class="p">,</span><span class="w"> </span><span class="n">u64</span><span class="w"> </span><span class="n">clone_flags</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="o">*</span><span class="n">local_copy</span><span class="p">;</span>
<span class="w"> </span><span class="n">bpf_rcu_read_lock</span><span class="p">();</span>
<span class="w"> </span><span class="n">local_copy</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">global</span><span class="p">;</span>
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">local_copy</span><span class="p">)</span>
<span class="w"> </span><span class="cm">/*</span>
<span class="cm"> * We could also pass local_copy to kfuncs or helper functions here,</span>
<span class="cm"> * as we're guaranteed that local_copy will be valid until we exit</span>
<span class="cm"> * the RCU read region below.</span>
<span class="cm"> */</span>
<span class="w"> </span><span class="n">bpf_printk</span><span class="p">(</span><span class="s">"Global task %s is valid"</span><span class="p">,</span><span class="w"> </span><span class="n">local_copy</span><span class="o">-></span><span class="n">comm</span><span class="p">);</span>
<span class="w"> </span><span class="k">else</span>
<span class="w"> </span><span class="n">bpf_printk</span><span class="p">(</span><span class="s">"No global task found"</span><span class="p">);</span>
<span class="w"> </span><span class="n">bpf_rcu_read_unlock</span><span class="p">();</span>
<span class="w"> </span><span class="cm">/* At this point we can no longer reference local_copy. */</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
<hr class="docutils" />
<p>A BPF program can also look up a task from a pid. This can be useful if the
caller doesn’t have a trusted pointer to a <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">task_struct</span> <span class="pre">*</span></code> object that
it can acquire a reference on with <a class="reference internal" href="#c.bpf_task_acquire" title="bpf_task_acquire"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_task_acquire()</span></code></a>.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.bpf_task_from_pid">
<span class="pre">__bpf_kfunc</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">task_struct</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">bpf_task_from_pid</span></span></span><span class="sig-paren">(</span><span class="n"><span class="pre">s32</span></span><span class="w"> </span><span class="n"><span class="pre">pid</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.bpf_task_from_pid" title="Link to this definition">¶</a><br /></dt>
<dd><p>Find a <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">task_struct</span></code> from its pid by looking it up in the root pid namespace idr. If a task is returned, it must either be stored in a map, or released with <a class="reference internal" href="#c.bpf_task_release" title="bpf_task_release"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_task_release()</span></code></a>.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">s32</span> <span class="pre">pid</span></code></dt><dd><p>The pid of the task being looked up.</p>
</dd>
</dl>
</div>
<p>Here is an example of it being used:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="n">SEC</span><span class="p">(</span><span class="s">"tp_btf/task_newtask"</span><span class="p">)</span>
<span class="kt">int</span><span class="w"> </span><span class="n">BPF_PROG</span><span class="p">(</span><span class="n">task_get_pid_example</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="o">*</span><span class="n">task</span><span class="p">,</span><span class="w"> </span><span class="n">u64</span><span class="w"> </span><span class="n">clone_flags</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">task_struct</span><span class="w"> </span><span class="o">*</span><span class="n">lookup</span><span class="p">;</span>
<span class="w"> </span><span class="n">lookup</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bpf_task_from_pid</span><span class="p">(</span><span class="n">task</span><span class="o">-></span><span class="n">pid</span><span class="p">);</span>
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">lookup</span><span class="p">)</span>
<span class="w"> </span><span class="cm">/* A task should always be found, as %task is a tracepoint arg. */</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="o">-</span><span class="n">ENOENT</span><span class="p">;</span>
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">lookup</span><span class="o">-></span><span class="n">pid</span><span class="w"> </span><span class="o">!=</span><span class="w"> </span><span class="n">task</span><span class="o">-></span><span class="n">pid</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="cm">/* bpf_task_from_pid() looks up the task via its</span>
<span class="cm"> * globally-unique pid from the init_pid_ns. Thus,</span>
<span class="cm"> * the pid of the lookup task should always be the</span>
<span class="cm"> * same as the input task.</span>
<span class="cm"> */</span>
<span class="w"> </span><span class="n">bpf_task_release</span><span class="p">(</span><span class="n">lookup</span><span class="p">);</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="o">-</span><span class="n">EINVAL</span><span class="p">;</span>
<span class="w"> </span><span class="p">}</span>
<span class="w"> </span><span class="cm">/* bpf_task_from_pid() returns an acquired reference,</span>
<span class="cm"> * so it must be dropped before returning from the</span>
<span class="cm"> * tracepoint handler.</span>
<span class="cm"> */</span>
<span class="w"> </span><span class="n">bpf_task_release</span><span class="p">(</span><span class="n">lookup</span><span class="p">);</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="struct-cgroup-kfuncs">
<h3>4.2 struct cgroup * kfuncs<a class="headerlink" href="#struct-cgroup-kfuncs" title="Link to this heading">¶</a></h3>
<p><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">cgroup</span> <span class="pre">*</span></code> objects also have acquire and release functions:</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.bpf_cgroup_acquire">
<span class="pre">__bpf_kfunc</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">cgroup</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">bpf_cgroup_acquire</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">cgroup</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">cgrp</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.bpf_cgroup_acquire" title="Link to this definition">¶</a><br /></dt>
<dd><p>Acquire a reference to a cgroup. A cgroup acquired by this kfunc which is not stored in a map as a kptr, must be released by calling <a class="reference internal" href="#c.bpf_cgroup_release" title="bpf_cgroup_release"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_cgroup_release()</span></code></a>.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">cgroup</span> <span class="pre">*cgrp</span></code></dt><dd><p>The cgroup on which a reference is being acquired.</p>
</dd>
</dl>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.bpf_cgroup_release">
<span class="pre">__bpf_kfunc</span><span class="w"> </span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">bpf_cgroup_release</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">cgroup</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">cgrp</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.bpf_cgroup_release" title="Link to this definition">¶</a><br /></dt>
<dd><p>Release the reference acquired on a cgroup. If this kfunc is invoked in an RCU read region, the cgroup is guaranteed to not be freed until the current grace period has ended, even if its refcount drops to 0.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">cgroup</span> <span class="pre">*cgrp</span></code></dt><dd><p>The cgroup on which a reference is being released.</p>
</dd>
</dl>
</div>
<p>These kfuncs are used in exactly the same manner as <a class="reference internal" href="#c.bpf_task_acquire" title="bpf_task_acquire"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_task_acquire()</span></code></a> and
<a class="reference internal" href="#c.bpf_task_release" title="bpf_task_release"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_task_release()</span></code></a> respectively, so we won’t provide examples for them.</p>
<hr class="docutils" />
<p>Other kfuncs available for interacting with <code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">cgroup</span> <span class="pre">*</span></code> objects are
<a class="reference internal" href="#c.bpf_cgroup_ancestor" title="bpf_cgroup_ancestor"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_cgroup_ancestor()</span></code></a> and <a class="reference internal" href="#c.bpf_cgroup_from_id" title="bpf_cgroup_from_id"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_cgroup_from_id()</span></code></a>, allowing callers to access
the ancestor of a cgroup and find a cgroup by its ID, respectively. Both
return a cgroup kptr.</p>
<dl class="c function">
<dt class="sig sig-object c" id="c.bpf_cgroup_ancestor">
<span class="pre">__bpf_kfunc</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">cgroup</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">bpf_cgroup_ancestor</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">cgroup</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">cgrp</span></span>, <span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="n"><span class="pre">level</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.bpf_cgroup_ancestor" title="Link to this definition">¶</a><br /></dt>
<dd><p>Perform a lookup on an entry in a cgroup’s ancestor array. A cgroup returned by this kfunc which is not subsequently stored in a map, must be released by calling <a class="reference internal" href="#c.bpf_cgroup_release" title="bpf_cgroup_release"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_cgroup_release()</span></code></a>.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">cgroup</span> <span class="pre">*cgrp</span></code></dt><dd><p>The cgroup for which we’re performing a lookup.</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">int</span> <span class="pre">level</span></code></dt><dd><p>The level of ancestor to look up.</p>
</dd>
</dl>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.bpf_cgroup_from_id">
<span class="pre">__bpf_kfunc</span><span class="w"> </span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="n"><span class="pre">cgroup</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">bpf_cgroup_from_id</span></span></span><span class="sig-paren">(</span><span class="n"><span class="pre">u64</span></span><span class="w"> </span><span class="n"><span class="pre">cgid</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.bpf_cgroup_from_id" title="Link to this definition">¶</a><br /></dt>
<dd><p>Find a cgroup from its ID. A cgroup returned by this kfunc which is not subsequently stored in a map, must be released by calling <a class="reference internal" href="#c.bpf_cgroup_release" title="bpf_cgroup_release"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_cgroup_release()</span></code></a>.</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Parameters</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">u64</span> <span class="pre">cgid</span></code></dt><dd><p>cgroup id.</p>
</dd>
</dl>
</div>
<p>Eventually, BPF should be updated to allow this to happen with a normal memory
load in the program itself. This is currently not possible without more work in
the verifier. <a class="reference internal" href="#c.bpf_cgroup_ancestor" title="bpf_cgroup_ancestor"><code class="xref c c-func docutils literal notranslate"><span class="pre">bpf_cgroup_ancestor()</span></code></a> can be used as follows:</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="cm">/**</span>
<span class="cm"> * Simple tracepoint example that illustrates how a cgroup's</span>
<span class="cm"> * ancestor can be accessed using bpf_cgroup_ancestor().</span>
<span class="cm"> */</span>
<span class="n">SEC</span><span class="p">(</span><span class="s">"tp_btf/cgroup_mkdir"</span><span class="p">)</span>
<span class="kt">int</span><span class="w"> </span><span class="n">BPF_PROG</span><span class="p">(</span><span class="n">cgrp_ancestor_example</span><span class="p">,</span><span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">cgroup</span><span class="w"> </span><span class="o">*</span><span class="n">cgrp</span><span class="p">,</span><span class="w"> </span><span class="k">const</span><span class="w"> </span><span class="kt">char</span><span class="w"> </span><span class="o">*</span><span class="n">path</span><span class="p">)</span>
<span class="p">{</span>
<span class="w"> </span><span class="k">struct</span><span class="w"> </span><span class="nc">cgroup</span><span class="w"> </span><span class="o">*</span><span class="n">parent</span><span class="p">;</span>
<span class="w"> </span><span class="cm">/* The parent cgroup resides at the level before the current cgroup's level. */</span>
<span class="w"> </span><span class="n">parent</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">bpf_cgroup_ancestor</span><span class="p">(</span><span class="n">cgrp</span><span class="p">,</span><span class="w"> </span><span class="n">cgrp</span><span class="o">-></span><span class="n">level</span><span class="w"> </span><span class="o">-</span><span class="w"> </span><span class="mi">1</span><span class="p">);</span>
<span class="w"> </span><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="o">!</span><span class="n">parent</span><span class="p">)</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="o">-</span><span class="n">ENOENT</span><span class="p">;</span>
<span class="w"> </span><span class="n">bpf_printk</span><span class="p">(</span><span class="s">"Parent id is %d"</span><span class="p">,</span><span class="w"> </span><span class="n">parent</span><span class="o">-></span><span class="n">self</span><span class="p">.</span><span class="n">id</span><span class="p">);</span>
<span class="w"> </span><span class="cm">/* Return the parent cgroup that was acquired above. */</span>
<span class="w"> </span><span class="n">bpf_cgroup_release</span><span class="p">(</span><span class="n">parent</span><span class="p">);</span>
<span class="w"> </span><span class="k">return</span><span class="w"> </span><span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</pre></div>
</div>
</section>
<section id="struct-cpumask-kfuncs">
<h3>4.3 struct cpumask * kfuncs<a class="headerlink" href="#struct-cpumask-kfuncs" title="Link to this heading">¶</a></h3>
<p>BPF provides a set of kfuncs that can be used to query, allocate, mutate, and
destroy <code class="xref c c-struct broken_xref docutils literal notranslate"><span class="pre">struct</span> <span class="pre">cpumask</span></code> * objects. Please refer to <a class="reference internal" href="cpumasks.html#cpumasks-header-label"><span class="std std-ref">BPF cpumask kfuncs</span></a>
for more details.</p>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/bpf/kfuncs.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>