This document describes what the kernel ABI is, how we enforce it, and possible ways to improve tracking.
ABI stands for Application Binary Interface. For the kernel, this boils down to the exported functions that modules (AKA drivers) can use to do things in kernel space. Most of these exported functions are available directly from the kernel (vmlinux), but a good portion is also exported from other modules. These functions allow modules to make use of subsystems in the kernel for memory management, device interfaces, filesystems (VFS), networking stacks, etc.
For the most part, users don't need to worry about the kernel ABI, but in some cases it can affect them. Most times, it's when they have a locally built module (e.g. vmware kernel modules). If the kernel ABI changes, these modules may not load any more.
For this reason, we track ABI. Not so much to avoid these problems, but to make it more apparent that it has changed.
How ABI is Tracked
For each build of the kernel, we get a list of exported functions. This is in a file called Modules.symver in the build. We slightly prepare this file and include it in the linux-image package as /boot/abi-KERNEL_VER. The ABI files for the last build are included in our packaging so that the next build can compare the new build with the last build's ABI. If it has changed, we increment our ABI number to denote this change.
How can I tell the ABI?
The ABI is included as part of the kernel version. If you run the command uname -r you will see something like 2.6.26-4-generic. The 4 in this example is the ABI. Numerically, it means nothing, except that it has changed since 3 and will be 5 when it changes again.
What sort of checks are enforced
There are several checks in our script (debian/scripts/abi-check in our build tree). Each has it's own meaning.
ABI changing checks
When the new build removes symbols that were in the previous build, this is definitely an ABI changing event.
This is the most common cause of an ABI increment. It means that the calling convention of a function has changed (which usually means an internal structure passed to the function, or returned from the function, has changed members).
This is noticed because the hash associated with the function changes. The hash is created based on the functions passed arguments and return type.
Non-ABI changing checks
These checks are informational only. They usually would not cause us to increment the ABI, but they do show us what is happening in the kernel.
This check is done to see if the new build has added symbols.
Symbols are exported differently in the kernel. In most cases, it's just a generic export, but other types include GPL-ONLY exports. This means that only GPL compatible modules can make use of them. Upstream policy is to never change a general export to a GPL-ONLY one, but we track it none-the-less.
Symbols can some times move around depending on whether a module is built-in, or is renamed. This helps us to track what part of the kernel is providing different symbols.
In some cases we will add exceptions for certain symbols or symbol groups. An example of this is the p80211 module, which exports several functions for use only by the prism2_usb module. In addition, these functions are not exported in headers for other modules to build against.
Since the two modules are built at the same time in the same source tree, there is no chance for skew between them, and as such, we do not care if the ABI changes. The p80211 module as a whole is blacklisted from the ABI checks (in debian/abi/perm-blacklist).
Note that exceptions are only supported in intrepid/8.10 and beyond (although we may backport this hardy/8.04 at some point).