Template:Linux Kernel Users Guide

Overview
This wiki will cover the basic steps for building the Linux kernel.

Preparing to Build
It is important that when using the GCC toolchain provided with the SDK or stand alone from TI that you do NOT source the environment-setup file included with the toolchain when building the kernel. Doing so will cause the compilation of host side components within the kernel tree to fail.

The following commands are intended to be run from the root of the kernel tree unless otherwise specified. The root of the kernel tree is the top-level directory and can be identified by looking for the "MAINTAINERS" file.

Compiler
For the purpose of this wiki &lt;compiler&gt; will be used for the path to and compiler used for the compilation.

Before compiling the kernel or kernel modules the SDK's toolchain needs to be added to the PATH environment variable

The current compiler supported for this release along with download location can be found in the release notes for the kernel release.

Getting the Code
The kernel code can be downloaded from a git repo.

In order to download the code the host will need to ensure that git is installed. Git installation wiki can be found here:

processors.wiki.ti.com/index.php/Git

The kernel repo location, branch and tag can be found in the corresponding release notes for the target source.

Cleaning the Kernel Sources
Prior to compiling the Linux kernel it is often a good idea to make sure that the kernel sources are clean and that there are no remnants left over from a previous build.

NOTE: The next step will delete any saved .config file in the kernel tree as well as the generated object files. If you have done a previous configuration and do not wish to lose your configuration file you should save a copy of the configuration file before proceeding.

The command to clean the kernel is:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; distclean

Configuring the Kernel
Before compiling the Linux kernel it needs to be configured to select what components will become part of the kernel image, which components will be build as dynamic modules, and which components will be left out all together. This is done using the Linux kernel configuration system.

Using Default Configurations
It is often easiest to start with a base default configuration and then customize it for you use case if needed. In the Linux kernel a command of the form:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; &lt;defconfig&gt; example: make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf-gcc omap2plus_defconfig

The &lt;defconfig&gt; used for the release can be found in the corresponding release notes.

After the configuration step has run the full configuration file is saved to the root of the kernel tree as .config. Any further configuration changes are based on this file until it is cleanup up by doing a kernel clean as mentioned above.

Customizing the Configuration
When you want to customize the kernel configuration the easiest way is to use the built in kernel configuration systems. Two of the most popular configuration systems are:

menuconfig: an ncurses based configuration utility xconfig: a Qt based graphical configuration utility.

NOTE: on some systems in order to use xconfig you may need to install the libqt3-mt-dev package. For example on Ubuntu 10.04 this can be done using the command sudo apt-get install libqt3-mt-dev

To invoke the kernel configuration you simply use a command like:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; &lt;config type&gt;

i.e. for menuconfig the command would look like

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; menuconfig

whereas for xconfig the command would look like

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; xconfig

Once the configuration window is open you can then select which kernel components should be included in the build. Exiting the configuration will save your selections to a file in the root of the kernel tree called .config.

Compiling the Kernel
Once the kernel has been configured it must be compiled to generate the bootable kernel image as well as any dynamic kernel modules that were selected.

By default U-boot expects zImage to be the type of kernel image used.

To just build the zImage use this command

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; zImage

For u-boot the kernel should be built with a u-boot header that the u-boot program can read. This is easily accomplished by using the uImage build target in the kernel. In order to build the uImage target the command is:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; LOADADDR=0x80008000 uImage

This will result in a kernel image file being created in the arch/arm/boot/ directory called uImage/zImage.

Compiling the Device Tree Binaries
This will result in a kernel image file being created in the arch/arm/boot/dts directory with an extension of dtb. You will need to determine the correct dtb file for the target device.

Building Individual Device Tree Binaries
To build an individual device tree file find the name of the dts file for the board you are using and replace the .dts extension with .dtb. Then run the following command:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; &lt;dt filename&gt;.dtb

For example, the Beaglebone Black device tree file is named am335x-boneblack.dts. To build the device tree binary you would run:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; am335x-boneblack.dtb

Building All Device Tree Binaries
To build all device tree binaries within arch/arm/boot/dts

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; dtbs

Compiling the Kernel Modules
If you selected any components of the kernel to be build as dynamic modules you must issue an additional command to compile those modules. The command is:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; modules

This will result in .ko (kernel object) files being placed in the kernel tree. These .ko files are the dynamic kernel modules. The next section will cover how to install these modules.

Installing the Kernel
Once the Linux kernel, dtb files and modules have been compiled they must be installed. In the case of the kernel image this can be installed by copying the zImage/uImage file to the location where it is going to be read from. The device tree binaries should also be copied to the same directory that the kernel image was copied to.

Installing the Kernel Image and Device Tree Binaries
Starting with U-boot 2013.10, the kernel and device tree binaries by default are no longer being read from the /boot/ partition on the MMC but from the root file system's boot directory when booting from MMC/EMMC. This would mean you would copy the kernel image and device tree binaries to /media/rootfs/boot instead of /media/boot.

Installing the Kernel Modules
To install the kernel modules you use another make command similar to the others, but with an additional parameter which give the base location where the modules should be installed. This command will create a directory tree from that location like lib/modules/&lt;kernel version&gt; which will contain the dynamic modules corresponding to this version of the kernel. The base location should usually be the root of your target file system. The general format of the command is:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; INSTALL_MOD_PATH=&lt;path to root of file system&gt; modules_install

For example if you are installing the modules to an NFS share located at /home/user/targetNFS you would do:

make ARCH=arm CROSS_COMPILE=&lt;compiler&gt; INSTALL_MOD_PATH=/home/user/targetNFS modules_install