**************************************
	***                                ***
	***  THIS IS AN UNFINISHED DRAFT ! ***
	***                                ***
	**************************************

WORKING WITH THE SUSE AND UNITED LINUX KERNEL SOURCES

Andreas Gruenbacher <agruen@suse.de>, SuSE Labs, May 2003


OVERVIEW

Kernels for SuSE and United Linux are generated from the vanilla kernel
sources found at http://ftp.kernel.org/, on top of which a set of
additional patches is applied. The resulting kernel source tree is
configured for a specific kind of system. The configurations are named
default, smp, athlon, etc. The configured kernel source tree is then
built, resulting in a binary kernel.

The patches and configuration files that make up the kernels are
maintained in a CVS repository. Those with access to the CVS repository
can use the scripts/tar-up.sh script to package up the repository for
processing by RPM.

The process of generating binary kernels from the vanilla kernel sources
plus patches is split into two phases. The first phase takes the kernel
sources and patches and produces a kernel-source package that contains
the fully patched kernel source tree. This package already contains the
configuration files for the binary kernels.  The second phase takes the
kernel-source package, configures the source tree appropriately using
one of the configuration files, and builds the binary kernel package.
The binary packages (and their configuration files) are named
k_deflt(default), k_smp(smp), k_athlon(athlon), etc.

Each of the above phases is usually performed by RPM, but can also be
performed by hand. 

COMPILING THE KERNEL


KERNEL SOURCES (PER ARCHITECTURE)

Beginning with SuSE Linux 8.3, the kernel sources are installed in the
/usr/src/linux-$VERSION.$PATCHLEVEL.$SUBLEVEL-$CONFIG_RELEASE directory
(e.g., /usr/src/linux-2.4.21-95).  Several architectures are using
architecture specific patches, so the kernel sources differ among
architectures.  On each architecture, all binary kernels are generated
from these kernel sources.


BINARY KERNELS AND THEIR CONFIGURATION FILES

The binary kernels differ in the configuration options used.  The kernel
sources contain all configuration files relevant for a given
architecture.  The configuration file for a kernel configuration named
$CONFIG_CFGNAME is named arch/$ARCH/defconfig.$CONFIG_CFGNAME (e.g.,
arch/i386/defconfig.smp).  The release name of a binary kernel with a
configuration name of $CONFIG_CFGNAME will be
$VERSION.$PATCHLEVEL.$SUBLEVEL-$CONFIG_RELEASE-$CONFIG_CFGNAME (e.g.,
2.4.21-95-smp).

We will be using module versioning support (CONFIG_MODVERSIONS).


KERNEL MODULES (KM_* PACKAGES)


PATCHES AND PATCH SELECTION

The patches are now managed in a more flexible and transparent way. The
file series.conf supersedes the old sequence-numbers file.

Sequence-numbers has been translated to series.conf so that the patch
sequences remain identical (unless I did something wrong). This means
that series.conf is still in a state of mess; we will probably clean
things up a lot more. The sequence-numbers file is still there for
reference, and series.conf includes the previous sequence numbers just
in case. Those left-overs will eventually go away as well.

Patch selection now works as follows. Patches are applied in the order
in wihch they are listed in series.conf. Architecture dependencies are
defined as conditionals in series.conf itself. The patch selection
logic should be obvious from comments in series.conf.

Instead of packaging up patches with sequence numbers prepended, the
patches are now packaged up as they are. All scripts use the same patch
selection mechanism; this includes kernel-source.spec, which up to now
had a separate selection mechanism.

A plain list of patches that are relevant for a given architecture can
be generated with the following command, $SYMBOLS being a list of
architecture symbols that direct the selection mechanism:

        $ scripts/guards $SYMBOLS < series.conf

	(On an i586 system, $SYMBOLS would be "i586 IA32"; all other
	symbols
	used on other architectures are documented in series.conf.)

	The sequence-patch.sh and tar-up.sh scripts have been updated to
	use the
	new selection mechanism. (I am leaving the other scripts alone
	since I
	am not using any of them; please update as you see fit.) As
	before, the
	kernel sources can be patched up for a specific architecture
	like this:

	$ PATCH_ARCH=ia64 scripts/sequence-patch.sh

It is possible to mark patches that are experimental and not to be
included by default with extra symbols in series.conf, like I have just
done for the NFS ACL patches (they are marked with `+nfs_acl).

The consequence is that those patches won't be included in the normal
kernel build.

Test kernels with those patches can be built by putting these extra
symbols in the file `extra-symbols' in the CVS checkout directory or
kernel-source directory (similar to the skip-build file), e.g.,

	echo "nfs_acl" > extra-symbols


SCRIPTS

sequence-patch.sh
tar-up.sh
guards
arch-symbols
check-conf
config.sh

this is just to remind you of scripts/check-conf, which checks the
series.conf file against the patches.* directories. It warns about
patches that are listed but don't exist, and about patches that exist
but are not referenced in series.conf.

I have attached the current (sorted) output of check-conf.

Patches you want to keep in the CVS but which shall not to be included
on any architectures can be prefixed with `-' in patches.series;
check-conf will then not complain about such patches anymore. (Of
course it makes little sense to mark the currently unmerged patches
like that.)