7. Kernel building recipes

Building a new kernel is typically driven by new hardware or new revisions of old hardware that are not recognized by our current kernel. There can be other reasons, but since we now have a decent journalled filesystem, NFSv3 that works reasonably well with our other computers, and ``large'' file support, the reasons are typically due to hardware. Note that we can reduce this a bit, by buying computers in identical batches where-ever possible. Building kernels for production use at CFHT should be kept to a minimum, to reduce maintenance overheads. Remember that running three different kernels instead of one exposes us to the union of the bugs in all of them!

This section attempts to explain three different approaches to adding new kernel-level hardware support to Sidious Linux. The three approaches are:

1. Adding a module for something which simply wasn't selected the last time we built the kernel. If done carefully, on another machine, I have shoe-horned the resulting new module into the production machine without changing the version.

   To do this, use a completely stand-alone machine to re-build an existing kernel without changing the name. Then extract the resulting module from /lib/modules/*/ and add them to the stable release. As long as files were only added, and stable systems were never loading a module by that name before, this method can work, but please be careful!

   Updating the /lib/modules/*/ directory for an existing kernel can work the same way for external packages. Build following their respective instructions on an isolated machine, then manually take the resulting modules over to the stable release.

   Re-run ``depmod -a'' on the stable machine after any modules are added to /lib/modules. This will update the modules.dep file.

2. The second approach, which is safer and cleaner, is to take a working kernel and re-build it with a slightly different .config. The .config is generated by running make menuconfig in the Linux source tree and selecting options and drivers. To use the Sidious .README scripts, this file must be copied to the same place as the *.README, but with a *.config filename.

3. The third approach involves updating the main kernel version. It is very similar to the second approach, but there is a higher probability that changes in the main kernel may require special attention to get everything to build correctly. Then again, those changes in the kernel itself might be what are needed to get new hardware working.

7.1 Kernel Archive Tarball

To set up any Sidious system for building a kernel, untar the latest KERNEL-*.tar.bz2 in /usr/src/. This will create a directory /usr/src/KERNEL/. If there is already one there, move it out of the way to be sure you are starting with a clean set of files. The latest kernel archive is KERNEL-2.4.26-4.tar.bz2 and should already be installed in /usr/src/ with an Sidious installation >= version 9.38d. For older Sidious installations, you can get this tar.bz2 file from the Sidious installation CDROM.

Then cd to the /usr/src/KERNEL/ directory. Summary:

# cd /usr/src
# test -d KERNEL && mv KERNEL KERNEL.OLD
# tar xjf KERNEL-2.4.26-4.tar.bz2
# cd KERNEL

After untarring this file, there are two other pieces needed to build a kernel for Sidious. One is the .README file which lists the patches and modules, and the other is the .config file which is a standard Linux kernel configuration file as generated by make menuconfig. The following sections explain how to set up these two files.

7.2 Setting up a .README file

The KERNEL tar file includes several example .README files. If you want a kernel most similar to the modular laptop kernel, starting with a copy of linux-2.4.19-si6.README or linux-2.4.26-smp4.README (or any later version) is recommended. For building a multiprocessor or large memory model kernel, start with linux-2.4.26-smp4.README. Here are the steps:

1. Copy this file to your own name, such as linux-2.4.26-test1.README Also copy closest .config to a name like linux-2.4.26-test1.config

   [ASIDE: The number after the ``test'' or ``si'' or ``smp'' is intended to indicate whether or not this is just an experimental build that could be in flux, or a stable released version. ODD numbers are experimental and may vary. EVEN numbers are released and should not change.]

2. Now open linux-2.4.26-test1.README in a text editor and change the KVERSION= and CONFIG= lines at the top to match the name you chose. Rebuilding an existing or stable kernel version without changing the name can cause a lot of confusion.

3. Comment/uncomment/add and P=... lines for any patches you need.

4. Comment out any build_modules_* lines at the bottom if you feel they may fail or you don't need them (for production release kernels, it is nice to leave as many of these in as possible.)

In summary:

# cp linux-2.4.26-smp4.README linux-2.4.26-test1.README
# cp linux-2.4.26-smp4.config linux-2.4.26-test1.config
# vi linux-2.4.26-test1.README

7.3 Setting up a .config file

There are many ways to end up with a valid kernel .config file. The only tricky part is that some of the patches may add new options, so you want to generate the .config from a kernel tree that includes all your patches. The easiest way to do that is as follows:

1. Having followed the steps so far to set up the .README, now simply run the .README.
2. At some point the script may prompt you if there are an questions unanswered by your current .config (due to new features or something added by a patch.) Hit ? for help, and then decided Y (yes) N (no) or M (module) for each of these.
3. If there are no new questions, or after you've answered them all, the script will begin building the kernel (you'll see ``make dep ...'' followed by a bunch of gcc lines.) At this point, interrupt the build process by pressing control-C.
4. Next, if there are any options you want to change, go into the linux-2.4.26-test1 (or the name you chose) directory and run ``make menuconfig''. This utility is essentially an editor for the .config file.
5. The only thing you want from all of this is the resulting .config file. Copy it from the kernel directory to /usr/src/KERNEL/linux-2.4.26-test1.config (or whatever you are building) and completely remove linux-2.4.26-test1 that got created.

7.4 Building the Kernel

In the /usr/src/KERNEL/ directory from KERNEL-2.4.26-4.tar.bz2 (or newer), and with the two files, .README and .config which you created in the previous steps, it is now possible to build a kernel. Given the example of 2.4.26-test1, the script will produce files in the following locations:

/usr/src/KERNEL/linux-2.4.26-test1/
/lib/modules/2.4.26-test1/
/boot/kernel-2.4.26-test1
/boot/System.map-2.4.26-test1

All of these must be removed or renamed first to produce a clean build!

Then:

1. Run the linux-2.4.26-test1.README script.
2. Edit your lilo.conf (see instructions in the previous section) and re-run lilo to add the new kernel.
3. Reboot into the new kernel.
4. Run the linux-2.4.26-test1.README script again to finish compiling some of the modules that are not part of the main kernel source.

That's it! The files listed at the beginning of this section (/lib/modules/linux-2.4.26-test1 and /boot/kernel-2.4.26-test1) can be transplanted to another system, or if your kernel was called -smp* or -rtai*, an etherboot image should also exist now in /tftpboot/.