Logoj0ke.net Open Build Service > Projects > GFS > kernel-source > README.SUSE
Sign Up | Log In

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