Chapter 5. Version numbers and ABIs

Table of Contents

5.1. The different types of version
5.2. The kernel ABI
5.2.1. The ABI name
5.2.2. Maintaining and updating the ABI

5.1. The different types of version

Upstream version

The version that Linus or a stable series maintainer uses for a release. Currently Linus will use the version format: 4.x[-rcy]. Stable series maintainers use the version format: 4.x.y.

Package version

The version used in a Debian package. Following Debian policy, it should follow the format upstreamversion-debianrevision. 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.

Kernel version

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 upstreamversion[-abiname][-featureset]-flavour. It is not changed for every new package version. The abiname is changed as explained below.

Many programs parse the kernel version string reported by the uname 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.

5.2. The kernel ABI

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.

5.2.1. The ABI name

In official kernel packages, we change the abiname part of the kernel version to mark ABI changes that aren't due to a new upstream version. This part comes from the abiname setting in debian/config/defines. We use either a number or 'trunk' (for experimental).

If you are rebuilding the package with local modifications, you should change the ABI name to some other string, for example 0.local. Then run the command

$ debian/rules debian/control-real

to regenerate the package definitions for this ABI name.

5.2.2. Maintaining and updating the ABI

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.

Bug fixes or configuration changes to the kernel may alter the ABI. If an exported function is conditional on CONFIG_FOO, or it uses a type whose definition depends on CONFIG_FOO, then turning CONFIG_FOO 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.

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.

We collect the symbol versions for previously uploaded packages under the directory debian/abi 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.

If the kernel ABI has changed you must then change the ABI name in debian/config/defines. Then run the command

$ debian/rules debian/control-real

to regenerate the package definitions for this ABI name.