File README.SUSE of Package kernel-source (Revision 0949719ee5a672e1198991dd8bfaa8cb)
Currently displaying revision 0949719ee5a672e1198991dd8bfaa8cb, show latest
1
WORKING WITH THE SUSE 2.6.x KERNEL SOURCES
2
3
Andreas Gruenbacher <agruen@suse.de>, SUSE Labs, 2003, 2004, 2005, 2006
4
5
6
This document gives an overview of how SUSE Linux kernels are
7
created, and describes tasks like building individual kernels
8
and creating external kernel modules.
9
10
A companion Update Media HOWTO that describes how to build driver update
11
disks (among other things) is available at:
12
13
ftp://ftp.suse.com/pub/people/hvogel/Update-Media-HOWTO.
14
15
16
TABLE OF CONTENTS
17
18
Overview
19
Compiling your own kernel
20
Building additional (external) modules
21
Supported vs. unsupported modules
22
Patch selection mechanism
23
Where to find configuration files
24
How to configure the kernel sources
25
Module load paths
26
27
28
OVERVIEW
29
30
The kernels for SUSE are generated from the vanilla Linux kernel sources
31
found at http://ftp.kernel.org, on top of which a number of patches are
32
applied. The resulting kernel source tree is configured and built,
33
resulting in a binary kernel.
34
35
Internally, the add-on patches and configuration files are maintained in
36
a CVS repository. A script (scripts/tar-up.sh) packs up the files in the
37
CVS repository in a form suitable for rpmbuild. When building the RPM
38
packages, the following binary packages get created:
39
40
* kernel-source
41
42
The kernel source tree, generated by unpacking the vanilla kernel
43
sources and applying the patches. The kernel sources are used by
44
a number of other packages. They can also be used for compiling
45
additional kernel modules.
46
47
* kernel-$FLAVOR
48
49
A number of binary kernels (for example, kernel-default for
50
uniprocessor machines, kernel-smp for smp machines, etc.). These
51
packages are all generated from the same kernel sources, and
52
differ in the kernel configurations used.
53
54
* kernel-syms
55
56
Kernel symbol version information for compiling external modules:
57
Functions and data structures that the kernel exports have version
58
information attached. When loading kernel modules, this version
59
information is used to make sure that the modules match the running
60
kernel.
61
62
* kernel-dummy
63
64
This package is relevant inside the SUSE build system only. We use
65
it to synchronize release numbers among the kernel packages. When
66
building packages locally, the kernel-dummy package can safely be
67
ignored.
68
69
70
The CVS repository contains the configuration files (.config) for all
71
SUSE kernel flavors. All configuration files are included in the
72
kernel-source package (see WHERE TO FIND CONFIGURATION FILES below).
73
74
75
In the installed system, the kernel-source package installs files in the
76
following directories:
77
78
79
* /usr/src/linux-$VERSION-$RELEASE/
80
81
The kernel sources.
82
83
* /usr/src/linux
84
85
A symbolic link to /usr/src/linux-$VERSION-$RELEASE.
86
87
* /usr/src/linux-$VERSION-$RELEASE-obj/$ARCH/$FLAVOR/
88
89
Kernel build object files for one kernel flavor. These
90
files are used for compiling additional kernel modules.
91
92
* /usr/src/linux-obj
93
94
A symbolic link to /usr/src/linux-$VERSION-$RELEASE-obj/$ARCH/$FLAVOR.
95
96
* /usr/share/doc/packages/kernel-source/
97
98
This document and an external kernel module example.
99
100
* /etc/init.d/running-kernel
101
102
Init script that adapts the kernel sources in /usr/src/linux to
103
the running kernel.
104
105
106
COMPILING YOUR OWN KERNEL
107
108
The kernel sources are found in the kernel-source.$ARCH.rpm package. The
109
recommended way to produce a binary kernel is:
110
111
(1) Install kernel-source.$ARCH.rpm. Change to the /usr/src/linux
112
directory.
113
114
(2) Configure the kernel (for example, ``make oldconfig'' or ``make
115
cloneconfig'', see HOW TO CONFIGURE THE KERNEL SOURCES).
116
117
(3) Build the kernel and all its modules (``make'').
118
119
(5) Install the kernel and the modules (``make modules_install'',
120
followed by ``make install''). This will automatically create
121
an initrd for the new kernel as well (see ``mkinitrd -h'').
122
123
(6) Add the kernel to the boot manager. When using lilo, run ``lilo''
124
to update the boot map.
125
126
Instead of building binary kernels by hand, you can also build
127
one of the kernel-$FLAVOR packages using RPM.
128
129
130
BUILDING ADDITIONAL (EXTERNAL) MODULES
131
132
A single binary kernel module generally only works for a specific
133
version of the kernel source tree, for a specific architecture and
134
configuration. This means that for each binary kernel that SUSE ships, a
135
custom module must be built. This requirement is to some extent relaxed
136
by the modversion mechanism: modversions attach a checksum to each
137
symbol (function or variable) exported to modules by the kernel. This
138
allows to use kernel modules that have been built for a kernel with a
139
different version or release number in many cases, as long as none of
140
the symbols the module uses have changed between the two kernel
141
versions.
142
143
When releasing maintenance or security update kernels for a specific
144
product, we carefully try to keep the kernel ABI stable. Despite this,
145
we sometimes have no choice but to break binary compatibility. In this
146
case, those kernel modules must be rebuilt.
147
148
Additional kernel modules for one of the SUSE kernel flavors can be
149
built in three different ways:
150
151
(1) by configuring the kernel sources in /usr/src/linux (or a copy,
152
see HOW TO CONFIGURE THE KERNEL SOURCES), or
153
154
(2) by using one of the standard configurations in
155
/usr/src/linux-obj/$ARCH/$FLAVOR, or
156
157
(3) by creating a Kernel Module Package (KMP) as described in the
158
Kernel Module Packages Manual, http://www.suse.de/~agruen/KMPM/.
159
160
161
The first method involves the following steps:
162
163
(1) Install kernel-source.$ARCH.rpm.
164
165
(2) Change to the /usr/src/linux directory. Configure the kernel
166
(for example, ``make oldconfig'' or ``make cloneconfig'', see
167
HOW TO CONFIGURE THE KERNEL SOURCES).
168
169
(3) Create files required for compiling external modules:
170
``make scripts'' and ``make prepare''.
171
172
(4) Compile the module(s) by changing into the module source directory
173
and typing ``make -C /usr/src/linux M=$(pwd)''.
174
175
(5) Install the module(s) by typing
176
``make -C /usr/src/linux M=$(pwd) modules_install''.
177
178
179
The second method involves the following steps:
180
181
(1) Install kernel-source.$ARCH.rpm.
182
183
(2) Install kernel-syms.$ARCH.rpm. This package is necessary for
184
symbol version information (CONFIG_MODVERSIONS).
185
186
(3) Compile the module(s) by changing into the module source directory
187
and typing ``make -C /usr/src/linux-obj/$ARCH/$FLAVOR M=$(pwd)''.
188
Substitute $ARCH and $FLAVOR with the architecture and flavor
189
for which to build the module(s).
190
191
If the installed kernel sources match the running kernel, you
192
can build modules for the running kernel by using the path
193
/lib/modules/$(uname -r)/build as the -C option in the above
194
command. (build is a symlink to /usr/src/linux-obj/$ARCH/$FLAVOR).
195
196
Starting with SuSE Linux 9.2 / SLES9 Service Pack 1, the
197
modversion information for the running kernel is also
198
contained in the kernel-$FLAVOR packages, and so for building
199
modules for the running kernel, the kernel-syms package is no
200
longer required.
201
202
(4) Install the module(s) with
203
``make -C /usr/src/linux-obj/$ARCH/$FLAVOR M=$(pwd) modules_install''.
204
205
206
Whenever building modules, please use the kernel build infrastructure as
207
much as possible, and do not try to circumvent it. The
208
Documentation/kbuild directory in the kernel sources documents kbuild
209
makefiles.
210
211
Please take a look at the demo module installed under
212
/usr/share/doc/packages/kernel-source for a simple example of an Kernel
213
Module Package (KMP).
214
215
216
SUPPORTED VS. UNSUPPORTED MODULES
217
218
As an extension to the mainline kernel, modules can be tagged as
219
supported (directly by SUSE, or indirectly by a third party) or
220
unsupported. Modules which are known to be flakey or for which SUSE does
221
not have the necessary expertise are marked as unsupported. Modules for
222
which SUSE has third-party support agreements are marked as externally
223
supported. Modules for which SUSE provides direct support are marked as
224
supported.
225
226
The support status of a module can be queried with the modinfo tool.
227
Modinfo will report one of the following:
228
229
- direct support by SUSE: "supported: yes"
230
- third-party support: "supported: external"
231
- unsupported modules: no supported tag.
232
233
At runtime, the setting of the" unsupported" kernel command line
234
parameter and /proc/sys/kernel/unsupported determines whether
235
unsupported modules can be loaded or not, and whether or not loading an
236
unsupported module causes a warning in the system log:
237
238
0 = only allow supported modules,
239
1 = warn when loading unsupported modules,
240
2 = don't warn.
241
242
Irrespective of this setting, loading an externally supported or unsupported
243
module both set a kernel taint flag. The taint flags are included in
244
Oopses. The taint status of the kernel can be inspected in
245
/proc/sys/kernel/tainted: Bits 0 to 4 have the following meanings:
246
247
bit 0 = a module with a GPL-incompatible license was loaded (tainted & 1),
248
bit 1 = module load was enforced (tainted & 2),
249
bit 2 = an SMP-unsafe module was loaded (tainted & 4),
250
bit 3 = (reserved),
251
bit 4 = an unsupported module was loaded (tainted & 16),
252
bit 5 = a module with third-party support was loaded (tainted & 32).
253
bit 10 = a machine check exception has occurred (taint & 1024; x86_64 only
254
so far).
255
256
The corresponding codes for the taint flags in Oopses are (x = unknown):
257
258
- "Pxxx" if bit 0 set or else
259
"Gxxx" if bit 0 unset,
260
261
- "xFxx" if bit 1 set or else
262
"x xx" if bit 1 unset,
263
264
- "xxSx" if set or else
265
"xx x" if bit 2 unset,
266
267
- "xxxU" if bit 4 set or else
268
"xxxX" if bit 5 set or else
269
"xxx ".
270
271
By default, external modules will not have the supported flag (that is,
272
they wil be marked as unsupported). For building externally supported
273
modules, please get in touch with Kurt Garloff <garloff@suse.de>.
274
275
276
PATCH SELECTION MECHANISM
277
278
The SUSE kernels consist of the vanilla kernel sources on top of which a
279
number of patches is applied. Almost all of these patches are applied on
280
all architectures; a few patches are only used on a subset of
281
architectures. The file series.conf determines which patches are applied
282
on which architectures. A script named "guards" converts series.conf
283
into a plain list of patch files to be applied. Guards decides which
284
patches to include and exclude based on a list of symbols. The symbols
285
used by default are computed by the helper script "arch-symbols". From
286
the kernel-source.src.rpm package, a fully patched kernel source tree
287
can be generated from vanilla sources + patches like this:
288
289
# Install the package:
290
291
$ rpm -i kernel-source.src.rpm
292
293
# Unpack the patches and the kernel sources:
294
295
$ cd /usr/src/packages/SOURCES
296
$ for f in patches.*.tar.bz2; do \
297
tar xfj $f || break; \
298
done
299
$ tar xfj linux-2.6.5.tar.bz2
300
301
# Apply the patches
302
303
$ for p in $(./guards $(./arch-symbols) < series.conf); do
304
patch -d linux-2.6.5 -p1 < $p || break
305
done
306
307
The configuration script config.conf which is similar to series.conf is
308
used for configuration file selection. See the section WHERE TO FIND
309
CONFIGURATION FILES.
310
311
The file format of series.conf and config.conf should be obvious from
312
the comments in series.conf, and from the guards(1) manual page. (The
313
guards(1) manual page can be generated by running pod2man on the guards
314
script.)
315
316
317
WHERE TO FIND CONFIGURATION FILES
318
319
Kernel configuration files are stored in the kernel CVS repository. When
320
packing up the repository, they end up in config.tar.bz. When
321
kernel-source.$ARCH.rpm is built, the config files are copied from
322
config/$ARCH/$FLAVOR to .config in the kernel source tree.
323
324
The kernel-$FLAVOR packages are based on config/$ARCH/$FLAVOR.
325
(kernel-default is based on config/$ARCH/default, for example).
326
The kernel-$FLAVOR packages install their configuration files as
327
/boot/config-$VER_STR (for example, /boot/config-2.6.5-99-default) as
328
well as /usr/src/linux-obj/$ARCH/$FLAVOR/.config.
329
330
In addition, the running kernel exposes a gzip compressed version of its
331
configuration file as /proc/config.gz. The kernel sources can be
332
configured based on /proc/config.gz with ``make cloneconfig''.
333
334
335
HOW TO CONFIGURE THE KERNEL SOURCES
336
337
Before a binary kernel is built or an additional loadable module
338
for an existing kernel is created, the kernel must be configured.
339
340
In order for a loadable module to work with an existing kernel, it must
341
be created with a configuration that is identical to the kernel's
342
configuration, or at least very close to that. Each configuration is
343
contained in a single file. The kernel-source package contains
344
configurations for all standard SUSE kernel variants, so for building
345
only external kernel modules it is not necessary to configure the kernel
346
sources.
347
348
Configuring the kernel sources for a specific configuration is
349
straightfoward:
350
351
- Locate the configuration file you want to use. (See WHERE TO FIND
352
CONFIGURATION FILES above).
353
354
- Copy the configuration to the file .config in the kernel source
355
tree. The kernel-source package installs its source tree in
356
/usr/src/linux.
357
358
- Run the following commands in sequence to apply the configuration,
359
generate version information files, etc.:
360
361
make clean
362
make oldconfig
363
364
Alternatively to ``make oldconfig'', you can also use ``make
365
menuconfig'' for a text menu oriented user interface. If the kernel
366
sources do not match the configuration file exactly, ``make
367
oldconfig'' will prompt for settings that are undefined.
368
369
For configuring the kernel to match the running kernel, there is a
370
shortcut ``make cloneconfig'' that expands the file /proc/config.gz
371
into .config, and then runs ``make oldconfig''.
372
373
374
MODULE LOAD PATHS
375
376
Modules that belong to a specific kernel release are installed in
377
/lib/modules/2.6.5-99-smp and similar. Note that this path contains the
378
kernel package release number. Modules from KMPs must be installed
379
below /lib/modules/2.6.5-99-smp/updates/ and similar: modules below
380
updates/ have priority over other modules.
381
382
When KMPs contain modules that are compatible between multiple installed
383
kernels, symlinks are used to make those modules available to those
384
compatible kernels like this:
385
386
/lib/modules/2.6.16-100-smp/weak-updates/foo.ko ->
387
/lib/modules/2.6.16-99-smp/updates/foo.ko
388
389
Modules in the weak-updates directory have lower priority than modules
390
in /lib/modules/2.6.16-100-smp/updates/, and higher priority than other
391
modules in /lib/modules/2.6.16-100-smp.
392
393
394
REFERENCES
395
396
General
397
398
Documentation in the kernel source tree.
399
400
Linux Documentation Project, http://www.tldp.org/
401
402
Linux Weekly News, http://lwn.net
403
404
Rusty's Remarkably Unreliable Guides (Kernel Hacking
405
and Kernel Locking guides),
406
http://www.netfilter.org/unreliable-guides/
407
408
Kernel newbies, http://www.kernelnewbies.org/
409
410
411
Loadable Kernel Modules
412
413
Peter Jay Salzman and Ori Pomerantz: Linux Kernel Module
414
Programming Guide, Version 2.4, April 2003,
415
http://www.tldp.org/guides.html
416
417
418
Kernel Module Packages
419
420
Andreas Gruenbacher: Kernel Module Packages Manual.
421
Versions for CODE9 (SLES9, SUSE LINUX 10.0) and CODE10
422
(SUSE Linux 10.1, SLES10),
423
http://www.suse.de/~agruen/KMPM/
424