Gentoo Linux Genkernel Guide

1. Introduction

Introduction 

Genkernel is designed to allow users who are not previously used to compiling a kernel to use a similar setup to that one that is used on the Gentoo LiveCDs which auto-detects your hardware.

Some users may also be interested in using genkernel for hardware which requires initialization and a working kernel before it can be booted. Because genkernel also automatically compiles your kernel modules, thus allowing hardware which needs to be loaded with module parameters to be used.

Is genkernel for me? 

Genkernel is often a good choice to those who are unused to compiling their own kernel or those who are not certain about their hardware configurations.

Because genkernel is designed to use a generic configuration, it should be able to support all of your hardware - however, because all the drivers and modules have to be compiled as well, compiling a kernel by yourself is often much faster provided you know what you need.

Genkernel does not however, currently support booting the sytem from LVM2/EVMS2 partitions. Users are recommended to use a manually compiled kernel for the time being.

Getting genkernel 

You can obtain genkernel by simply running emerge genkernel. Don't forget to use the -k flag for emerge if you are using binary packages, i.e. GRP. Due to the GRP packages having an older version of genkernel, the flags are different. As a result, you should consult the Gentoo Handbook and genkernel --help.

Supported platforms 

As of genkernel 3.0.2; the following platforms should be supported: alpha, amd64, parisc, parisc64, ppc, ppc64, sparc, sparc64, and x86. If you believe that there is a bug with the support code, and not with genkernel, please file a bug at the Gentoo Bugzilla.

2. Genkernel usage

Introduction 

Genkernel is designed to work in three modes:

• "all" mode: this builds the kernel and the initrd
• "kernel" mode: this only builds the kernel image
• "initrd" mode: this only builds the initrd

Most users will only want the "all" mode, which runs the "kernel" mode and the "initrd" mode for you. Note that the "kernel" and "initrd" modes are currently just aliases for the "all" mode, so they will currently give you no special effect.

Although genkernel is mainly a command to make your life easier when you need to compile a kernel, genkernel is also packed full of different flags which allow you to customize how your kernel is compiled or configured.

Genkernel compiler flags 

Genkernel supports the following flags which are passed to the relevant applications when your kernel is assembled:

• --kernel-as=someAssembler: This specifies an assembler which would be used for compiling your kernel.
• --kernel-cc=someCompiler: This specifies a compiler which would be used for compiling your kernel.
• --kernel-ld=someLinker: This specifies a linker which would be used for compiling your kernel.
• --kernel-make=someMake: This specifies an alternate GNU Make which would be used for compiling your kernel.

• --utils-as=someAssembler: This specifies an assembler which would be used for compiling the support utilities.
• --utils-cc=someCompiler: This specifies a compiler which would be used for compiling the support utilities.
• --utils-ld=someLinker: This specifies a linker which would be used for compiling the support utilities.
• --utils-make=someMake: This specifies an alternate GNU Make which would be used for compiling the support utilities.

• --makeopts=-jJobs: This specifies the flags which would be passed to GNU Make when the kernel and utilities are being compiled.

Genkernel kernel flags 

Genkernel supports the following flags, some of which have --no-option equivalents that influence kernel compilation:

• --callback="echo Hello": This routine calls the specified arguments after the kernel and the relevant modules have been built; but before the initrd has been built. This is useful where you might want external modules installed to the initrd by emerging the relevant item using the callback and then redefinining a Genkernel module group.
• --no-clean: This runs or does not run make clean before compiling your kernel. This causes all object files and dependencies to be removed.
• --no-mrproper: This runs or does not run make mrproper before compiling your kernel. This causes all object files, dependencies and your configuration to be removed.

• --kerneldir=/path/to/sources: This specifies an alternative kernel source location, instead of the default location of /usr/src/linux.
• --kernel-config=/path/to/config-file: This specifies an alternative kernel configuration which would be used; rather than the inpersistant /path/to/sources/.config which is used by default.

• --no-bootsplash: This adds or does not add bootsplash support in the initrd which genkernel builds. Not all architectures currently support bootsplash, and a kernel that supports bootsplash is also required.
• --no-menuconfig: This runs or does not run the kernel menu-based configurator before building your kernel, after make oldconfig has ran.

