Compiling a Realtime Linux kernel with the preemp-rt kernel patch

LinuxCNC requires a realtime kernel in which to run. Most Linux distributions do not have the option to install a prebuilt realtime kernel. As a result, if you want something other than the default LinuxCNC distribution you will have to take matters into your own hands. This document will show you how to compile and install a new kernel that has been patched with the realtime preempt-rt patch.

This tutorial is based on Lubuntu 18.04 32-bit version. This distribution was selected do to its lightweight desktop. While this is not the newest release of Lubuntu, it is the newest available LTS (Long Term Support) available at the time of this writing.

Prior to following this tutorial I have installed Lubuntu 18.04 32-bit using the normal installation option and also checked the download updates while installing. After installation all updates were completed and the system rebooted.

Installing the required software for compiling a kernel

Before you can compile a kernel, you will need to install some additional software. This will include the following packages: build-essential, curses, bison, flex and the ssl libraries. These software packages include the compiler, libraries and additional tools that the system will need to complete the compilation of the kernel. To install them on your system open a terminal and type in the following command, or copy and paste into your terminal.

sudo apt install build-essential libncurses-dev bison flex libssl-dev

Now that the computer has the required software installed to compile the kernel, the next step is to create a place to do the work. For our purposes we will create a folder on the hard disk and do all the work required from this folder. If you still have your terminal open, and if not you will need to open it. (Note: all the work we will be doing will be from the terminal.) and issue the following commands:

mkdir rtkernel

The above command will create a directory named rtkernel. This directory or folder is where we will be working from to keep the system tidy.

cd rtkernel

The above command will change you into the rtkernel directory

Downloading the Kernel source and the preempt-rt patch

Now that we have created a place to work from it is time to download the Kernel source code and the preempt-rt kernel patch. One thing to keep in mind is that there kernel version that we wish to compile and the patch version have to match, viz. Be the same version number. I would also recommend compiling a kernel with the same major version number as the kernel that is currently running on your system. To find the version number of the kernel currently running on your system, type the following command in your terminal.

uname -r

The above command will spit out some numbers and perhaps some text. For example, on my machine I get the following output.

4.18.0-18-generic

This indicates that I am running kernel version 4.18.0. What I want to take note of here is the first number. The number 4 tells me that this is version 4 of the kernel and we will use that version in our tutorial.

Before we actually download the kernel and patch, keep in mind that the current kernel source code may be at a slightly higher version than the newest release of the preempt-rt patch. Because of this, we will get the patch first and then get the corresponding kernel source code.

Open your browser and navigate to https://wiki.linuxfoundation.org/realtime/start. At the time of this writing, you can get to the two latest realtime patches from the main page of the site, but in the event that the page changes or you need an older version of the patch we will navigate to where we can find links to the patches. On the main page under the heading Versions of PREEMPT-RT patches you will see the two newest versions of the patch available. Under these is a link titled Read more about PREEMPT_RT versions. Clicking this link will open another page. On the right hand side you will see a list of actively maintained preempt_rt versions. At the time of this writing there are four separate versions of the kernel version 4 of the patch. The newest is 4.19. That is the one in which I will use. Clicking on these links will open a page that will allow you to download the code. Here you will see several files. There are basically two types of files here. The compressed patch and a signature for each compressed file. You have the option of selecting you favorite compressed format. But rather than clicking the file and downloading it somewhere then having to move it, we will do this a little different. Find the patch that ends with the .gz extension, right click and select copy link location. This will copy the url to the file to your computers clip board. Now go back to the teminal window and type wget and then a space and right click your mouse and select paste, or alternatively, press the [CTRL][ALT][V] keys to paste into the terminal. You should get something that looks like the following:

wget http://cdn.kernel.org/pub/linux/kernel/projects/rt/4.19/patch-4.19.37-rt19.patch.gz

Now press the enter key and the computer will download the patch to our current directory, rtkernel. It will only take a couple of seconds or so to download. While you are at it, note the version number of the patch you downloaded. In the above example, the version is 4.19.37. This will be the version of the kernel we will want to download as well.

