Attention

You are viewing an older version of the documentation. The latest version is v3.3.

Configure and Build Linux Kernel¶

This guide presents two methods of configuring and building the Linux kernel. Both methods will produce identical results, but they differ in the build environment used. See the table below for a description of each method.

Section	Description
Configure and Build Linux Kernel from ECI Build Engine	This method will configure and build the Linux kernel using the ECI Build Engine. Choose this method if you would like to build Deb packages which can be installed onto a target system.
Configure and Build Linux Kernel on local filesystem	This section will configure and build the Linux kernel directly from the local filesystem. Choose this method if you would like to develop directly on the target system.

Configure and Build Linux Kernel from ECI Build Engine¶

This section will explain the procedure to configure the Linux kernel and build it using the ECI Build Engine. It is recommended to read ECI Development Practices to gain a better understanding of the basic development principles.

Step 1: Environment Prerequisites
Step 2: Use Linux Menu Tool
Step 3: Build Linux Kernel

Step 1: Environment Prerequisites¶

In this step, you will set up your build environment.

Setup the Build System, if not done already.
Identify the Linux kernel that you want to configure. ECI offers a few options for various distributions. Refer to ECI Linux Intel LTS Kernel for a list of available kernels and their respective distribution. In this section, linux-image-intel-rt for Debian bullseye distribution will be used. If you are using a different kernel, you will need to modify the example commands accordingly.

Locate the pre-built Linux kernel Deb package:

$ find ./targets/packages/ -name linux-image-intel*.deb

The find command should display a list of available Linux kernel Deb packages:

./targets/packages/bullseye/eci-bullseye/pool/main/l/linux-intel-acrn-sos/linux-image-intel-acrn-sos_5.10.115-bullseye-2_amd64.deb
./targets/packages/bullseye/eci-bullseye/pool/main/l/linux-intel-rt/linux-image-intel-rt_5.10.115-rt67-bullseye-2_amd64.deb
./targets/packages/bullseye/eci-bullseye/pool/main/l/linux-intel-xenomai/linux-image-intel-xenomai_5.10.100-bullseye-2_amd64.deb
./targets/packages/jammy/eci-jammy/pool/main/l/linux-intel-acrn-sos/linux-image-intel-acrn-sos_5.15.36-jammy-2_amd64.deb
./targets/packages/jammy/eci-jammy/pool/main/l/linux-intel-rt/linux-image-intel-rt_5.15.36-rt41-jammy-2_amd64.deb

Export the path of the desired Linux kernel Deb package, so that you can reference it in the later commands:

$ export PACKAGE=./targets/packages/bullseye/eci-bullseye/pool/main/l/linux-intel-rt/linux-image-intel-rt_5.10.115-rt67-bullseye-2_amd64.deb

Extract the Linux kernel Deb package to obtain the Linux kernel default configuration:

$ TDIR=$(mktemp -d -p .)
$ ar x ${PACKAGE} --output ${TDIR}
$ tar --directory=${TDIR} -xf ${TDIR}/data.tar*
$ cp ${TDIR}/boot/config-* . && rm -r ${TDIR}

Now, you will find a file named config-* in the directory:

$ ls config-*
config-5.10.115-rt67-intel-ese-standard-lts-rt+

Locate the existing Linux kernel default configuration, backup the existing Linux kernel default configuration, and copy the new one:

$ RDIR=./targets/layers/meta-tgr/meta-eci-isar/recipes-kernel/linux/files
$ DEFAULT=$(find ${RDIR} -name *_intel_defconfig)
$ mv ${DEFAULT} ${RDIR}/$(basename ${DEFAULT})_backup
$ cp config-* ${DEFAULT}

You will find two *intel_defconfig* files in the ${RDIR} directory:

