Building a Linux kernel for FullPliant

This document is assuming Pliant release 108 or more.

Overview

This document is intended to provide more than a step by set set of instructions about how to build a Linux kernel for FullPliant. It is intended to explain what's going under the hood so that you can cope with any unexpected situation.

In order to compile a kernel for FullPliant, you need to collect several pieces:

We suggest that you create a file:/pliant_archive/kernel_source/ directory and put all the collected stuff here since it's where the Pliant scripts will default pick them. Also you don't need that if you plan to do everything by hand, as explained in the various 'alternative' paragraphs bellow.

Moreover, in order to build a Linux kernel, you need more Linux tools than available in the core part of FullPliant (as an example, you need GCC C compiler).
So, you need to do that on Pliant instance running in a standard Linux distribution such as Ubuntu. On a box running FullPliant, the standard Linux distribution shall run as a virtual (KVM emulated) computer provided your box be equipped with a VT enabled processor, and you have enough memory (1 GB should be ok).
If the distribution is Ubuntu Karmic, you need to install the two extra following optional packages (through typing something like 'sudo dpkg install package_name'):
  patch
  libncurses5-dev

Collecting the data

Downloading Linux kernel source

Download various tarballs from http://www.kernel.org/pub/linux/kernel/v2.6/
to your 'file:/pliant_archive/kernel_source/' directory.

If you expect to compile Linux 2.6.32.2,
you could have as well download l'inux-2.6.29.tgz'
plus 'patch-2.6.30.tgz'
plus 'patch-2.6.31.tgz'
plus 'patch-2.6.32.tgz'
plus 'patch-2.6.32.2.tgz'
Pliant kernel installation script will be abble to apply the patches sequence so that you don't need to download the full kernel tarball with each new release.

Downloading 'fullpliant.patch' FullPliant kernel patch

On a running FullPliant system, the 'fullpliant.patch' that have been used to build the kernel is available in 'file:/boot/' directory.
Copy it to your 'file:/pliant_archive/kernel_source/' directory.

Alternatively, you can download it from http://www.fullpliant.org/download/

Downloading kernel '.config' conguration file

On a running FullPliant system, the '.config' kernel configuration file that have been used to build the kernel is available in 'file:/boot/' directory.
Copy it to your 'file:/pliant_archive/kernel_source/' directory.

Alternatively, you can download it from http://www.fullpliant.org/download/

As a third solution you can build the '.config' kernel configuration file from scratch:

Building the kernel

1. Unpacking

Use 'Install kernel' button to unpack the tarballs and apply patches.
It will create 'file:/usr/src/a/' directory with the vanilla Linux kernel source,
and 'file:/usr/src/b/' with the one patched for FullPliant.

Alternatively, you can install the kernel source by hand through untaring the kernel tarball, applying the various patches, and copying the .config file.

2. Configuring

Then open a Linux shell prompt, and type in:
  cd /usr/src/b
  make menuconfig
It is a good idea to check what you have in 'Processor type and features' / 'High memory support'. On a generic kernel, it's a good idea to leave it to 4 GB, but the optimal is to set it to 'off' for computers with 1 GB or less of memory, and use a 64 bits kernel (see bellow) on computers with more than 1 GB of memory and a processor with 64 bits support.
In the end, always select 'Exit' in order to build a fresh '.config' file that matches your exact kernel version.

If you want to compile a 64 bits kernel, what you have to type in is rather:
  cd /usr/src/b
  make ARCH=x86_64 menuconfig
and don't forget to check that, in 'Executable file format', 'IA32 emulation' be set.
Starting from 2.6.35 kernel, I found easier to start form the Ubuntu .config for both the 32 bits and the 64 bits kernel, instead of building the 64 bits one through just changing a few options in the 32 bits one.

As a summary, if you have more than 1 GB of memory, or if you have a disk or RAID set with 2 TB or more, and if your processor has 64 bits support, then it's a good idea to compile a 64 bits kernel, even if you run only 32 bits softwares.

3. Compiling and building the kernel tarball

Finally, use 'Build kernel' button to build the Linux kernel tarball suited for FullPliant.
It will be stored as file:/pliant_archive/kernel.tgz

Alternatively, you could use 'make bzImage' and 'make modules' to compile the kernel, but then you need either to install various kernel pieces by hand, or type in a few more commands to build the kernel tarball. See /pliant/fullpliant/build/kernel.ui source code for extra details about kernel tarball packaging: it's fairly straightforward to read.

Installing the new kernel

Select 'Install' 'Upgrade kernel' from FullPliant main menu.

Alternatively, you can untar the kernel tarball in 'file:/' then run 'lilo -C /boot/lilo.conf' in order to make it bootable. See /pliant/fullpliant/install/kernel.ui for details.

Recovering a broken kernel

If your FullPliant system does not boot any more because the kernel does not load or is not suited for your hardware, then here is how to reinstall a kernel in a FullPliant system by hand:

We assume that:

In order to extract the kernel follow 'Tools' 'Interpreter' menu, an run the following program:
  file_extract "file:/pliant_archive/kernel.tgz" "file:/mnt/foo/"

In order to make it bootable, follow 'Tools' 'Execute' menu, then set root path field to
  file:/mnt/foo/
and run the following command:
  lilo -C /boot/lilo.conf

FullPliant kernel patch documentation

Here are the description of the changes applied to Linux Kernel through 'fullpliant.patch':

FullPliant initrd.img

When booting from an USB key or disk, the USB device is not immediately available because USB device detection is dynamic and takes a few seconds. So, if trying to boot the standard way, the kernel would just complain that it does not find the root (USB device) partition, then stop.

In order to solve the issue, FullPliant uses an initrd image. An initrd image is a small filesystem that 'lilo' boot loader loads at the same time as the kernel, and that the kernel will use to run some programs it picks on the filesystem before trying to mount the effective root filesystem. This is used by some Linux distributions to enable to have disk drivers as dynamically loaded modules as opposed to being statically compiled as in Ubuntu or FullPliant kernel.
In FullPliant, the program run within initrd is /pliant/fullpliant/linuxrc.c and it's effect is just to wait for the root partition to pop up. The right root partition will be recognized thanks to it's label which must be 'pliant_usb'.

The 'initrd.img' is built by the /pliant/fullpliant/install/disk.ui script used to create the bootable Linux USB key. More precisely, the script calls 'fullpliant_install' function in module /pliant/fullpliant/install.pli that calls 'fullpliant_initrd' function that tries to build a fresh initrd image.
If compiling 'linuxrc.c' fails because under FullPliant, there is no GCC C compiler available, then the file:/bin/linuxrc one will be reused, and this one had been build at the time FullPliant executables have been built.
If building 'initrd.img' completely fails because the kernel lacks loopback support or something like that, then the existing file:/boot/initrd.img will be reused.