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