Working with LITMUSRT generally requires compiling the entire LITMUSRT kernel from source, and then installing liblitmus and Feather-Trace. The following instructions include all of the necessary compilation and installation steps.
These instructions were tested on 32- and 64-bit versions of Ubuntu 14.04 and 16.04 (running in VirtualBox VMs), but should be largely identical for other platforms. When in doubt, contact the LITMUSRT mailing list.
Some Linux systems, including Ubuntu 14.04, do not have
git or the
openssl libraries installed by default. These are needed for compiling LITMUSRT, and can be installed on Debian-based systems (including Ubuntu) using this command:
sudo apt install libncurses-dev git libssl-dev
Create a directory to contain all of the litmus-related code. This directory is identified using the
$DIR environment variable for the remainder of this tutorial:
mkdir litmus cd litmus export DIR=`pwd`
First, obtain a copy of the LITMUSRT kernel code:
cd $DIR git clone https://github.com/LITMUS-RT/litmus-rt.git cd litmus-rt
Next, we need to configure the compile-time kernel options.
If it’s available, the kernel configuration used by the currently running kernel is usually a good starting point when configuring a new kernel. On Ubuntu systems, the kernel configuration files for the pre-installed kernels are located in the
/boot directory, and can be copied by running the following command (in the
cp /boot/config-`uname -r` .config
Alternatively, on other systems, the existing kernel configuration options may be contained in
zcat /proc/config.gz > .config
Finally, if neither of the two options worked and you can’t locate an existing configuration file for your system, you can run the following command to generate a default configuration:
After a suitable initial configuration has been obtained with one of the above steps (or after simply creating a new configuration from scratch), some further adjustments are needed for LITMUSRT to work correctly.
These instructions use the menu configuration tool to locate and adjust the options needed for LITMUSRT. Access this tool by running the following command:
cd $DIR/litmus-rt make menuconfig
You’ll need to find and adjust several configuration options. I’ll include the locations of the settings in the menu-based configuration for my Ubuntu systems, but these locations may change depending on which base version of the Linux kernel you’re using:
Add a recognizable local version, such as
Local version - append to kernel release.
Enable in-kernel preemptions.
Processor type and features->
Preemption model. Choose
Preemptible Kernel (Low-Latency Desktop).
Disable group scheduling.
Automatic process group schedulingoption under
Control group support->
CPU controller, disable
Group scheduling for SCHED_OTHER
Disable frequency scaling and power management options that affect timer frequency.
Timer tick handling, set the option to
constant rate, no dynticks.
Power management and ACPI options, make sure that
Suspend to RAM and standby,
Opportunistic sleepare disabled.
Power management and ACPI options->
CPU Frequency scaling, disable
CPU Frequency scaling.
When planning to do development, enable tracing in LITMUSRT.
After finishing making configuration changes, save the updated configuration (keep the
.config name). Afterwards, run the following commands to build the LITMUSRT kernel:
make bzImage make modules
This will take some time. To speed things up a little, you may want to enable a parallel build by giving the
-j option to
make (with a limit of twice the number of cores or so).
After compiling the LITMUSRT kernel, install it using the following commands:
cd $DIR/litmus-rt sudo make modules_install sudo make install
(These instructions will usually differ somewhat on non-x86 platforms and when cross-compiling.)
Finally, configure the boot loader (e.g., grub in Ubuntu and most modern distros on x86) to show the boot menu, to allow the LITMUSRT kernel to be selected during boot rather than the default Linux kernel.
# Comment out the line containing GRUB_HIDDEN_TIMEOUT, then save the changes. sudo nano /etc/default/grub # Re-generate grub's internal configuration settings. sudo update-grub
You should now be able to reboot your system and select the Litmus kernel from the boot menu.
After the kernel has been built, proceed next to building liblitmus, which is the userspace portion of LITMUSRT. This includes both libraries for writing real-time tasks and utilities such as
setsched for managing the system’s schedulers.
To download and build liblitmus:
# You can place liblitmus elsewhere, but it's more convenient to put it # somewhere relative to the LITMUS^RT kernel source code, which is required when # compiling liblitmus. cd $DIR # Obtain a copy of the liblitmus source code git clone https://github.com/LITMUS-RT/liblitmus.git cd liblitmus # Usually, no configuration file is needed for liblitmus. However, if you didn't # place liblitmus in the same location as the LITMUS^RT kernel source code's # directory, then you'll need to provide a .config file to refer to the correct # location of the LITMUS^RT kernel source code. Download the following template to # get started. wget -O .config http://www.litmus-rt.org/releases/2016.1/liblitmus-config # Finally, compile liblitmus make
The Feather-Trace tools are needed to trace and visualize scheduling events, and to measure overheads when using LITMUSRT. Feather-Trace tools are built in a manner identical to liblitmus, with the sole difference that the (in the common case purely optional)
.config file refers to the location of liblitmus rather than the LITMUSRT kernel source.
To download and build Feather-Trace:
cd $DIR git clone https://github.com/LITMUS-RT/feather-trace-tools.git cd feather-trace-tools wget -O .config http://www.litmus-rt.org/releases/2016.1/ft_tools-config make
At this point, reboot the system into LITMUSRT and try running a few examples. Check out the tutorial for some initial steps, or the plugin creation tutorial to start writing a LITMUSRT scheduler plugin.