With the patch downloaded it is time to get the kernel source code. Go back to your browser and navigate to https://www.kernel.org. When the page opens you will see several kernel versions available that you could download. These are the current list of the newest kernel releases for different kernel versions. If one of them is the same version as the patch you downloaded, then simply right click the “tarball” link next to it and select copy link location like we did above. But more than likely, the version that is available on the main page will be just slightly newer than the version of the patch you were able to download. If you fall into that category then don’t despair, we just have to make a few click to get the kernel we want. At the top of the page you will see a protocol and location list. Click on the link next to https and it will open page with a list of directories. Click the linux link on this page and another will open with yet another list of directories. On this page click the kernel link. Finally on the page that opens click the v4.x link for a list of all the version 4 kernel source code archives. Now this page is quite long. Scroll down the page until you find the files that start with linux. These are the kernel source code files. Look for the file that says kernel-.tar.gz. So in our case we are looking for linux-4.19.37.tar.gz. When you find it, right click the file with your mouse and select copy link location like we done for the patch. Now in your terminal, type wget and a space, then either right click your mouse and select paste or press [CTRL][ALT][V] on your keyboard to paste in the terminal. This will give you a command that looks something like the following.

wget https://mirrors.edge.kernel.org/pub/linux/kernel/v4.x/linux-4.19.37.tar.gz

When you press enter, the wget program will go and retrieve the file for you.

Extracting and patching the kernel source code

Now that the source code for the kernel and the patch have been downloaded, we can extract and apply the patch. Doing an ls command in the terminal should like the files we have downloaded. In the terminal type:

ls

This should give you a result that looks something like:
linux-4.19.37.tar.gz
patch-4.19.37-rt19.patch.gz

These are the two files that we downloaded. First we will extract the kernel source code with the following command:

tar xvf linux-4.19.37.tar.gz

This will take a moment or two depending on how fast your system is. When it is compete, if you do a ls command now, you will see that a directory called linux-4.19.37 was created. Next we want to unzip the patch file we downloaded. We will do this with the gunzip program. Type the following in the terminal:

gunzip patch-4.19.37-rt19.patch.gz

Now if you ls the directory you see patch is there but the .gz is gone from the end, indicating that it is now unzipped.

From here on out we will be working from within the linux kernel source code directory. Change to this directory by issuing the following command in the terminal

cd linux-4.19.37

Now that we are in the kernel source tree we need to patch the kernel source with the preempt-rt patch. In the terminal type the following command.

patch -p1 < ../patch-4.19.37-rt19.patch

You will see some stuff fly up the screen indicating the files that are being patched. When it is complete we can proceed.

Now that the kernel is patched we only need to make sure the source tree is free from any remnants of any build that may be left there for some reason. To do this we will issue the following command in the terminal.

make mrproper

Make is a command that can take different directives depending on what is in the makefile. The mrproper directive in the kernels makefile will clean anything from the source tree that would adversely affect compilation of the kernel. You should always run this command before starting any work on the kernel for the first time. If you are interested in what command are available for making the Linux Kernel type make help in the terminal. You will be given a list of options that are available.

Copying a starting configuration to use with the kernel

If we were to compile the kernel now, there is no telling what would be included in the new kernel. We have to provide it some configuration. Fortunately we have a working kernel now so we can use its configuration as a basis. If we run the following command:

ls /boot

The result is a list of files in the /boot directory. These are the files that grub loads when the computer starts up. They consist of kernels and init ram disks. Notice in the listing we also see files that start with the text config-. These are the configuration files used to create that specific kernel. Recall we ran the command uname -r to get the current running kernel version, run that command again

uname -r

Notice there is a config- file with the same information appended to the end of it. We will copy this config file to the kernel source tree and call it .config. We will do this with the following command.

cp /boot/config-"$(uname -r)" ./.config

To recap, the cp command means to copy, some source file to a destination. The next part says in the boot directory the file config-(plus what our uname command prints out) will be copied to ./.config. The first ./ means the current directory and the file we are coping to will be named .config.

Configure the Kernel

Now that we have a basic kernel configuration copied over we can start in earnest. But first we need to set a couple of options in the kernel configuration ourselves. To do this we need to run the kernel’s menuconfig program. To do this we will run the following command.

make menuconfig

You can think of the kernel as the operating system for most intents and purposes. The kernel handles all of the interaction between you the user and the computers hardware. Todays kernels can handle a huge variety of hardware and file systems and much more. The menuconfig program allows you to select what the kernel will have built in, excluded or what you might want to use loadable modules for. In our case, we want to tell the config program that we want to build a fully preemptible kernel.

