<!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>DWARF module versioning — 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="Bash completion for Kbuild" href="bash-completion.html" />
<link rel="prev" title="Building Linux with Clang/LLVM" href="llvm.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>
<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 class="current">
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Build system</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="kconfig-language.html">Kconfig Language</a></li>
<li class="toctree-l2"><a class="reference internal" href="kconfig-macro-language.html">Kconfig macro language</a></li>
<li class="toctree-l2"><a class="reference internal" href="kbuild.html">Kbuild</a></li>
<li class="toctree-l2"><a class="reference internal" href="kconfig.html">Configuration targets and editors</a></li>
<li class="toctree-l2"><a class="reference internal" href="makefiles.html">Linux Kernel Makefiles</a></li>
<li class="toctree-l2"><a class="reference internal" href="modules.html">Building External Modules</a></li>
<li class="toctree-l2"><a class="reference internal" href="headers_install.html">Exporting kernel headers for use by userspace</a></li>
<li class="toctree-l2"><a class="reference internal" href="issues.html">Recursion issues</a></li>
<li class="toctree-l2"><a class="reference internal" href="reproducible-builds.html">Reproducible builds</a></li>
<li class="toctree-l2"><a class="reference internal" href="gcc-plugins.html">GCC plugin infrastructure</a></li>
<li class="toctree-l2"><a class="reference internal" href="llvm.html">Building Linux with Clang/LLVM</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">DWARF module versioning</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#introduction">Introduction</a></li>
<li class="toctree-l3"><a class="reference internal" href="#type-information-availability">Type information availability</a></li>
<li class="toctree-l3"><a class="reference internal" href="#symtypes-output-format">Symtypes output format</a></li>
<li class="toctree-l3"><a class="reference internal" href="#maintaining-a-stable-kabi">Maintaining a stable kABI</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="bash-completion.html">Bash completion for Kbuild</a></li>
</ul>
</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/kbuild/gendwarfksyms.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="dwarf-module-versioning">
<h1>DWARF module versioning<a class="headerlink" href="#dwarf-module-versioning" title="Link to this heading">¶</a></h1>
<section id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Link to this heading">¶</a></h2>
<p>When CONFIG_MODVERSIONS is enabled, symbol versions for modules
are typically calculated from preprocessed source code using the
<strong>genksyms</strong> tool. However, this is incompatible with languages such
as Rust, where the source code has insufficient information about
the resulting ABI. With CONFIG_GENDWARFKSYMS (and CONFIG_DEBUG_INFO)
selected, <strong>gendwarfksyms</strong> is used instead to calculate symbol versions
from the DWARF debugging information, which contains the necessary
details about the final module ABI.</p>
<section id="usage">
<h3>Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h3>
<p>gendwarfksyms accepts a list of object files on the command line, and a
list of symbol names (one per line) in standard input:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Usage: gendwarfksyms [options] elf-object-file ... < symbol-list
Options:
-d, --debug Print debugging information
--dump-dies Dump DWARF DIE contents
--dump-die-map Print debugging information about die_map changes
--dump-types Dump type strings
--dump-versions Dump expanded type strings used for symbol versions
-s, --stable Support kABI stability features
-T, --symtypes file Write a symtypes file
-h, --help Print this message
</pre></div>
</div>
</section>
</section>
<section id="type-information-availability">
<h2>Type information availability<a class="headerlink" href="#type-information-availability" title="Link to this heading">¶</a></h2>
<p>While symbols are typically exported in the same translation unit (TU)
where they’re defined, it’s also perfectly fine for a TU to export
external symbols. For example, this is done when calculating symbol
versions for exports in stand-alone assembly code.</p>
<p>To ensure the compiler emits the necessary DWARF type information in the
TU where symbols are actually exported, gendwarfksyms adds a pointer
to exported symbols in the <cite><code class="xref c c-func broken_xref docutils literal notranslate"><span class="pre">EXPORT_SYMBOL()</span></code></cite> macro using the following
macro:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#define __GENDWARFKSYMS_EXPORT(sym) \
static typeof(sym) *__gendwarfksyms_ptr_##sym __used \
__section(".discard.gendwarfksyms") = &sym;
</pre></div>
</div>
<p>When a symbol pointer is found in DWARF, gendwarfksyms can use its
type for calculating symbol versions even if the symbol is defined
elsewhere. The name of the symbol pointer is expected to start with
<cite>__gendwarfksyms_ptr_</cite>, followed by the name of the exported symbol.</p>
</section>
<section id="symtypes-output-format">
<h2>Symtypes output format<a class="headerlink" href="#symtypes-output-format" title="Link to this heading">¶</a></h2>
<p>Similarly to genksyms, gendwarfksyms supports writing a symtypes
file for each processed object that contain types for exported
symbols and each referenced type that was used in calculating symbol
versions. These files can be useful when trying to determine what
exactly caused symbol versions to change between builds. To generate
symtypes files during a kernel build, set <cite>KBUILD_SYMTYPES=1</cite>.</p>
<p>Matching the existing format, the first column of each line contains
either a type reference or a symbol name. Type references have a
one-letter prefix followed by “#” and the name of the type. Four
reference types are supported:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>e#<type> = enum
s#<type> = struct
t#<type> = typedef
u#<type> = union
</pre></div>
</div>
<p>Type names with spaces in them are wrapped in single quotes, e.g.:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>s#'core::result::Result<u8, core::num::error::ParseIntError>'
</pre></div>
</div>
<p>The rest of the line contains a type string. Unlike with genksyms that
produces C-style type strings, gendwarfksyms uses the same simple parsed
DWARF format produced by <strong>--dump-dies</strong>, but with type references
instead of fully expanded strings.</p>
</section>
<section id="maintaining-a-stable-kabi">
<h2>Maintaining a stable kABI<a class="headerlink" href="#maintaining-a-stable-kabi" title="Link to this heading">¶</a></h2>
<p>Distribution maintainers often need the ability to make ABI compatible
changes to kernel data structures due to LTS updates or backports. Using
the traditional <cite>#ifndef __GENKSYMS__</cite> to hide these changes from symbol
versioning won’t work when processing object files. To support this
use case, gendwarfksyms provides kABI stability features designed to
hide changes that won’t affect the ABI when calculating versions. These
features are all gated behind the <strong>--stable</strong> command line flag and are
not used in the mainline kernel. To use stable features during a kernel
build, set <cite>KBUILD_GENDWARFKSYMS_STABLE=1</cite>.</p>
<p>Examples for using these features are provided in the
<strong>scripts/gendwarfksyms/examples</strong> directory, including helper macros
for source code annotation. Note that as these features are only used to
transform the inputs for symbol versioning, the user is responsible for
ensuring that their changes actually won’t break the ABI.</p>
<section id="kabi-rules">
<h3>kABI rules<a class="headerlink" href="#kabi-rules" title="Link to this heading">¶</a></h3>
<p>kABI rules allow distributions to fine-tune certain parts
of gendwarfksyms output and thus control how symbol
versions are calculated. These rules are defined in the
<cite>.discard.gendwarfksyms.kabi_rules</cite> section of the object file and
consist of simple null-terminated strings with the following structure:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>version\0type\0target\0value\0
</pre></div>
</div>
<p>This string sequence is repeated as many times as needed to express all
the rules. The fields are as follows:</p>
<ul class="simple">
<li><p><cite>version</cite>: Ensures backward compatibility for future changes to the
structure. Currently expected to be “1”.</p></li>
<li><p><cite>type</cite>: Indicates the type of rule being applied.</p></li>
<li><p><cite>target</cite>: Specifies the target of the rule, typically the fully
qualified name of the DWARF Debugging Information Entry (DIE).</p></li>
<li><p><cite>value</cite>: Provides rule-specific data.</p></li>
</ul>
<p>The following helper macros, for example, can be used to specify rules
in the source code:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#define ___KABI_RULE(hint, target, value) \
static const char __PASTE(__gendwarfksyms_rule_, \
__COUNTER__)[] __used __aligned(1) \
__section(".discard.gendwarfksyms.kabi_rules") = \
"1\0" #hint "\0" target "\0" value
#define __KABI_RULE(hint, target, value) \
___KABI_RULE(hint, #target, #value)
</pre></div>
</div>
<p>Currently, only the rules discussed in this section are supported, but
the format is extensible enough to allow further rules to be added as
need arises.</p>
<section id="managing-definition-visibility">
<h4>Managing definition visibility<a class="headerlink" href="#managing-definition-visibility" title="Link to this heading">¶</a></h4>
<p>A declaration can change into a full definition when additional includes
are pulled into the translation unit. This changes the versions of any
symbol that references the type even if the ABI remains unchanged. As
it may not be possible to drop includes without breaking the build, the
<cite>declonly</cite> rule can be used to specify a type as declaration-only, even
if the debugging information contains the full definition.</p>
<p>The rule fields are expected to be as follows:</p>
<ul class="simple">
<li><p><cite>type</cite>: “declonly”</p></li>
<li><p><cite>target</cite>: The fully qualified name of the target data structure
(as shown in <strong>--dump-dies</strong> output).</p></li>
<li><p><cite>value</cite>: This field is ignored.</p></li>
</ul>
<p>Using the <cite>__KABI_RULE</cite> macro, this rule can be defined as:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#define KABI_DECLONLY(fqn) __KABI_RULE(declonly, fqn, )
</pre></div>
</div>
<p>Example usage:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct s {
/* definition */
};
KABI_DECLONLY(s);
</pre></div>
</div>
</section>
<section id="adding-enumerators">
<h4>Adding enumerators<a class="headerlink" href="#adding-enumerators" title="Link to this heading">¶</a></h4>
<p>For enums, all enumerators and their values are included in calculating
symbol versions, which becomes a problem if we later need to add more
enumerators without changing symbol versions. The <cite>enumerator_ignore</cite>
rule allows us to hide named enumerators from the input.</p>
<p>The rule fields are expected to be as follows:</p>
<ul class="simple">
<li><p><cite>type</cite>: “enumerator_ignore”</p></li>
<li><p><cite>target</cite>: The fully qualified name of the target enum
(as shown in <strong>--dump-dies</strong> output) and the name of the
enumerator field separated by a space.</p></li>
<li><p><cite>value</cite>: This field is ignored.</p></li>
</ul>
<p>Using the <cite>__KABI_RULE</cite> macro, this rule can be defined as:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#define KABI_ENUMERATOR_IGNORE(fqn, field) \
__KABI_RULE(enumerator_ignore, fqn field, )
</pre></div>
</div>
<p>Example usage:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>enum e {
A, B, C, D,
};
KABI_ENUMERATOR_IGNORE(e, B);
KABI_ENUMERATOR_IGNORE(e, C);
</pre></div>
</div>
<p>If the <code class="xref c c-enum broken_xref docutils literal notranslate"><span class="pre">enum</span> <span class="pre">additionally</span></code> includes an end marker and new values must
be added in the middle, we may need to use the old value for the last
enumerator when calculating versions. The <cite>enumerator_value</cite> rule allows
us to override the value of an enumerator for version calculation:</p>
<ul class="simple">
<li><p><cite>type</cite>: “enumerator_value”</p></li>
<li><p><cite>target</cite>: The fully qualified name of the target enum
(as shown in <strong>--dump-dies</strong> output) and the name of the
enumerator field separated by a space.</p></li>
<li><p><cite>value</cite>: Integer value used for the field.</p></li>
</ul>
<p>Using the <cite>__KABI_RULE</cite> macro, this rule can be defined as:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#define KABI_ENUMERATOR_VALUE(fqn, field, value) \
__KABI_RULE(enumerator_value, fqn field, value)
</pre></div>
</div>
<p>Example usage:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>enum e {
A, B, C, LAST,
};
KABI_ENUMERATOR_IGNORE(e, C);
KABI_ENUMERATOR_VALUE(e, LAST, 2);
</pre></div>
</div>
</section>
<section id="managing-structure-size-changes">
<h4>Managing structure size changes<a class="headerlink" href="#managing-structure-size-changes" title="Link to this heading">¶</a></h4>
<p>A data structure can be partially opaque to modules if its allocation is
handled by the core kernel, and modules only need to access some of its
members. In this situation, it’s possible to append new members to the
structure without breaking the ABI, as long as the layout for the original
members remains unchanged.</p>
<p>To append new members, we can hide them from symbol versioning as
described in section <a class="reference internal" href="#hiding-members"><span class="std std-ref">Hiding members</span></a>, but we can’t
hide the increase in structure size. The <cite>byte_size</cite> rule allows us to
override the structure size used for symbol versioning.</p>
<p>The rule fields are expected to be as follows:</p>
<ul class="simple">
<li><p><cite>type</cite>: “byte_size”</p></li>
<li><p><cite>target</cite>: The fully qualified name of the target data structure
(as shown in <strong>--dump-dies</strong> output).</p></li>
<li><p><cite>value</cite>: A positive decimal number indicating the structure size
in bytes.</p></li>
</ul>
<p>Using the <cite>__KABI_RULE</cite> macro, this rule can be defined as:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#define KABI_BYTE_SIZE(fqn, value) \
__KABI_RULE(byte_size, fqn, value)
</pre></div>
</div>
<p>Example usage:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct s {
/* Unchanged original members */
unsigned long a;
void *p;
/* Appended new members */
KABI_IGNORE(0, unsigned long n);
};
KABI_BYTE_SIZE(s, 16);
</pre></div>
</div>
</section>
<section id="overriding-type-strings">
<h4>Overriding type strings<a class="headerlink" href="#overriding-type-strings" title="Link to this heading">¶</a></h4>
<p>In rare situations where distributions must make significant changes to
otherwise opaque data structures that have inadvertently been included
in the published ABI, keeping symbol versions stable using the more
targeted kABI rules can become tedious. The <cite>type_string</cite> rule allows us
to override the full type string for a type or a symbol, and even add
types for versioning that no longer exist in the kernel.</p>
<p>The rule fields are expected to be as follows:</p>
<ul class="simple">
<li><p><cite>type</cite>: “type_string”</p></li>
<li><p><cite>target</cite>: The fully qualified name of the target data structure
(as shown in <strong>--dump-dies</strong> output) or symbol.</p></li>
<li><p><cite>value</cite>: A valid type string (as shown in <strong>--symtypes</strong>) output)
to use instead of the real type.</p></li>
</ul>
<p>Using the <cite>__KABI_RULE</cite> macro, this rule can be defined as:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>#define KABI_TYPE_STRING(type, str) \
___KABI_RULE("type_string", type, str)
</pre></div>
</div>
<p>Example usage:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/* Override type for a structure */
KABI_TYPE_STRING("s#s",
"structure_type s { "
"member base_type int byte_size(4) "
"encoding(5) n "
"data_member_location(0) "
"} byte_size(8)");
/* Override type for a symbol */
KABI_TYPE_STRING("my_symbol", "variable s#s");
</pre></div>
</div>
<p>The <cite>type_string</cite> rule should be used only as a last resort if maintaining
a stable symbol versions cannot be reasonably achieved using other
means. Overriding a type string increases the risk of actual ABI breakages
going unnoticed as it hides all changes to the type.</p>
</section>
</section>
<section id="adding-structure-members">
<h3>Adding structure members<a class="headerlink" href="#adding-structure-members" title="Link to this heading">¶</a></h3>
<p>Perhaps the most common ABI compatible change is adding a member to a
kernel data structure. When changes to a structure are anticipated,
distribution maintainers can pre-emptively reserve space in the
structure and take it into use later without breaking the ABI. If
changes are needed to data structures without reserved space, existing
alignment holes can potentially be used instead. While kABI rules could
be added for these type of changes, using unions is typically a more
natural method. This section describes gendwarfksyms support for using
reserved space in data structures and hiding members that don’t change
the ABI when calculating symbol versions.</p>
<section id="reserving-space-and-replacing-members">
<h4>Reserving space and replacing members<a class="headerlink" href="#reserving-space-and-replacing-members" title="Link to this heading">¶</a></h4>
<p>Space is typically reserved for later use by appending integer types, or
arrays, to the end of the data structure, but any type can be used. Each
reserved member needs a unique name, but as the actual purpose is usually
not known at the time the space is reserved, for convenience, names that
start with <cite>__kabi_</cite> are left out when calculating symbol versions:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct s {
long a;
long __kabi_reserved_0; /* reserved for future use */
};
</pre></div>
</div>
<p>The reserved space can be taken into use by wrapping the member in a
union, which includes the original type and the replacement member:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct s {
long a;
union {
long __kabi_reserved_0; /* original type */
struct b b; /* replaced field */
};
};
</pre></div>
</div>
<p>If the <cite>__kabi_</cite> naming scheme was used when reserving space, the name
of the first member of the <code class="xref c c-union broken_xref docutils literal notranslate"><span class="pre">union</span> <span class="pre">must</span></code> start with <cite>__kabi_reserved</cite>. This
ensures the original type is used when calculating versions, but the name
is again left out. The rest of the <code class="xref c c-union broken_xref docutils literal notranslate"><span class="pre">union</span> <span class="pre">is</span></code> ignored.</p>
<p>If we’re replacing a member that doesn’t follow this naming convention,
we also need to preserve the original name to avoid changing versions,
which we can do by changing the first <code class="xref c c-union broken_xref docutils literal notranslate"><span class="pre">union</span> <span class="pre">member</span></code>’s name to start with
<cite>__kabi_renamed</cite> followed by the original name.</p>
<p>The examples include <cite>KABI_(RESERVE|USE|REPLACE)*</cite> macros that help
simplify the process and also ensure the replacement member is correctly
aligned and its size won’t exceed the reserved space.</p>
</section>
<section id="hiding-members">
<span id="id1"></span><h4>Hiding members<a class="headerlink" href="#hiding-members" title="Link to this heading">¶</a></h4>
<p>Predicting which structures will require changes during the support
timeframe isn’t always possible, in which case one might have to resort
to placing new members into existing alignment holes:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct s {
int a;
/* a 4-byte alignment hole */
unsigned long b;
};
</pre></div>
</div>
<p>While this won’t change the size of the data structure, one needs to
be able to hide the added members from symbol versioning. Similarly
to reserved fields, this can be accomplished by wrapping the added
member to a <code class="xref c c-union broken_xref docutils literal notranslate"><span class="pre">union</span> <span class="pre">where</span></code> one of the fields has a name starting with
<cite>__kabi_ignored</cite>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>struct s {
int a;
union {
char __kabi_ignored_0;
int n;
};
unsigned long b;
};
</pre></div>
</div>
<p>With <strong>--stable</strong>, both versions produce the same symbol version. The
examples include a <cite>KABI_IGNORE</cite> macro to simplify the code.</p>
</section>
</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/kbuild/gendwarfksyms.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>