<!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>Livepatching APIs — 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="Rust" href="../rust/index.html" />
<link rel="prev" title="Reliable Stacktrace" href="reliable-stacktrace.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>
<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"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a></li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul class="current">
<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 current"><a class="reference internal" href="index.html">Livepatching</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="livepatch.html">Livepatch</a></li>
<li class="toctree-l2"><a class="reference internal" href="callbacks.html">(Un)patching Callbacks</a></li>
<li class="toctree-l2"><a class="reference internal" href="cumulative-patches.html">Atomic Replace & Cumulative Patches</a></li>
<li class="toctree-l2"><a class="reference internal" href="module-elf-format.html">Livepatch module ELF format</a></li>
<li class="toctree-l2"><a class="reference internal" href="shadow-vars.html">Shadow Variables</a></li>
<li class="toctree-l2"><a class="reference internal" href="system-state.html">System State Changes</a></li>
<li class="toctree-l2"><a class="reference internal" href="reliable-stacktrace.html">Reliable Stacktrace</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Livepatching APIs</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#livepatch-enablement">Livepatch Enablement</a></li>
<li class="toctree-l3"><a class="reference internal" href="#shadow-variables">Shadow Variables</a></li>
<li class="toctree-l3"><a class="reference internal" href="#system-state-changes">System State Changes</a></li>
<li class="toctree-l3"><a class="reference internal" href="#object-types">Object Types</a></li>
</ul>
</li>
</ul>
</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/livepatch/api.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="livepatching-apis">
<h1>Livepatching APIs<a class="headerlink" href="#livepatching-apis" title="Link to this heading">¶</a></h1>
<section id="livepatch-enablement">
<h2>Livepatch Enablement<a class="headerlink" href="#livepatch-enablement" title="Link to this heading">¶</a></h2>
<dl class="c function">
<dt class="sig sig-object c" id="c.klp_enable_patch">
<span class="kt"><span class="pre">int</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">klp_enable_patch</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.klp_patch" title="klp_patch"><span class="n"><span class="pre">klp_patch</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">patch</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.klp_enable_patch" title="Link to this definition">¶</a><br /></dt>
<dd><p>enable the livepatch</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">klp_patch</span> <span class="pre">*patch</span></code></dt><dd><p>patch to be enabled</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Initializes the data structure associated with the patch, creates the sysfs
interface, performs the needed symbol lookups and code relocations,
registers the patched functions with ftrace.</p>
<p>This function is supposed to be called from the livepatch <a class="reference internal" href="../driver-api/basics.html#c.module_init" title="module_init"><code class="xref c c-func docutils literal notranslate"><span class="pre">module_init()</span></code></a>
callback.</p>
<p><strong>Return</strong></p>
<p>0 on success, otherwise error</p>
</div>
</section>
<section id="shadow-variables">
<h2>Shadow Variables<a class="headerlink" href="#shadow-variables" title="Link to this heading">¶</a></h2>
<dl class="c function">
<dt class="sig sig-object c" id="c.klp_shadow_get">
<span class="kt"><span class="pre">void</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">klp_shadow_get</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span>, <span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="n"><span class="pre">id</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.klp_shadow_get" title="Link to this definition">¶</a><br /></dt>
<dd><p>retrieve a shadow variable data pointer</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">void</span> <span class="pre">*obj</span></code></dt><dd><p>pointer to parent object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">id</span></code></dt><dd><p>data identifier</p>
</dd>
</dl>
<p><strong>Return</strong></p>
<p>the shadow variable data element, NULL on failure.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.klp_shadow_alloc">
<span class="kt"><span class="pre">void</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">klp_shadow_alloc</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span>, <span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="n"><span class="pre">id</span></span>, <span class="n"><span class="pre">size_t</span></span><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="n"><span class="pre">gfp_t</span></span><span class="w"> </span><span class="n"><span class="pre">gfp_flags</span></span>, <span class="n"><span class="pre">klp_shadow_ctor_t</span></span><span class="w"> </span><span class="n"><span class="pre">ctor</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">ctor_data</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.klp_shadow_alloc" title="Link to this definition">¶</a><br /></dt>
<dd><p>allocate and add a new shadow variable</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">void</span> <span class="pre">*obj</span></code></dt><dd><p>pointer to parent object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">id</span></code></dt><dd><p>data identifier</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">size</span></code></dt><dd><p>size of attached data</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">gfp_t</span> <span class="pre">gfp_flags</span></code></dt><dd><p>GFP mask for allocation</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">klp_shadow_ctor_t</span> <span class="pre">ctor</span></code></dt><dd><p>custom constructor to initialize the shadow data (optional)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*ctor_data</span></code></dt><dd><p>pointer to any data needed by <strong>ctor</strong> (optional)</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Allocates <strong>size</strong> bytes for new shadow variable data using <strong>gfp_flags</strong>.
The data are zeroed by default. They are further initialized by <strong>ctor</strong>
function if it is not NULL. The new shadow variable is then added
to the global hashtable.</p>
<p>If an existing <obj, id> shadow variable can be found, this routine will
issue a WARN, exit early and return NULL.</p>
<p>This function guarantees that the constructor function is called only when
the variable did not exist before. The cost is that <strong>ctor</strong> is called
in atomic context under a spin lock.</p>
<p><strong>Return</strong></p>
<p>the shadow variable data element, NULL on duplicate or
failure.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.klp_shadow_get_or_alloc">
<span class="kt"><span class="pre">void</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">klp_shadow_get_or_alloc</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span>, <span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="n"><span class="pre">id</span></span>, <span class="n"><span class="pre">size_t</span></span><span class="w"> </span><span class="n"><span class="pre">size</span></span>, <span class="n"><span class="pre">gfp_t</span></span><span class="w"> </span><span class="n"><span class="pre">gfp_flags</span></span>, <span class="n"><span class="pre">klp_shadow_ctor_t</span></span><span class="w"> </span><span class="n"><span class="pre">ctor</span></span>, <span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">ctor_data</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.klp_shadow_get_or_alloc" title="Link to this definition">¶</a><br /></dt>
<dd><p>get existing or allocate a new shadow variable</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">void</span> <span class="pre">*obj</span></code></dt><dd><p>pointer to parent object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">id</span></code></dt><dd><p>data identifier</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">size</span></code></dt><dd><p>size of attached data</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">gfp_t</span> <span class="pre">gfp_flags</span></code></dt><dd><p>GFP mask for allocation</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">klp_shadow_ctor_t</span> <span class="pre">ctor</span></code></dt><dd><p>custom constructor to initialize the shadow data (optional)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*ctor_data</span></code></dt><dd><p>pointer to any data needed by <strong>ctor</strong> (optional)</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Returns a pointer to existing shadow data if an <obj, id> shadow
variable is already present. Otherwise, it creates a new shadow
variable like <a class="reference internal" href="#c.klp_shadow_alloc" title="klp_shadow_alloc"><code class="xref c c-func docutils literal notranslate"><span class="pre">klp_shadow_alloc()</span></code></a>.</p>
<p>This function guarantees that only one shadow variable exists with the given
<strong>id</strong> for the given <strong>obj</strong>. It also guarantees that the constructor function
will be called only when the variable did not exist before. The cost is
that <strong>ctor</strong> is called in atomic context under a spin lock.</p>
<p><strong>Return</strong></p>
<p>the shadow variable data element, NULL on failure.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.klp_shadow_free">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">klp_shadow_free</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">obj</span></span>, <span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="n"><span class="pre">id</span></span>, <span class="n"><span class="pre">klp_shadow_dtor_t</span></span><span class="w"> </span><span class="n"><span class="pre">dtor</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.klp_shadow_free" title="Link to this definition">¶</a><br /></dt>
<dd><p>detach and free a <obj, id> shadow variable</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">void</span> <span class="pre">*obj</span></code></dt><dd><p>pointer to parent object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">id</span></code></dt><dd><p>data identifier</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">klp_shadow_dtor_t</span> <span class="pre">dtor</span></code></dt><dd><p>custom callback that can be used to unregister the variable
and/or free data that the shadow variable points to (optional)</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>This function releases the memory for this <obj, id> shadow variable
instance, callers should stop referencing it accordingly.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.klp_shadow_free_all">
<span class="kt"><span class="pre">void</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">klp_shadow_free_all</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="n"><span class="pre">id</span></span>, <span class="n"><span class="pre">klp_shadow_dtor_t</span></span><span class="w"> </span><span class="n"><span class="pre">dtor</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.klp_shadow_free_all" title="Link to this definition">¶</a><br /></dt>
<dd><p>detach and free all <_, id> shadow variables</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">unsigned</span> <span class="pre">long</span> <span class="pre">id</span></code></dt><dd><p>data identifier</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">klp_shadow_dtor_t</span> <span class="pre">dtor</span></code></dt><dd><p>custom callback that can be used to unregister the variable
and/or free data that the shadow variable points to (optional)</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>This function releases the memory for all <_, id> shadow variable
instances, callers should stop referencing them accordingly.</p>
</div>
</section>
<section id="system-state-changes">
<h2>System State Changes<a class="headerlink" href="#system-state-changes" title="Link to this heading">¶</a></h2>
<dl class="c function">
<dt class="sig sig-object c" id="c.klp_get_state">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.klp_state" title="klp_state"><span class="n"><span class="pre">klp_state</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">klp_get_state</span></span></span><span class="sig-paren">(</span><span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.klp_patch" title="klp_patch"><span class="n"><span class="pre">klp_patch</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="n"><span class="pre">patch</span></span>, <span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="n"><span class="pre">id</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.klp_get_state" title="Link to this definition">¶</a><br /></dt>
<dd><p>get information about system state modified by the given patch</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">klp_patch</span> <span class="pre">*patch</span></code></dt><dd><p>livepatch that modifies the given system state</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">unsigned</span> <span class="pre">long</span> <span class="pre">id</span></code></dt><dd><p>custom identifier of the modified system state</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Checks whether the given patch modifies the given system state.</p>
<p>The function can be called either from pre/post (un)patch
callbacks or from the kernel code added by the livepatch.</p>
<p><strong>Return</strong></p>
<p>pointer to <a class="reference internal" href="#c.klp_state" title="klp_state"><code class="xref c c-struct docutils literal notranslate"><span class="pre">struct</span> <span class="pre">klp_state</span></code></a> when found, otherwise NULL.</p>
</div>
<dl class="c function">
<dt class="sig sig-object c" id="c.klp_get_prev_state">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><a class="reference internal" href="#c.klp_state" title="klp_state"><span class="n"><span class="pre">klp_state</span></span></a><span class="w"> </span><span class="p"><span class="pre">*</span></span><span class="sig-name descname"><span class="n"><span class="pre">klp_get_prev_state</span></span></span><span class="sig-paren">(</span><span class="kt"><span class="pre">unsigned</span></span><span class="w"> </span><span class="kt"><span class="pre">long</span></span><span class="w"> </span><span class="n"><span class="pre">id</span></span><span class="sig-paren">)</span><a class="headerlink" href="#c.klp_get_prev_state" title="Link to this definition">¶</a><br /></dt>
<dd><p>get information about system state modified by the already installed livepatches</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">unsigned</span> <span class="pre">long</span> <span class="pre">id</span></code></dt><dd><p>custom identifier of the modified system state</p>
</dd>
</dl>
<p><strong>Description</strong></p>
<p>Checks whether already installed livepatches modify the given
system state.</p>
<p>The same system state can be modified by more non-cumulative
livepatches. It is expected that the latest livepatch has
the most up-to-date information.</p>
<p>The function can be called only during transition when a new
livepatch is being enabled or when such a transition is reverted.
It is typically called only from pre/post (un)patch
callbacks.</p>
<p><strong>Return</strong></p>
<p>pointer to the latest <a class="reference internal" href="#c.klp_state" title="klp_state"><code class="xref c c-struct docutils literal notranslate"><span class="pre">struct</span> <span class="pre">klp_state</span></code></a> from already
installed livepatches, NULL when not found.</p>
</div>
</section>
<section id="object-types">
<h2>Object Types<a class="headerlink" href="#object-types" title="Link to this heading">¶</a></h2>
<dl class="c struct">
<dt class="sig sig-object c" id="c.klp_func">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">klp_func</span></span></span><a class="headerlink" href="#c.klp_func" title="Link to this definition">¶</a><br /></dt>
<dd><p>function structure for live patching</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct klp_func {
const char *old_name;
void *new_func;
unsigned long old_sympos;
void *old_func;
struct kobject kobj;
struct list_head node;
struct list_head stack_node;
unsigned long old_size, new_size;
bool nop;
bool patched;
bool transition;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">old_name</span></code></dt><dd><p>name of the function to be patched</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">new_func</span></code></dt><dd><p>pointer to the patched function code</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">old_sympos</span></code></dt><dd><p>a hint indicating which symbol position the old function
can be found (optional)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">old_func</span></code></dt><dd><p>pointer to the function being patched</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">kobj</span></code></dt><dd><p>kobject for sysfs resources</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">node</span></code></dt><dd><p>list node for klp_object func_list</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">stack_node</span></code></dt><dd><p>list node for klp_ops func_stack list</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">old_size</span></code></dt><dd><p>size of the old function</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">new_size</span></code></dt><dd><p>size of the new function</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">nop</span></code></dt><dd><p>temporary patch to use the original code again; dyn. allocated</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">patched</span></code></dt><dd><p>the func has been added to the klp_ops list</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">transition</span></code></dt><dd><p>the func is currently being applied or reverted</p>
</dd>
</dl>
</div>
<p><strong>Description</strong></p>
<p>The patched and transition variables define the func’s patching state. When
patching, a func is always in one of the following states:</p>
<blockquote>
<div><p>patched=0 transition=0: unpatched
patched=0 transition=1: unpatched, temporary starting state
patched=1 transition=1: patched, may be visible to some tasks
patched=1 transition=0: patched, visible to all tasks</p>
</div></blockquote>
<p>And when unpatching, it goes in the reverse order:</p>
<blockquote>
<div><p>patched=1 transition=0: patched, visible to all tasks
patched=1 transition=1: patched, may be visible to some tasks
patched=0 transition=1: unpatched, temporary ending state
patched=0 transition=0: unpatched</p>
</div></blockquote>
<dl class="c struct">
<dt class="sig sig-object c" id="c.klp_callbacks">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">klp_callbacks</span></span></span><a class="headerlink" href="#c.klp_callbacks" title="Link to this definition">¶</a><br /></dt>
<dd><p>pre/post live-(un)patch callback structure</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct klp_callbacks {
int (*pre_patch)(struct klp_object *obj);
void (*post_patch)(struct klp_object *obj);
void (*pre_unpatch)(struct klp_object *obj);
void (*post_unpatch)(struct klp_object *obj);
bool post_unpatch_enabled;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">pre_patch</span></code></dt><dd><p>executed before code patching</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">post_patch</span></code></dt><dd><p>executed after code patching</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">pre_unpatch</span></code></dt><dd><p>executed before code unpatching</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">post_unpatch</span></code></dt><dd><p>executed after code unpatching</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">post_unpatch_enabled</span></code></dt><dd><p>flag indicating if post-unpatch callback
should run</p>
</dd>
</dl>
</div>
<p><strong>Description</strong></p>
<p>All callbacks are optional. Only the pre-patch callback, if provided,
will be unconditionally executed. If the parent klp_object fails to
patch for any reason, including a non-zero error status returned from
the pre-patch callback, no further callbacks will be executed.</p>
<dl class="c struct">
<dt class="sig sig-object c" id="c.klp_object">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">klp_object</span></span></span><a class="headerlink" href="#c.klp_object" title="Link to this definition">¶</a><br /></dt>
<dd><p>kernel object structure for live patching</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct klp_object {
const char *name;
struct klp_func *funcs;
struct klp_callbacks callbacks;
struct kobject kobj;
struct list_head func_list;
struct list_head node;
struct module *mod;
bool dynamic;
bool patched;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">name</span></code></dt><dd><p>module name (or NULL for vmlinux)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">funcs</span></code></dt><dd><p>function entries for functions to be patched in the object</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">callbacks</span></code></dt><dd><p>functions to be executed pre/post (un)patching</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">kobj</span></code></dt><dd><p>kobject for sysfs resources</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">func_list</span></code></dt><dd><p>dynamic list of the function entries</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">node</span></code></dt><dd><p>list node for klp_patch obj_list</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">mod</span></code></dt><dd><p>kernel module associated with the patched object
(NULL for vmlinux)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">dynamic</span></code></dt><dd><p>temporary object for nop functions; dynamically allocated</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">patched</span></code></dt><dd><p>the object’s funcs have been added to the klp_ops list</p>
</dd>
</dl>
</div>
<dl class="c struct">
<dt class="sig sig-object c" id="c.klp_state">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">klp_state</span></span></span><a class="headerlink" href="#c.klp_state" title="Link to this definition">¶</a><br /></dt>
<dd><p>state of the system modified by the livepatch</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct klp_state {
unsigned long id;
unsigned int version;
void *data;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">id</span></code></dt><dd><p>system state identifier (non-zero)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">version</span></code></dt><dd><p>version of the change</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">data</span></code></dt><dd><p>custom data</p>
</dd>
</dl>
</div>
<dl class="c struct">
<dt class="sig sig-object c" id="c.klp_patch">
<span class="k"><span class="pre">struct</span></span><span class="w"> </span><span class="sig-name descname"><span class="n"><span class="pre">klp_patch</span></span></span><a class="headerlink" href="#c.klp_patch" title="Link to this definition">¶</a><br /></dt>
<dd><p>patch structure for live patching</p>
</dd></dl>
<div class="kernelindent docutils container">
<p><strong>Definition</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct klp_patch {
struct module *mod;
struct klp_object *objs;
struct klp_state *states;
bool replace;
struct list_head list;
struct kobject kobj;
struct list_head obj_list;
bool enabled;
bool forced;
struct work_struct free_work;
struct completion finish;
};
</pre></div>
</div>
<p><strong>Members</strong></p>
<dl class="simple">
<dt><code class="docutils literal notranslate"><span class="pre">mod</span></code></dt><dd><p>reference to the live patch module</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">objs</span></code></dt><dd><p>object entries for kernel objects to be patched</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">states</span></code></dt><dd><p>system states that can get modified</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">replace</span></code></dt><dd><p>replace all actively used patches</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">list</span></code></dt><dd><p>list node for global list of actively used patches</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">kobj</span></code></dt><dd><p>kobject for sysfs resources</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">obj_list</span></code></dt><dd><p>dynamic list of the object entries</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">enabled</span></code></dt><dd><p>the patch is enabled (but operation may be incomplete)</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">forced</span></code></dt><dd><p>was involved in a forced transition</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">free_work</span></code></dt><dd><p>patch cleanup from workqueue-context</p>
</dd>
<dt><code class="docutils literal notranslate"><span class="pre">finish</span></code></dt><dd><p>for waiting till it is safe to remove the patch module</p>
</dd>
</dl>
</div>
</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/livepatch/api.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>