When the menuconfig has been created the first thing we want to do is to load the configuration that we copied over. To do this we will use the right arrow key and arrow to the load menu entry and press the enter key. It asks for the name of the configuration file we want to load. Recall we copied the file over and named it .config. This is what is populated in the dialog by default, so we can just press the enter key to load it.

First, we will make sure that the kernel is set up to be a fully preemptible kernel. To to this, we will arrow down to General setup ---> in the main menu and press the enter key. Now that we are in the General Setup menu, arrow down until Preemption model is highlighted and press the enter key. Here we will be given a dialog with the list of different preemption models. Arrow to highlight the selection that reads Fully Preemptible Kernel (RT) and press the enter key to select it. You will be placed back in the General Setup menu and will notice that our selection is printed on the same line as the Preemption model menu line. With that completed, arrow right to exit and press enter to leave the General Setup menu.

Next in the list of main menu items is the 64-bit kernel option. This depends on you and the system you are running. But in my experience, unless the system has more the 4 gig of ram and or you are working with HUGE data, then I always install the 32-bit distributions of Linux. So in my case I make sure it is turn off by pressing the N key. If the option is turned off and you want to build a 64-bit kernel, then press the Y key to turn the option on. It will be denoted with an asterisk if it is on, and empty brackets if it is off.

Finally, as I understand it ACPI can interfere with realtime systems. You may want to turn this feature off. To do so, arrow down to the Power management and ACPI options and press the enter key to open the sub menu. Next arrow down to the ACPI menu entry. The N key will turn this option off and the Y key will turn it on. Press whichever you want, but I have elected to turn this off. Now, to get back to the main menu arrow right to exit and press enter.

This will be all the changes that I will make in this tutorial for kernel configurations. Feel free to explore the other menu entries and if you are curious of what they do, you can highlight an entry and then right arrow to help to read about what that function does. I strongly encourage you to be careful of what you do with the kernel config. You can make an inoperable kernel and thus a system that will not boot.

Once we are done with the kernel configuration we want to save that config for the compiler to use when we build the kernel. From the main menu, arrow right to save and press enter. A dialog will open and ask you for a name for the config file. By default it will be .config so just press the enter key to save the file. It will then inform you that the config file has been written and you can press the enter key again to exit this dialog.

We are done with the kernel configuration and can leave the configuration tool. To do this, arrow right to exit and press enter.

Compile the Kernel and Modules

Now that the configuration is complete we can compile the kernel and the modules. We do this by issuing the command make or make all. In your terminal window type make and press enter.

make

Now this part will take quite some time. It all really depends on your system. While testing on a virtual machine, my computer too a little over 2 hours to compile the kernel using a single processor. Yours may be faster or slower, depending on your processor and memory. If you have more than a single core processor you can run make with the -j flag and tell it the number of cores to use. If you are unsure how many cores you have, you can issue the following command:

nproc

It will print a number indocating how many processor cores the computer has. In my case the computer has two cpu cores. To compile the kernel using both cores issue the following command:

make -j2

Now, go get some lunch, coffee or something while the compiler does its thing. And come back here when it is done.

Install the modules

Now that the computer has finished compiling the kernel and modules we can install the modules. This needs to be done with elevated permissions because we are copying them to an area that belongs to the system. To install the module, enter the following command:

sudo make modules_install

This will take a few minutes as there are many modules to copy over. When this is complete we can install our newly built kernel.

Installing the kernel

Last thing to do is install the kernel. Again, this requires elevated permission. To do this we issue the following command in the terminal:

sudo make install

This command does quite a bit of work, it copies the config file, system map and kernel to the systems /boot directory. It will create and copy over the initrd file and then finally make a call to grub to install it as a menu entry in the boot loader. It only takes a few minutes to complete.

Booting the new Kernel and verifying that it loaded

Now that we have installed the new Kernel, we need to boot the computer using it. To do this, close all the windows and do a logout / reboot or enter the following command in the terminal:

sudo reboot

When Grub loads up we can select the first entry or just let it run. When the computer finally boots up, open a terminal and type the following commands

uname -r

The text outputted will be the kernel version that is running in memory. In the case of this tutorial it will read

4.19.37-rt19

If you run the command:

uname -a

You should see the words PREEMPT RT somewhere in the listing indicating it is a realtime kernel.

Conclusion

Congratulations!!! Now you have a system that runs a realtime kernel. Now we can compile LinuxCNC to run on it. That is another tutorial though.

End of Tutorial - Last Revision [06 MAY 2019 – 16:07]