3.3.1. Users Guide
3.3.1.1. Overview
This document will cover the basic steps for building the Linux kernel.
3.3.1.2. 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. You can download the latest Processor SDK Linux installer from AM57xx-Linux-SDK-Download-page. 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 Kernel section of the release notes.
3.3.1.3. 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.
Note
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.
3.3.1.3.1. 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/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.
3.3.1.3.2. 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-none-linux-gnueabihf- distclean
3.3.1.4. 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.
It is often easiest to start with a base default configuration and then customize it for your use case if needed. Apply Linux kernel configurations with a command of the form:
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabihf- <defconfig>
3.3.1.4.1. Using Default Configurations
For this sdk, the defconfig found in arch/arm64/configs is used to create the prebuilt files. We recommend users to use this kernel configuration (or at least use it as a starting point).
platformName is am335x-evm for AM335x, am437x-evm for AM437x, am57xx-evm for AM57xx, k2hk-evm for K2H/K2K, k2e-evm for K2E, k2l-evm for K2L, k2g-evm for K2G, and omapl138-lcdk for OMAP-L138.
For example, to apply the default AM335x kernel configuration, use:
For Linux,
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabihf- multi_v7_defconfig ti_multi_v7_prune.config no_smp.config
For RT-Linux,
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabihf- multi_v7_defconfig ti_multi_v7_prune.config no_smp.config ti_rt.config
The config fragments found in <path-to-ti-linux-kernel>/kernel/configs can be used to trim/add features when building a kernel that targets only TI EVMs. Append a config fragment to the end of “make” command like above to add/remove features.
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 cleaned up by doing a kernel clean as mentioned above.
3.3.1.4.2. Customizing the Configuration
When you want to customize the kernel configuration the easiest way is to use the built in kernel configuration systems. One popular configuration system is menuconfig. menuconfig is an ncurses based configuration utility.
To invoke the kernel configuration you simply use a command like:
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabihf- <config type>
i.e. for menuconfig the command would look like
make ARCH=arm CROSS_COMPILE=arm-none-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.
3.3.1.5. Compiling the Sources
3.3.1.5.1. 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-none-linux-gnueabihf- zImage
This will result in a kernel image file being created in the arch/arm/boot/ directory called zImage.
3.3.1.5.2. 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.
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 |
AM574x IDK |
am574x-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 |
K2G ICE EVM |
keystone-k2g-ice.dts |
OMAP-L138 LCDK |
da850-lcdk.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 DTC_FLAGS=-@ ARCH=arm CROSS_COMPILE=arm-none-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 DTC_FLAGS=-@ ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabihf- am335x-boneblack.dtb
Alternatively, you can build every device tree binary with command
make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabihf- dtbs
3.3.1.5.3. Compiling the Kernel Modules
By default the majority of the Linux drivers used in the sdk are not integrated into the kernel image file (zImage). These drivers are built as dynamic modules. The command to build these modules is:
make ARCH=arm CROSS_COMPILE=arm-none-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.
Note
If you make a change to the kernel which requires you to recompile the kernel, then you should also recompile the kernel modules and reinstall the kernel modules. Otherwise your kernel modules may refuse to load, which will result in a loss of functionality.
3.3.1.6. Creating the kernel fitImage for high security device / GP devices
SDKs have pre-built FIT images that contain the default Kernel and DTB files. But developers may want to deploy and test new Kernel and DTB without going through the standard build system. For the specific purpose, board specific fitImage.its will be present in the prebuilt-images directory.
Pre-requisites ( Already part of SDK installations ):
Uboot build directory for ARMV8
Linux Image and DTB
Note
GP/HS-FS devices will also enforce authentication if booting fitImage. To disable authentication enforcement, FIT_SIGNATURE_ENFORCE needs to be disabled in defconfig for the specific board during uboot build.
3.3.1.6.1. Describing FIT source
FIT Image is a packed structure containing binary blobs and configurations. The Kernel FIT Image that we have has Kernel Image, DTB and the DTBOs
kernel-1 {
description = "Linux kernel";
data = /incbin/("linux.bin");
type = "kernel";
arch = "arm64";
os = "linux";
compression = "gzip";
load = <0x81000000>;
entry = <0x81000000>;
hash-1 {
algo = "sha512";
};
};
fdt-ti_k3-j721e-common-proc-board.dtb {
description = "Flattened Device Tree blob";
data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-common-proc-board.dtb");
type = "flat_dt";
arch = "arm64";
compression = "none";
load = <0x83000000>;
hash-1 {
algo = "sha512";
};
};
fdt-ti_k3-j721e-evm-virt-mac-client.dtbo {
description = "Flattened Device Tree blob";
data = /incbin/("arch/arm64/boot/dts/ti/k3-j721e-evm-virt-mac-client.dtbo");
type = "flat_dt";
arch = "arm64";
compression = "none";
load = <0x83080000>;
hash-1 {
algo = "sha512";
};
};
Change the path in data variables to point to the respective files in your local machine.
For e.g change “linux.bin” to “<path-to-tisdk>/board-support/prebuilt-images/Image”.
The new addition to the FIT from 8.6 to 9.0 is the FIT Signature.
conf-ti_k3-j721e-common-proc-board.dtb {
description = "Linux kernel, FDT blob";
fdt = "fdt-ti_k3-j721e-common-proc-board.dtb";
kernel = "kernel-1";
signature-1 {
algo = "sha512,rsa4096";
key-name-hint = "custMpk";
sign-images = "kernel", "fdt";
};
};
Specify all images you need the signature to authenticate as a part of sign-images. The key-name-hint needs to be changed if you are using some other key other than the TI dummy key that we are using for this example. It should be the name of the file containing the keys.
Note
Generating new set of keys:
$ mkdir keys
$ openssl genpkey -algorithm RSA -out keys/dev.key \
-pkeyopt rsa_keygen_bits:4096 -pkeyopt rsa_keygen_pubexp:65537
$ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
3.3.1.6.2. Generating the fitImage
Note
For signing a secondary platform like SK boards, you’ll require additional steps
Change the CONFIG_DEFAULT_DEVICE_TREE
For e.g
diff --git a/configs/j721e_evm_a72_defconfig b/configs/j721e_evm_a72_defconfig index a5c1df7e0054..6d0126d955ef 100644 --- a/configs/j721e_evm_a72_defconfig +++ b/configs/j721e_evm_a72_defconfig @@ -13,7 +13,7 @@ CONFIG_CUSTOM_SYS_INIT_SP_ADDR=0x80480000 CONFIG_ENV_SIZE=0x20000 CONFIG_DM_GPIO=y CONFIG_SPL_DM_SPI=y -CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-common-proc-board" +CONFIG_DEFAULT_DEVICE_TREE="k3-j721e-sk" CONFIG_SPL_TEXT_BASE=0x80080000 CONFIG_DM_RESET=y CONFIG_SPL_MMC=y
Change the binman nodes to package u-boot.dtb for the correct set of platform
For e.g
diff --git a/arch/arm/dts/k3-j721e-binman.dtsi b/arch/arm/dts/k3-j721e-binman.dtsi index 673be646b1e3..752fa805fe8d 100644 --- a/arch/arm/dts/k3-j721e-binman.dtsi +++ b/arch/arm/dts/k3-j721e-binman.dtsi @@ -299,8 +299,8 @@ #define SPL_J721E_SK_DTB "spl/dts/k3-j721e-sk.dtb" #define UBOOT_NODTB "u-boot-nodtb.bin" -#define J721E_EVM_DTB "u-boot.dtb" -#define J721E_SK_DTB "arch/arm/dts/k3-j721e-sk.dtb" +#define J721E_EVM_DTB "arch/arm/dts/k3-j721e-common-proc-board.dtb" +#define J721E_SK_DTB "u-boot.dtb"
This step will embed the public key in the u-boot.dtb file that was already built during the initial u-boot build.
mkimage -r -f fitImage.its -k $UBOOT_PATH/arch/arm/mach-k3/keys -K $UBOOT_PATH/build/$ARMV8/dts/dt.dtb fitImage
Note
If you have another set of keys then change the -k argument to point to the folder where your keys are present, the build requires the presence of both .key and .crt file.
3.3.1.6.3. Build uboot again
The updated u-boot.dtb needs to be packed in u-boot.img for authentication so rebuild uboot ARMV8 without changing any parameters.
Refer to SDK Build using Makefile
3.3.1.7. 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 kernel image 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.
3.3.1.7.1. 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 /media/rootfs/boot
arch/arm/boot/dts/am335x-boneblack.dtb /media/rootfs/boot
Starting with U-boot 2013.10, the kernel and device tree binaries are read from the root file system’s boot directory when booting from MMC/EMMC. (NOT from the /boot/ partition on the MMC). This would mean you copy the kernel image and device tree binaries to /media/rootfs/boot instead of /media/boot.
3.3.1.7.2. 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
Note
Append INSTALL_MOD_STRIP=1 to the make modules_install command to reduce the size of the resulting installation