Linux U-Boot and Kernel Users Guide

Linux U-Boot and Kernel Users Guide 1

Table of Contents Overview... 4 General Information... 4 Getting the U-Boot and Kernel Source Code (SDK)... 4 Preparing to Build... 4 Compiler... 5 Device Trees... 5 U-Boot... 5 Building MLO and u-boot... 5 Cleaning the Sources... 6 Compiling MLO and u-boot... 6 Kernel... 7 Cleaning the Kernel Sources... 7 Configuring the Kernel... 7 Using SDK Kernel Configuration... 7 Customizing the Configuration... 8 Compiling the Sources... 8 Compiling the Kernel... 8 Compiling the Device Tree Binaries... 9 Compiling the Kernel Modules... 9 Installing the Kernel... 10 Installing the Kernel Image and Device Tree Binaries... 10 Installing the Kernel Modules... 11 SDK Linux create SD card script... 11 Common Steps... 11 Invoking the Script... 11 Select the SD Card Device... 12 Re-Partitioning the SD Card... 12 Select Number of Partitions... 13 Installing SD Card Content... 13 SD Card Using Default Images... 14 Prerequisites... 14 2

Choose Install Pre-built Images... 14 Updating an SD card from a host PC... 15 3

Overview Comertech s Linux release is based on the official Linux SDK from Texas Instruments. This document will cover the basic steps for building the Linux U-Boot and kernel. General Information Getting the U-Boot and Kernel Source Code (SDK) The easiest way to get access to the kernel source code is by downloading and installing the Linux SDK from Texas Instruments. Linux SDK 07.00.00.00 can be found in the download link below: http://software-dl.ti.com/sitara_linux/esd/am335xsdk/07_00_00_00/index_fds.html Once downloaded the kernel source code is included in the sdk's board-support directory. The detailed procedure on how to run the SDK Installer can be found on in the link below: http://downloads.ti.com/sitara_linux/esd/am335xsdk/07_00_00_00/exports/sitaralinuxsdk-gsg-07.00.00.00.pdf Comertech s EVM changes are fully integrated into SDK 07.00.00.00. Comertech will provide the link to the modified Kernel and U-Boot by customer request. Once downloaded the modified the kernel and u-boot package. Simply extract the package and replace the existing kernel and u-boot from Texas Instruments. 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. 4

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 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/i686-aragolinux/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. Device Trees A note about device trees. With this LCPD release all boards are required to use a device tree to boot. To facilitate this, within U-Boot we have a command in the environment named findfdt that will set the fdtfile variable to the name of the device tree to use, as found with the kernel sources. The device tree is expected to be loaded from the same media as the kernel, and from the same relative path. U-Boot Building MLO and u-boot We strongly recommend the use of separate object directories when building. This is done with O= parameter to make. We also recommend that you use an output directory name that is identical to the configuration target name. That way if you are working with multiple configuration targets it is very easy to know which folder contains the u-boot binaries that you are interested in. We also strongly recommend using the toolchain that came with the Linux Core release that corresponds to this U-Boot release. 5

Cleaning the Sources If you did not use a separate object directory: $ make CROSS_COMPILE=arm-linux-gnueabihf- distclean If you used 'O=am335x_evm' as your object directory: $ rm -rf./am335x_evm Compiling MLO and u-boot Building of both u-boot and SPL is done at the same time. You must however first configure the build for the board you are working with. Use the following table to determine what to use to configure with: Board Config target config file (under include/configs/) AM335x EVM, AM335x EVM-SK, Beaglebone White/Black am335x_evm_config am335x_evm.h AM43xx epos EVM / GP EVM / EVM- SK am43xx_evm_config am43xx_evm.h am57xx GP EVM am57xx_evm_config am57x_evm.h DRA7xx EVM (J6, J6Eco) dra7xx_evm_config dra7xx_evm.h Then: # Use 'am335x_evm' and 'AM335x GP EVM' in this example $ make CROSS_COMPILE=arm-linux-gnueabihf- O=am335x_evm am335x_evm_config all Note that not all possible build targets for a given platform are listed here as the community has additional build targets that are not supported by TI. To find these read the 'boards.cfg' file and look for the build target listed above. And please note that the main config file will leverage other files under include/configs, as seen by #include statements. 6

