Linux Kernel Users Guide

From Texas Instruments Wiki
Jump to: navigation, search

Ti stk 1c rev rgb png.png


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

Getting the Kernel Source Code

The easiest way to get access to the kernel source code is by downloading and installing the Processor SDK Linux. Once installed, the kernel source code is included in the SDK's board-support directory. For your convenience the sources also includes the kernel's git repository including commit history.
Alternatively, Kernel sources can directly be fetched from GIT. You can find the details about the git repository, branch and commit id in the Processor_SDK_Linux_Kernel_Release_Notes and Processor_SDK_Linux_RT_Kernel_Release_Notes.

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.


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

export PATH=<sdk path>/linux-devkit/sysroots/x86_64-arago-linux/usr/bin:$PATH

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

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.


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 (.config) before proceeding.

The command to clean the kernel is:

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- 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=arm-linux-gnueabihf- <defconfig>

SDK Kernel Configuration

For this sdk the singlecore-omap2plus_defconfig was used and is the one we recommend all users to use or at least use as a starting point. example:

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- tisdk_amNNNx-evm_defconfig

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.


Previous SDKs recommended users use omap2plus_defconfig as their <defconfig>. For this release tisdk_[platformName]-evm_defconfig should be used instead, which has included the platform name (e,g., am335x for AM335x, am437x for AM437x, am57xx for AM57xx, k2hk for K2H/K2K, k2e for K2E, k2l for K2L, and k2g for K2G). If the kernel was downloaded directly from the git repository, the defconfig will need to be built with scripts. Please see ti_config_fragments/README within the kernel sources for more information. Otherwise a user will notice a significant amount of features not working.

Below is the procedure to build the defconfig from the kernel git repository.

$ ti_config_fragments/ -t ti_sdk_[device]_release
$ export ARCH=arm 
$ make ti_sdk_[device]_release_defconfig
$ mv .config arch/arm/configs/tisdk_[platformName]-evm_defconfig

The list of defconfig map file (i.e., ti_sdk_[device]_release used above) supported can be found from ti_config_fragments/defconfig_map.txt file.

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

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=arm-linux-gnueabihf- <config type>

i.e. for menuconfig the command would look like

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- menuconfig

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 Sources

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=arm-linux-gnueabihf- zImage

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

Compiling the Device Tree Binaries

Starting with the 3.8 kernel each TI evm has an unique device tree binary file required by the kernel. Therefore, you will need to build and install the correct dtb for the target device. All device tree files are located at arch/arm/boot/dts/. Below list various TI evms and the matching device tree file.

Device Tree File Name Per Board
Boards Device Tree File
Beaglebone Black am335x-boneblack.dts
AM335x General Purpose EVM am335x-evm.dts
AM335x Starter Kit am335x-evmsk.dts
AM335x Industrial Communications Engine am335x-icev2.dts
AM437x General Purpose EVM am437x-gp-evm.dts,
am437x-gp-evm-hdmi.dts (HDMI)
AM437x Starter Kit am437x-sk-evm.dts
AM437x Industrial Development Kit am437x-idk-evm.dts
AM57xx EVM am57xx-evm.dts,
am57xx-evm-reva3.dts (revA3 EVMs )
AM572x IDK am572x-idk.dts
AM571x IDK am571x-idk.dts
K2H/K2K EVM keystone-k2hk-evm.dts
K2E EVM keystone-k2e-evm.dts
K2L EVM keystone-k2l-evm.dts
K2G EVM keystone-k2g-evm.dts

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=arm-linux-gnueabihf- <dt filename>.dtb

The compiled device tree file with be located in arch/arm/boot/dts.

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=arm-linux-gnueabihf- am335x-boneblack.dtb

Compiling the Kernel Modules

By default the majority of the Linux drivers used in the sdk are not integrated into the kernel image (ex zImage). These drivers are built as dynamic modules. The command to build these modules is:

make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- modules

This will result in .ko (kernel object) files being placed in the kernel tree. These .ko files are the dynamic kernel modules.

When ever you make a change to the kernel its generally recommended that you rebuild your kernel modules and reinstall the kernel modules. Otherwise the kernel modules may not load or run. The next section will cover how to install these modules.


Any time you make a change to the kernel which requires you to recompile it you should also insure that you recompile the kernel modules and reinstall them. Otherwise all your kernel modules may refuse to load which will result in a significant loss of functionality.

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 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

cd <kernel sources dir>
sudo cp arch/arm/boot/zImage <rootfs path>/boot
sudo cp arch/arm/boot/dts/<dt file>.dtb <rootfs path>/boot

For example, if you wanted to copy the kernel image and BeagleBone Black device tree file to the rootfs partition of a SD card you would enter the below commands:
cd <kernel sources dir>
sudo cp arch/arm/boot/zImage arch/arm/boot/dts/am335x-boneblack.dtb /media/rootfs/boot

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/<kernel version> 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:

sudo make ARCH=arm  INSTALL_MOD_PATH=<path to root of file system> modules_install

For example if you are installing the modules on the rootfs partition of the SD card you would do:

sudo make ARCH=arm INSTALL_MOD_PATH=/media/rootfs modules_install

Append INSTALL_MOD_STRIP=1 to the make modules_install command to reduce the size of the resulting installation

Linux Kernel Drivers Guide

Baseport Drivers Guides

Linux Core Crypto User's Guide

Connectivity Drivers Guides

Linux Core I2C User's Guide

Linux Core SPI User's Guide

Linux Core QSPI User's Guide

Linux Core MUSB User's Guide

Linux Core DWC3 User's Guide

Linux Core CPSW User's Guide

Linux Core NetCP User's Guide

Linux Core PCIe Root Complex User's Guide

Linux Core PCIe End Point User's Guide

Linux Core RapidIO User's Guide

Audio & Display Drivers Guides

Linux Core PWM/Backlight User's Guide

Linux Core DSS User's Guide

Linux Core VPE User's Guide

Linux Core Audio User's Guide

Linux Core VPFE User's Guide

Power Management Drivers Guides

Linux Core Power Management User's Guide

Storage Drivers Guides

Linux Core SATA User's Guide

Linux Core NAND User's Guide

Linux Core MMC/SD User's Guide


Processor SDK Linux Kernel User Guide
Processor SDK Linux Kernel User Guide
Processor SDK Linux Kernel User Guide
Processor SDK Linux Kernel User Guide
Processor SDK Linux Kernel User Guide
Processor SDK Linux Kernel User Guide
AMSDK 8.0 Linux Kernel User Guide
AMSDK 7.X Linux Kernel User Guide