<?xml version='1.0' encoding='utf-8'?>
<!-- -*- DocBook -*- -->
<chapter id="ch-versions">
<?dbhtml filename="ch-versions.html" ?>
<title>Version numbers and ABIs</title>
<section id="s-version-types"><title>The different types of version</title>
<variablelist>
<varlistentry>
<term>Upstream version</term>
<listitem>
<para>
The version that Linus or a stable series maintainer uses for a release.
Currently Linus will use the version format:
4.<replaceable>x</replaceable>[-rc<replaceable>y</replaceable>].  Stable series
maintainers use the version format:
4.<replaceable>x</replaceable>.<replaceable>y</replaceable>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Package version</term>
<listitem>
<para>
The version used in a Debian package.  Following Debian policy, it should
follow the format
<replaceable>upstreamversion</replaceable>-<replaceable>debianrevision</replaceable>.
However, for an upstream release candidate, the string '-rc' must be replaced
with '~rc' so that it will be recognised as an earlier version than the
following release.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Kernel version</term>
<listitem>
<para>
This is the version that appears in kernel messages, filenames, package names
and the output of 'uname -r'.  In official kernel packages it follows the
format
<replaceable>upstreamversion</replaceable>[-<replaceable>abiname</replaceable>][-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable>.
It is not changed for every new package version.  The
<replaceable>abiname</replaceable> is changed as explained below.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Many programs parse the kernel version string reported by the
<command>uname</command> system call or command and expect to find at least 3
version components separated by dots.  For compatibility, the official kernel
packages currently add '.0' to the upstream version.
</para>
</section>

<section id="s-abi"><title>The kernel ABI</title>
<para>
An ABI (Application Binary Interface) is an interface between two software
components, considered at the level of register allocation and memory layout.
The ABI between the kernel and user-space is generally maintained carefully,
and is not a concern here.  However, the ABI between the kernel and its modules
is not.  In order to support out-of-tree modules, the kernel version should be
changed when the ABI between the kernel and modules changes.
</para>
<section id="s-abi-name"><title>The ABI name</title>
<para>
In official kernel packages, we change the <replaceable>abiname</replaceable>
part of the kernel version to mark ABI changes that aren't due to a new
upstream version.  This part comes from the <literal>abiname</literal> setting
in <filename>debian/config/defines</filename>.  We use either a number or 'trunk'
(for experimental), but for a custom package it should be some other string.
</para>
</section>

<section id="s-abi-maintenance"><title>Maintaining and updating the ABI</title>
<para>
In order to avoid the need for users to rebuild out-of-tree modules frequently,
we try to avoid changing the kernel ABI during updates to a Debian stable or
oldstable release.  Most importantly, we avoid making such changes without
changing the ABI name, except where it appears that out-of-tree modules do not
depend on that part of the ABI.
</para>
<para>
Bug fixes or configuration changes to the kernel may alter the ABI.  If an
exported function is conditional on
<symbol>CONFIG_<replaceable>FOO</replaceable></symbol>, or it uses a type
whose definition depends on
<symbol>CONFIG_<replaceable>FOO</replaceable></symbol>, then turning
<symbol>CONFIG_<replaceable>FOO</replaceable></symbol> on or off changes the
ABI of that function, and thus of the kernel as a whole.  Enabling or changing
the configuration of a single driver usually doesn't change the ABI, because
most drivers don't export anything.
</para>
<para>
The kernel build process generates a 'symbol version' for each exported
function or variable.  This is a hash of the definitions that it depends on,
and should change whenever the function's ABI changes.  The kernel module
loader detects incompatible modules by comparing symbol versions.  The whole
set of symbol versions represents the kernel ABI.
</para>
<para>
We collect the symbol versions for previously uploaded packages under the
directory <filename>debian/abi</filename> and then compare the new kernel with
those.  If the ABI name is unchanged but the ABI itself is changed - except for
additions, or changes that we have marked as acceptable - then the build is
aborted.
</para>
<para>
If the kernel ABI has changed you must then change the ABI name in
<filename>debian/config/defines</filename>.  Then run the command
</para>
<screen>
<prompt>$</prompt> <userinput>fakeroot debian/rules debian/control-real</userinput>
</screen>
<para>
to regenerate the package definitions for this ABI name.
</para>
</section>

</section>

</chapter>