• --no-initrdmodules: This doesn't copy any modules to the initrd which genkernel creates.
• --no-install: This installs or does not install your kernel, modules, and initrd once the compilation has finished.

Genkernel miscellaneous flags 

Genkernel also supports some miscellaneous flags which do not fit into the other two categories:

• --arch-override=someArch: This flag can be used to override what architecture genkernel thinks you're on, if the auto-detection mechanism fails (please file a bug if it does!) or if you wish to cross-compile a kernel.

• --busybox-config=/path/to/busybox-config: This overrides the default busybox configuration with the specifid file
• --busybox-bin=/path/to/busybox-binary.tar.bz2: Using this option means that a busybox binary would not be compiled, and the specified tarball would be used. Note that busybox must be compiled statically!

• --minkernpackage=/output/to/yourkernel.tar.bz2: This flag outputs a tarball of the kernel, named as kernel and the initrd named as initrd to the specified file. No path information or modules will be includes in the tarball.

Running genkernel 

All that is needed to run genkernel is just genkernel with the necessary flags as root. For example:

# genkernel --menuconfig --no-clean --no-install --bootsplash all
(Would produce a kernel, asking you what how to configure it
to your desire, leaving alone any compiled object files, enabling
bootsplash support but not installing anything.)

If you want genkernel to install your kernel as well, you must ensure that your /boot partition is mounted - recent Genkernels would automatically attempt to do this for you if MOUNTBOOT is set to "yes" in /etc/genkernel.conf.

(If /boot is a valid entry in /etc/fstab:)
# mount /boot
(... otherwise for IDE disks:)
# mount /dev/hda1 /boot
(... and for SCSI disks:)
# mount /dev/sda1 /boot

Setting up genkernel to work with your bootloader 

To set up genkernel to work with your bootloader, three or four changes are required to your bootloader configuration.

1. Add root=/dev/ram0 and init=/linuxrc to the kernel parameters passed to the kernel image.
2. Add real_root=/dev/hda3, for example, to the kernel parameters passed to the kernel image if /dev/hda3 contains your root partition.
3. If you are using bootsplash, add a suitable modeline such as vga=0x317 to the parameters passed to the kernel and also add splash=verbose or splash=silent depending on the verboseness you require from your bootsplash.
4. Add the initrd according to how your bootloader requires it: see the Gentoo Handbook for details on how you would do it for your bootloader.

Kernel Configuration Files 

genkernel will save your kernel config in /etc/kernels and use that config whenever you issue genkernel again. If you want to start off again with the defaults, rename the file in /etc/kernels. genkernel will then use the kernel config located in /usr/share/genkernel/<arch> instead.

3. Porting genkernel

Introduction 

Provided your architecture has all the required libraries and utilties which genkernel requires, which includes but it not limited to a working kernel for your architecture, working compiler suite, GNU Make, and a working busybox distribution, you're all set to go!

For each architecture, genkernel uses /usr/share/genkernel/archName for configuration files for that architecture.

How the system bootstrapping works 

1. The bootloader loads the genkernel image, built to the specification of the configuration files in the genkernel directories as well as the initrd which is prepared by genkernel.
2. The kernel boots up, allocates a small amount of RAM in which busybox is initialized, which probes the system with the modules in the modules_load list for the architecture.
3. Once done, and providing that the real_root parameter which is the root boot device as busybox sees things is found, the system is booted from the device.

The configuration files 

• busy-config: This is the configuration which is used to build busybox for your architecture.
• config.sh: This is a shell script which sets various internal genkernel variables. See one of the config.sh files for an example.
• modules_load: This is a file containing a space-delimited list of modules which are loaded for SCSI, FireWire, ATARAID and PCMCIA support. If none are available for your platform, leave the fields blank. See one of the modules_load files for an example.

• kernel-config: A default kernel configuration used for any kernel version.
• kernel-config-2.4: A default kernel configuration used for 2.4 series kernels.
• kernel-config-2.6: A default kernel configuration used for 2.6 series kernels.