$ ls ${RDIR}/*_intel_defconfig*
./targets/layers/meta-tgr/meta-eci-isar/recipes-kernel/linux/files/amd64_5.10_intel_defconfig
./targets/layers/meta-tgr/meta-eci-isar/recipes-kernel/linux/files/amd64_5.10_intel_defconfig_backup

Start a bitbake Environment.

Note: You do not have to append any meta-layer YAML meta-vendor-application.yml to build the Linux kernel. The example uses bullseye targets, but use bookworm or jammy targets if you are building a Linux kernel for the Debian or Canonical® Ubuntu® distribution respectively.

Step 2: Use Linux Menu Tool¶

In this step, you will use the Linux menuconfig tool to modify the Linux kernel configuration.

Export the Linux kernel image recipe name, so that you can reference it in the later commands:
```
export RECIPE=linux-image-intel-rt
```
Clean the recipe build cache to ensure a known initial state:
```
$ bitbake ${RECIPE} -c cleansstate
```
Instantiate the recipe build environment by using the devshell command:
```
$ bitbake ${RECIPE} -c devshell
```
Xenomai Only If you are working with the Xenomai kernel, it is necessary to first build the kernel to apply the Xenomai patches. If you are not working with the Xenomai kernel, you may skip this step.
```
$ dpkg-buildpackage --sanitize-env -us -uc -b -rfakeroot --source-option=-I
```
Open the Linux kernel menuconfig tool:
```
$ make menuconfig
```
Use the arrow keys to navigate the menu. Select the < Load > menu option.
In the input prompt, enter build-full/.config to load the Linux kernel default configuration:
Modify the configuration as needed. Use the spacebar key to cycle through configuration options.
- [*] kernel configuration will be built-in to the kernel
- [m] kernel configuration will be available as a discrete kernel module
- [ ] kernel configuration will be excluded
You can use the search prompt to locate a particular configuration and learn about its dependencies. Press the / key to open the search prompt. This example searches for the PREEMPT_RT configuration:

The following is the search result:
After modifying, save the configuration. Select the < Save > menu option, then enter build-full/new.config in the input prompt.
Select the < Exit > menu option until you return to the devshell command prompt. Exit the devshell using the exit command:
```
$ exit
```

Replace the Linux kernel default configuration with the new.config file available in the temporary build directory. This method uses bitbake, so you do not need to exit the bitbake environment:

$ cp $(bitbake ${RECIPE} -e | grep '^S=' | cut -d'"' -f2)/build-full/new.config $(ls $(bitbake ${RECIPE} -e | grep '^FILE_DIRNAME=' | cut -d'"' -f2)/files/*_intel_defconfig)

Step 3: Build Linux Kernel¶

In this step, you will build the Linux kernel Deb package.

Build the Linux kernel image. The build duration will vary depending on the system capabilities. Typically, the build will complete in about 20 minutes if the system meets the recommended system requirements.
```
$ bitbake ${RECIPE}
```
After the build completes, exit the bitbake environment using the exit command.
```
$ exit
```
You will find the resulting Linux kernel Deb packages in the target APT repository located at build/eci-packages-<distribution>/tmp/deploy/isar-apt. To find all the Linux kernel Deb packages, run the following command:
```
$ sudo find build/eci-packages-*/tmp/deploy/isar-apt  -name linux-image-*.deb
```
For example, the linux-image-intel-rt Deb package for bullseye:
```
build/eci-packages-bullseye/tmp/deploy/isar-apt/eci-bullseye-amd64/apt/eci-bullseye/pool/main/l/linux-intel-rt/linux-image-intel-rt_5.10.140-rt73-bullseye-4_amd64.deb
```
You could install the Linux kernel Deb package onto the target system using the dpkg -i <package.deb> command or you could privately host the ECI APT repository to install the Linux kernel Deb package using the APT package manager.

Configure and Build Linux Kernel on local filesystem¶

This section will explain the procedure to configure the Linux kernel and build it from a local filesystem using incremental kernel development principles.

Intel® Edge Controls for Industrial adopts the built-in IKPATCHSET_PROC principles designed by OSADL to facilitate easier maintenance and redistribution of Intel® LTS out-of-tree (OOT) Intel® Edge Controls for Industrial kernel patches.

Step 1: Local Environment Prerequisites
Step 2: Download Linux Intel LTS tree
Step 3: Apply patch quilt from IKPATCHSET_PROC
Step 4: Use local Linux Menu Tool
Step 5: Build and install local Linux kernel image

Step 1: Local Environment Prerequisites¶

In this step, you will set up your Linux local build environment.

Install ECI Linux kernel, if not done already.
Identify the Linux kernel that you want to rebuild locally. ECI offers a few options for various distributions. Refer to ECI Linux Intel LTS Kernel for a list of available kernels and their respective distribution.

In this section, linux-image-intel-rt for Debian bullseye distribution will be used as example. If you are using a different kernel, you will need to modify the example commands accordingly.

Locate the Linux kernel images Deb package:

$ apt list | grep linux-image-intel*

The grep command should display a list of available Linux kernel Deb packages:

linux-image-intel-acrn-sos/unknown 5.10.179-bullseye-8 amd64
linux-image-intel-rt/unknown 5.10.179-rt87-bullseye-8 amd64  [installed]
linux-image-intel-xenomai/unknown 5.10.179-bullseye-8 amd64

Install Linux kernel build essential Deb packages:

$ sudo apt install build-essential:amd64 bc kmod cpio libelf-dev libncurses-dev libssl-dev bison flex wget rsync quilt asciidoctor gcc-multilib libaudit-dev libbabeltrace-dev libdw-dev libiberty-dev libnewt-dev libnuma-dev libperl-dev libunwind-dev libopencsd-dev python3-dev python3-docutils zlib1g-dev libbpf-dev libcap-dev clang llvm libfl-dev pahole

Step 2: Download Linux Intel LTS tree¶

In this step, you will set download the Intel® LTS Linux tree at a specific tag.

Find the https://github.com/intel/linux-intel-lts tag of current a local Linux kernel image using /proc
```
$ tar zxf /proc/patchset.tar.gz baseversion && cat baseversion
```
The cat command should display the https://github.com/intel/linux-intel-lts tag Linux kernel Deb packages was built from:
```
lts-v5.10.179-rt87-preempt-rt-230612T183703Z
```

Download Intel® LTS given reference archive and instantiate Linux source tree.

$ tar zxf /proc/patchset.tar.gz baseversion && cat baseversion
$ major="$(cut -d- -f2 baseversion | cut -c2-)"
$ urldir="https://github.com/intel/linux-intel-lts/archive/refs/tags"
$ directory="linux-intel-lts-$(cat baseversion)"
$ archive="$(cat baseversion).tar.gz"
$ wget "${urldir}/${archive}"

Tip

If wget is unable to download the Linux Intel tree archive file, follow these troubleshooting tips:

Make sure that the system has network connectivity.

Make sure that the ports 80 and 8080 are not blocked by a firewall.

Add proxy setting (if network traffic routes through a proxy server) on via command line parameter or into ~/.wgetrc config
$ wget -e use_proxy=yes -e http_proxy=http://<proxyurl>:<port> -e https_proxy=http://<proxyurl>:<port> "${urldir}/${archive}"

Step 3: Apply patch quilt from IKPATCHSET_PROC¶

In this step, you will apply Intel® LTS out-of-tree (OOT) Intel® Edge Controls for Industrial patches.

Find the https://github.com/intel/linux-intel-lts tag of current a local Linux kernel image using /proc:

$ tar zxf "${archive}"
$ cd "${directory}"
$ mkdir -p ./build-full
$ tar zxf /proc/patchset.tar.gz && cat patches/series

The cat command should display the ordered patches which will be applied onto the https://github.com/intel/linux-intel-lts tag baseversion source tree. For example:

tools-perf-version.patch
tools-perf-install.patch
0001-edac-fix-hazardeous-ieh-nmi-registery.patch
0001-keylocker-fix-compile-when-CONFIG_ACPI_SLEEP-disable.patch
0001-GT-Frequency-Lock-Set-idle-Frequency.patch
0001-vfio-pci-Add-support-for-opregion-v2.1.patch
0002-vfio-pci-Add-OpRegion-2.0-Extended-VBT-support.patch
0003-vfio-pci-Add-IGD-stolen-memory-identical-mapping.patch
0001-osadl-Save-the-current-patchset-in-the-kernel.patch
0002-isar-adapt-ikpatchset-to-intel-lts-tag-base.patch
0001-igc-fix-missing-SPD-pins-and-PPS-when-ptm-is-disable.patch
0002-igc-add-CONFIG_IGC_TSN_TRACE-conditional-trace_print.patch
0001-ANDROID-trace-power-add-trace_clock_set_parent.patch
0002-ANDROID-trace-net-use-pK-for-kernel-pointers.patch
0003-ANDROID-trace-add-non-hierarchical-function_graph-op.patch
0004-xdp-Add-trace-events-in-XDP-transmit-path.patch
0005-xdp-extend-XDP_TX-trace-events-format.patch
0001-Changing-the-reference-value-from-100Mhz-to-200Mhz.patch
0001-porting-mcp251xfd-spi-driver-on-x86-platform.patch
0001-disable-loading-pnvm.patch

Apply patch quilt on Intel® LTS referenced Linux source tree:
```
$ quilt push -a
```

Step 4: Use local Linux Menu Tool¶

In this step, you will use the Linux menuconfig tool to modify the Linux kernel configuration.

Extract the .config file to obtain the Linux kernel default configuration:
```
$ zcat /proc/config.gz  > ./build-full/.config
```
Open the Linux kernel menuconfig tool in a console:
```
$ make menuconfig
```
Use the arrow keys to navigate the menu. Select the < Load > menu option.
In the input prompt, enter build-full/.config to load the Linux kernel default configuration:
Modify the configuration as needed. Use the spacebar key to cycle through configuration options.
- [*] kernel configuration will be built-in to the kernel
- [m] kernel configuration will be available as a discrete kernel module
- [ ] kernel configuration will be excluded
You can use the search prompt to locate a particular configuration and learn about its dependencies. Press the / key to open the search prompt. This example searches for the PREEMPT_RT configuration:

The following is the search result:
After modifying, save the configuration. Select the < Save > menu option, then enter build-full/new.config in the input prompt.
Select the < Exit > menu option until you return to the console prompt.

Step 5: Build and install local Linux kernel image¶

In this step, you will use the Linux toolchain to build and install Linux kernel images and modules.

Run a full build of the Linux kernel image and modules:

$ export ARCH=x86
$ export CROSS_COMPILE='x86_64-linux-gnu-'
$ export O=$(pwd)'/build-full'
$ make -j16 O=build-full DISALLOW_TRACE_PRINTK=1

make[1]: Entering directory '/home/eci-user/lts-v5.10.179-rt87-preempt-rt-230612T183703Z/build-full'
SYNC    include/config/auto.conf.cmd
GEN     Makefile
GEN     Makefile
WRAP    arch/x86/include/generated/uapi/asm/bpf_perf_event.h
WRAP    arch/x86/include/generated/uapi/asm/errno.h
WRAP    arch/x86/include/generated/uapi/asm/fcntl.h
WRAP    arch/x86/include/generated/uapi/asm/ioctl.h
WRAP    arch/x86/include/generated/uapi/asm/ioctls.h
WRAP    arch/x86/include/generated/uapi/asm/ipcbuf.h
WRAP    arch/x86/include/generated/uapi/asm/param.h
WRAP    arch/x86/include/generated/uapi/asm/poll.h
WRAP    arch/x86/include/generated/uapi/asm/resource.h
WRAP    arch/x86/include/generated/uapi/asm/socket.h
WRAP    arch/x86/include/generated/uapi/asm/sockios.h
WRAP    arch/x86/include/generated/uapi/asm/termbits.h
WRAP    arch/x86/include/generated/uapi/asm/termios.h
WRAP    arch/x86/include/generated/uapi/asm/types.h
UPD     include/generated/uapi/linux/version.h
UPD     include/config/kernel.release
WRAP    arch/x86/include/generated/asm/early_ioremap.h
WRAP    arch/x86/include/generated/asm/export.h
WRAP    arch/x86/include/generated/asm/mcs_spinlock.h
WRAP    arch/x86/include/generated/asm/irq_regs.h
WRAP    arch/x86/include/generated/asm/kmap_size.h
WRAP    arch/x86/include/generated/asm/local64.h
WRAP    arch/x86/include/generated/asm/mm-arch-hooks.h
WRAP    arch/x86/include/generated/asm/mmiowb.h
WRAP    arch/x86/include/generated/asm/module.lds.h
WRAP    arch/x86/include/generated/asm/rwonce.h
UPD     include/generated/utsrelease.h
DESCEND  objtool
HOSTCC  scripts/extract-cert
HOSTCC   /home/eci-user/linux-intel-rt/build-full/tools/objtool/fixdep.o
HOSTLD   /home/eci-user/linux-intel-rt/build-full/tools/objtool/fixdep-in.o
LINK     /home/eci-user/linux-intel-rt/build-full/tools/objtool/fixdep
CC      scripts/mod/empty.o
HOSTCC  scripts/mod/mk_elfconfig
CC      scripts/mod/devicetable-offsets.s
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/weak.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/check.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/special.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/orc_gen.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/orc_dump.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/builtin-check.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/builtin-orc.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/exec-cmd.o
MKDIR    /home/eci-user/linux-intel-rt/build-full/tools/objtool/arch/x86/
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/elf.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/help.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/objtool.o
MKDIR    /home/eci-user/linux-intel-rt/build-full/tools/objtool/arch/x86/lib/
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/arch/x86/special.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/libstring.o
GEN      /home/eci-user/linux-intel-rt/build-full/tools/objtool/arch/x86/lib/inat-tables.c
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/libctype.o
CC       /home/eci-user/linux-intel-rt/build-full/tools/objtool/str_error_r.o
UPD     scripts/mod/devicetable-offsets.h
MKELF   scripts/mod/elfconfig.h
HOSTCC  scripts/mod/modpost.o
HOSTCC  scripts/mod/file2alias.o
HOSTCC  scripts/mod/sumversion.o
...
LD [M]  sound/soc/codecs/snd-soc-wm8750.ko
LD [M]  sound/soc/codecs/snd-soc-wm8753.ko
LD [M]  sound/soc/codecs/snd-soc-wm8770.ko
LD [M]  sound/soc/codecs/snd-soc-wm8776.ko
LD [M]  sound/soc/codecs/snd-soc-wm8804-i2c.ko
LD [M]  sound/soc/codecs/snd-soc-wm8804-spi.ko
LD [M]  sound/soc/codecs/snd-soc-wm8804.ko
LD [M]  sound/soc/codecs/snd-soc-wm8903.ko
LD [M]  sound/soc/codecs/snd-soc-wm8960.ko
LD [M]  sound/soc/codecs/snd-soc-wm8962.ko
LD [M]  sound/soc/codecs/snd-soc-wm8974.ko
LD [M]  sound/soc/codecs/snd-soc-wm8978.ko
LD [M]  sound/soc/codecs/snd-soc-wm8985.ko
LD [M]  sound/soc/generic/snd-soc-simple-card-utils.ko
LD [M]  sound/soc/generic/snd-soc-simple-card.ko
LD [M]  sound/soc/intel/atom/snd-soc-sst-atom-hifi2-platform.ko
LD [M]  sound/soc/intel/atom/sst/snd-intel-sst-acpi.ko
LD [M]  sound/soc/intel/atom/sst/snd-intel-sst-core.ko
LD [M]  sound/soc/intel/boards/snd-skl_nau88l25_max98357a.ko
LD [M]  sound/soc/intel/boards/snd-soc-intel-hda-dsp-common.ko
LD [M]  sound/soc/intel/boards/snd-soc-skl_nau88l25_ssm4567.ko
LD [M]  sound/soc/intel/boards/snd-soc-skl_rt286.ko
LD [M]  sound/soc/intel/boards/snd-soc-sst-bxt-da7219_max98357a.ko
LD [M]  sound/soc/intel/boards/snd-soc-sst-bxt-rt298.ko
LD [M]  sound/soc/intel/boards/snd-soc-sst-bytcr-rt5640.ko
LD [M]  sound/soc/intel/boards/snd-soc-sst-bytcr-rt5651.ko
LD [M]  sound/soc/intel/boards/snd-soc-sst-cht-bsw-max98090_ti.ko
LD [M]  sound/soc/intel/boards/snd-soc-sst-cht-bsw-rt5645.ko
LD [M]  sound/soc/intel/boards/snd-soc-sst-cht-bsw-rt5672.ko
LD [M]  sound/soc/intel/common/snd-soc-acpi-intel-match.ko
LD [M]  sound/soc/intel/common/snd-soc-sst-dsp.ko
LD [M]  sound/soc/intel/common/snd-soc-sst-ipc.ko
LD [M]  sound/soc/intel/skylake/snd-soc-skl.ko
LD [M]  sound/soc/snd-soc-acpi.ko
LD [M]  sound/soc/snd-soc-core.ko
LD [M]  sound/synth/emux/snd-emux-synth.ko
LD [M]  sound/synth/snd-util-mem.ko
LD [M]  sound/usb/hiface/snd-usb-hiface.ko
LD [M]  sound/usb/snd-usb-audio.ko
LD [M]  sound/usb/usx2y/snd-usb-us122l.ko
LD [M]  sound/usb/snd-usbmidi-lib.ko
LD [M]  sound/usb/usx2y/snd-usb-usx2y.ko
LD [M]  virt/lib/irqbypass.ko
make[1]: Leaving directory '/home/eci-user/lts-v5.10.179-rt87-preempt-rt-230612T183703Z/build-full'

Install Linux bootable kernel image:

$ kimage="./build-full/$(make O=$(pwd)'/build-full' -s --no-print-directory image_name)" && echo $kimage
$ krel="$(make O=$(pwd)'/build-full' -s --no-print-directory kernelrelease)" && echo $krel
$ kimage_path="/boot/vmlinuz-${krel}"

$ sudo install -m 755 -d $(dirname ${kimage_path})
$ sudo install -m 644 ${kimage} ${kimage_path}

Install Linux kernel configuration:

$ sudo install -m 644 $(pwd)/build-full/.config $(dirname ${kimage_path})/config-${krel}
$ sudo install -m 644 $(pwd)/build-full/System.map $(dirname ${kimage_path})/System.map-${krel}

Install Linux kernel image debug symbols. Note: The locations will differ for the various Linux tools e.g. perf, kdump-tools, Systemtap …

$ sudo mkdir -p /usr/lib/debug/lib/modules/${krel}/
$ sudo install -m 644 $(pwd)/build-full/vmlinux /usr/lib/debug/lib/modules/${krel}/
$ sudo mkdir -p /usr/lib/debug/boot/
$ sudo ln -s ../lib/modules/${krel}/vmlinux /usr/lib/debug/boot/vmlinux-${krel}
$ sudo ln -s lib/modules/${krel}/vmlinux /usr/lib/debug/vmlinux-${krel}

Install Linux kernel modules:

$ sudo mkdir -p /usr/lib/modules/${krel}/
$ sudo make O=$(pwd)'/build-full' INSTALL_MOD_PATH='/usr/lib/modules/'${krel} modules_install

Update the GRUB boot configuration:

$ sudo update-grub

Generating grub configuration file ...
Found background image: /usr/share/images/desktop-base/desktop-grub.png
Found linux image: /boot/vmlinuz-5.10.179-rt87-intel-ese-standard-lts-rt+
Found initrd image: /boot/initrd.img-5.10.179-rt87-intel-ese-standard-lts-rt+
Found linux image: /boot/vmlinuz-5.10.179-rt87-intel-ese-standard-lts-rt+
Found initrd image: /boot/initrd.img-5.10.179-rt87-intel-ese-standard-lts-rt+
Adding boot menu entry for UEFI Firmware Settings ...