This tutorial will present how to compile and install a Xenomai-patched Linux kernel. Moreover, we will build Debian packages to ease the installation process.

At the time of writing, the most recent stable version of Xenomai is 3.1 and the latest supported Linux kernel version is 4.19.89. However, these instructions should be valid for past and future versions.

All the instructions have been executed on a machine running Ubuntu 20.04.

Pre-requisites

Install the following required packages:

sudo apt-get update
sudo apt-get install devscripts debhelper dh-kpatches findutils kernel-package libncurses-dev fakeroot zlib1g-dev autotools-dev autoconf automake libtool git libssl-dev libelf-dev libcurses5-dev bison flex

Download required files

From now and for the rest of this guide, the working directory is ~/sources.

Download and extract needed archives:

mkdir -p ~/sources
cd ~/sources

# Download and extract Xenomai
wget https://xenomai.org/downloads/xenomai/stable/xenomai-3.1.tar.bz2
tar -xf xenomai-3.1.tar.bz2

# Download ipipe patch (must match the kernel version)
wget https://xenomai.org/downloads/ipipe/v4.x/x86/ipipe-core-4.19.89-x86-9.patch

# Download the kernel sources
wget https://mirrors.edge.kernel.org/pub/linux/kernel/v4.x/linux-4.19.89.tar.xz
tar -xf linux-4.19.89.tar.xz

Build packages for Xenomai libraries

cd xenomai-3.1

# Create a new Debian changelog entry and build the packages
DEBEMAIL="your@email.com" DEBFULLNAME="Your Name" debchange -v 3.1 Release 3.1
debuild -uc -us

This command built 4 packages in the ~/sources directory. These packages contain, respectively:

  • libxenomai1: Shared libraries
  • libxenomai-dev: Headers and static libraries
  • xenomai-kernel-source: Patches and goodies for building the linux kernel
  • xenomai-runtime: Runtime utilities

Install the packages:

cd ~/sources

# Install packages
sudo dpkg -i libxenomai1_3.1.0_amd64.deb libxenomai-dev_3.1.0_amd64.deb xenomai-kernel-source_3.1.0_all.deb xenomai-runtime_3.1.0_amd64.deb

Prepare the kernel sources

Prepare the kernel sources by applying Xenomai patches using the bundled script:

cd linux-4.19.89

../xenomai-3.1/scripts/prepare-kernel.sh --arch=x86_64 --ipipe=../ipipe-core-4.19.89-x86-9.patch

Configure the kernel

Configure the kernel according to your needs using the make menuconfig command.

Some configuration errors may occur. I personally make sure to apply the following settings:

CONFIG_HYPERVISOR_GUEST=n
CONFIG_X86_UV=n
CONFIG_SYSTEM_TRUSTED_KEYS=""

Compile the kernel

Now that the kernel has been patched and configured, we shall compile it and produce Debian packages out of it:

# Don't use '-j' argument for concurrency
CONCURRENCY_LEVEL=8 CLEAN_SOURCE=no fakeroot make-kpkg --initrd \ --append-to-version -xenomai-3.1 --revision 1.0 kernel_image kernel_headers

This operation might take some time (up to several tens of minutes), so be patient!
In the meantime, don’t hesitate to read the next section so you have everything ready when compilation is done.

Additional configuration

Running a Xenomai kernel requires some additional configuration, like allowing non-root users to have access to real-time commands, or configuring GRUB.

Allow non-root users

sudo addgroup xenomai
sudo addgroup root xenomai
sudo usermod -aG xenomai <username>

If you wish to use a specific GID for the xenomai group, append the --gid <GID> option to the first addgroup command.

Configure GRUB

Edit the GRUB configuration file:

sudo /etc/default/grub

Pass the xenomai GID (here 1234) as a boot parameter so that users in this group can run real-time commands (you can retrieve the GID by executing cat /etc/group | grep xenomai):

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash xenomai.allowed_group=1234"

If you have an Intel HD Graphics integrated GPU (any type):

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash i915.enable_rc6=0 i915.enable_dc=0 noapic xenomai.allow_group=1234"

If you have an Intel Skylake CPU, you need to add the nosmap parameter to fix the latency hang:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash i915.enable_rc6=0 i915.enable_dc=0 noapic nosmap xenomai.allow_group=1234"

Finally, exit editing and update GRUB:

sudo update-grub

Install the Xenomai kernel

cd ~/sources

sudo dpkg -i linux-image-4.19.89-xenomai-3.1_1.0_amd64.deb

You may now reboot your machine and select the Xenomai kernel.

Testing

After booting, make sure you are running the Xenomai kernel:

$ uname -r
4.19.89-xenomai-3.1

Run xeno latency to test the latency and play a bit with the graphics to see how it works. You should see results like:

== Sampling period: 100 us
== Test mode: periodic user-mode task
== All results in microseconds
warming up...
RTT|  00:00:01  (periodic user-mode task, 100 us period, priority 99)
RTH|----lat min|----lat avg|----lat max|-overrun|---msw|---lat best|--lat worst
RTD|      1.992|      2.655|      7.759|       0|     0|      1.992|      7.759
RTD|      2.656|      4.241|     47.226|       0|     0|      1.992|     47.226
RTD|      0.042|      1.526|     41.533|       0|     0|      0.042|     47.226
RTD|      0.885|      1.794|      5.563|       0|     0|      0.042|     47.226
RTD|      1.840|      2.734|     16.330|       0|     0|      0.042|     47.226
RTD|      2.130|      3.688|      6.958|       0|     0|      0.042|     47.226
RTD|      2.239|      4.291|     13.761|       0|     0|      0.042|     47.226
RTD|      3.567|      4.314|     11.943|       0|     0|      0.042|     47.226
---|-----------|-----------|-----------|--------|------|-------------------------
RTS|      0.042|      3.155|     47.226|       0|     0|    00:00:08/00:00:08

Conclusion

You now have a wonderful freshly-compiled Xenomai kernel and can start playing around with real-time functions!

I hope this tutorial was helpful to you and let us know what you think in the comments section!

References

https://gitlab.denx.de/Xenomai/xenomai/-/wikis/Installing_Xenomai_3

https://nrotella.github.io/download/Rotella_XenomaiGuide.pdf