====== HOWTO setup Linux with PREEMPT_RT properly ======

Linux in itself is not real time capable.  With the additional
PREEMPT_RT patch it gains real-time capabilities.  The sources have to
be downloaded first.  After unpacking and patching, the kernel
configuration has to be adapted.  Then, the kernel can be built and
started.

===== Getting the sources =====

First, the kernel version should be chosen.  After this, take a look
if the PREEMPT_RT patch is [[https://www.kernel.org/pub/linux/kernel/projects/rt|available]]
for this particular version.

The source of the desired version has to be downloaded (for the Linux
kernel as well as for the PREEMPT_RT patch).  This example is based on
the Linux kernel version 4.4.12.

  $ wget https://www.kernel.org/pub/linux/kernel/v4.x/linux-4.4.12.tar.xz
  $ wget https://www.kernel.org/pub/linux/kernel/projects/rt/4.4/patch-4.4.12-rt19.patch.xz

After downloading, unpack the archives and patch the Linux kernel:

  $ xz -cd linux-4.4.12.tar.xz | tar xvf -
  $ cd linux-4.4.12
  $ xzcat ../patch-4.4.12-rt19.patch.xz | patch -p1

===== Configuring the kernel =====

The only necessary configuration for real-time Linux kernel is the
choice of the "Fully Preemptible Kernel" preemption model
(CONFIG_PREEMPT_RT_FULL).  All other kernel configuration parameters
depend on system requirements.  For detailed information about how to
configure a kernel have a look at [[https://www.kernel.org/doc/Documentation/kbuild/kconfig.txt|Linux kernel documentation]].

When measuring system latency all kernel debug options should be
turned off.  They require much overhead and distort the measurement
result.  Examples for those debug mechanism are:

  * DEBUG_PREEMPT
  * Lock Debugging (spinlocks, mutexes, etc. . . )
  * DEBUG_OBJECTS
  * ...

Some of those debugging mechanisms (like lock debugging) produce a
randomized overhead in a range of some micro seconds to several
milliseconds depending on the kernel configuration as well as on the
compile options (DEBUG_PREEMPT has a low overhead compared to Lock
Debugging or DEBUG_OBJECTS).

However, in the first run of a real-time capable Linux kernel it might
be advisable to use those debugging mechanisms.  This helps to locate
fundamental problems.

===== Building the kernel =====

Building the kernel and starting the kernel works similarly to a
kernel without PREEMPT_RT patch.