Kernel 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 (.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 SDK Kernel Configuration 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> 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- omap2plus_defconfig 7

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. NOTE Previous SDKs recommended users use omap2plus_defconfig as their <defconfig>. For this release singlecore-omap2plus_defconfig should be used instead. Otherwise a user will notice a significant amount of features not working. 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-mtdev 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 8

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 Beaglebone Beaglebone Black Device Tree File am335x-bone.dts am335x-boneblack.dts AM335x General Purpose EVM am335x-evm.dts AM335x Starter Kit am335x-evmsk.dts AM437x General Purpose EVM am437x-gp-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 9

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. NOTE 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 10

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 SDK Linux create SD card script The Linux SDK includes a script in the <SDK INSTALL DIR>/bin directory named create-sdcard.sh. The purpose of this script is to create SD cards with default images. Common Steps Invoking the Script The create-sdcard.sh script can be run from any location but must be run with root permissions. This usually means using the sudo command to start execution of the script. For example: host# sudo <SDK INSTALL DIR>/bin/create-sdcard.sh If you fail to execute the script with root permissions you will receive a message that root permissions are required and the script will exit. 11

Select the SD Card Device The first step of the script will ask you to select the drive representing the SD card that you want to format. In most cases your host root file system drive has been masked off to prevent damage to the host system. When prompted enter the device number corresponding to the SD card. For example if the output looks like: Availible Drives to write images to: # major minor size name 1: 8 16 7761920 sdb Enter Device Number: You would enter 1 to select the sdb device NOTE: For most common installations, this script works fine. However, if you are using more advanced disk slicing and volume management, the presented list of device nodes are off by one; in the best case (picking the last item) it will flag a range error, and in the worst case (anything in the middle) the wrong DASD can be destroyed. The problem originates when it attempts to determine the $ROOTDRIVE to "mask" the volume where "/" is mounted from the selection list using a "grep -v $ROOTDRIVE" For the naive partitioning case, its heuristic is fine, yielding something like "sda" --- but for LVM, it grabs some chunk of the device name, e.g. "mapp" (out of "/dev/mapper/kubuntu--vgroot on / type...") Re-Partitioning the SD Card Any partitions of the device that are already mounted will be un-mounted so that the device is ready for partitioning. If the SD Card already has partition you will see a prompt like the following asking you if you would like to repartition the card. If the card was not already partitioned then this step will be skipped and you can move on to the next step. Would you like to re-partition the drive anyways [y/n] : Options: 12

y - This will allow you to change the partitioning of the SD card. For example if you have a 3 partition card and want to create a 2 partition card to give additional storage space to the root file system you would select y here. NOTE: This operation WILL ERASE the contents of your SD card n - If the SD card already has the desired number of partitions then this will leave the partitioning alone. Select Number of Partitions You should now see a prompt like the following which will ask you how many partitions you want to create for the SD card Number of partitions needed [2/3] : Options: 2 - This is the most common use case and will give the most space to the root file system. 3 - This case should only be used by board manufacturers making SD cards to go in the box with the EVM. This requires access to the partition tarballs used for Out-Of-Box SD cards. It is not covered in this document. After selecting the number of partitions move on to the next section. Installing SD Card Content After the SD card is partitioned you will be prompted whether you want to continue installing the file system or safely exit the script. Options: y - Selecting yes here will begin the process of installing the SD card contents. This operation WILL ERASE any existing data on the SD card. Refer to one of the following sections for additional instructions depending on which use case you are creating an SD card for Create the SD card using default images 13

n - Selecting no here will allow you to have partitioned your card but will leave the partitions empty. SD Card Using Default Images The purpose of this section is to cover how to use the create-sdcard.sh script to populate an SD card that can be used to boot the device using the default images that ship with the Processor SDK for Linux. Prerequisites 1. The Processor SDK for Linux is installed on your host system 2. The SD card you wish to create is inserted into the host system and has a size sufficiently large to hold at least the bootloaders, kernel, and root file system. 3. You have started running the script as detailed in the Common Steps section above. Choose Install Pre-built Images You should now see a prompt like: ###################################################################### ########## Choose file path to install from 1 ) Install pre-built images from SDK 2 ) Enter in custom boot and rootfs file paths ###################################################################### ########## 14

Choose now [1/2] : You should choose option 1 to create an SD card using the pre-built images from the SDK. Updating an SD card from a host PC This section assume that you have created an SD card following the instructions on SDK Linux create SD card script given above or have made a compatible layout by hand. In this case, you will need to copy the MLO and u-boot.img files to the boot partition. At this point, the card is now bootable in the SD card slot. We default to using /boot/zimage on the rootfs partition and the device tree file loaded from /boot with the same name as in the kernel. 15