1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
<chapt id="versions">
<heading>Version numbers and ABIs</heading>
<sect id="version-types">
The different types of version
<p>
<taglist>
<tag>Upstream version</tag>
<item>
The version that Linus or a stable series maintainer uses
for a release. Currently Linus will use the version
format: 3.<var>x</var>[-rc<var>y</var>]. Stable series
maintainers use the version format:
3.<var>x</var>.<var>y</var>.
</item>
<tag>Package version</tag>
<item>
The version used in a Debian package. Following Debian
policy, it should follow the format
<var>upstreamversion</var>-<var>debianrevision</var>.
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.
</item>
<tag>Kernel version</tag>
<item>
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
<var>upstreamversion</var>[-<var>abiname</var>][-<var>featureset</var>]-<var>flavour</var>.
It is not changed for every new package version.
The <var>abiname</var> is changed as explained below.
</item>
</taglist>
</p>
<p>
Many programs parse the kernel version string reported by
the <tt>uname</tt> 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, but this will be dropped in
wheezy+1.
</p>
</sect>
<sect id="abi">
The kernel ABI
<p>
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.
</p>
<sect1 id="abi-name">
The ABI name
<p>
In official kernel packages, we change the
<var>abiname</var> part of the kernel version to mark ABI
changes that aren't due to a new upstream version. This
part comes from the <tt>abiname</tt> setting in
<tt>debian/config/defines</tt>. We use either a number or
'trunk' (for experimental), but for a custom package it
should be some other string.
</p>
</sect1>
<sect1 id="abi-maintenance">
Maintaining and updating the ABI
<p>
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.
</p>
<p>
Bug fixes or configuration changes to the kernel may alter
the ABI. If an exported function is conditional on
<tt>CONFIG_</tt><var>FOO</var>, or it uses a type whose
definition depends on <tt>CONFIG_</tt><var>FOO</var>, then
turning <tt>CONFIG_</tt><var>FOO</var> 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.
</p>
<p>
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.
</p>
<p>
We collect the symbol versions for previously uploaded
packages under the directory <tt>debian/abi</tt> 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.
</p>
<p>
If the kernel ABI has changed you must then change the ABI
name in <tt>debian/config/defines</tt>. Then run the
command
<example>
$ fakeroot debian/rules debian/control-real
</example>
to regenerate the package definitions for this ABI name.
</p>
</sect1>
</sect>
</chapt>
|
