LITMUS^RT User-Space Library: liblitmus

Copyright (c) 2007-2016 The LITMUS^RT Project & Contributors http://www.litmus-rt.org

Released as open source under the terms of the GNU General Public License (GPL2).

Overview

This library and the included tools provide the user-space interface to LITMUS^RT. Real-time tasks should link against this library. The header file litmus.h contains all necessary system calls and definitions to interact with the kernel services provided for real-time tasks.

Documentation

For a gentle introduction to LITMUS^RT and its userspace tools, we recommend to check out the materials that were prepared for the LITMUS^RT tutorial presented at TuToR'16 @ CPSWeek'16.

• LITMUS^RT tutorial at TuToR'16 @ CPSWeek'16

In particular, check out the online manual prepared for TuToR'16:

• A Tour of LITMUS^RT

Some additional information is available on the LITMUS^RT wiki at:

• Some notes on the user-space interface.

• General installation instructions.

When writing real-time applications that need to make use of LITMUS^RT-specific interfaces and facilities, the application binary needs to be linked against liblitmus (this library). Instructions for how to do so are provided on the LITMUS^RT wiki.

• HOWTO: linking against liblitmus.

As of version 2016.1, LITMUS^RT supports reservation-based scheduling. How to set up and use reservations is described in a separate document.

• HOWTO: working with reservations

As part of the reservation framework, LITMUS^RT also supports proper table-driven scheduling (aka time partitioning or time-triggered scheduling). How to set up and use a static scheduling table described in a separate guide.

• HOWTO: table-driven scheduling

Getting Help

For any questions, bug reports, suggestions, etc. pertaining to LITMUS^RT or liblitmus, please contact the LITMUS^RT mailing list.

Tools and Programs in liblitmus

setsched

Run as:

setsched [<PLUGIN>]

Selects the active scheduler. Must be run as root. Run without argument to be presented with a list of available plugins (requires 'dialog' to be installed).

showsched

Run as:

showsched

Print the name of the currently active scheduler.

rt_launch

Run as:

rt_launch  [-w] [-p <PARTITION>] <WCET> <PERIOD> <PROGRAM> <ARGS>...

Launch the program <PROGRAM> as a real-time task provisioned with the given worst-case execution time and priod. Any additional parameters are passed on to the real-time task. The -w option makes the task wait for a sytem release. Run rt_launch -h for further options.

Tip: for debugging purposes, a couple of

rt_launch $EXEC_TIME $PERIOD find /

real-time processes, for reasonable values of $EXEC_TIME and $PERIOD, generates a workload that stresses the wakeup/suspend path of the scheduler pretty well. Similarly, running

rt_launch $EXEC_TIME $PERIOD sha256sum `find /home | sort -R

produces a CPU-intensive workload that also includes significant IO.

rt_spin

Run as:

rtspin [-w] [-p <PARTITION>] WCET PERIOD DURATION

A simple spin loop for emulating purely CPU-bound workloads. Not very realistic, but a good tool for debugging. The -w option makes the task wait for a sytem release. Run rtspin -h for further options.

The parameters WCET and PERIOD must be given in milliseconds, the paramter DURATION must be given in seconds.

release_ts

Run as:

release_ts [-f <NUM_TASKS>]

Release the task system. This allows for synchronous task system releases (i.e., ensure that all tasks share a common "time zero"). The -f option makes release_ts wait until the number of tasks waiting for the task system release equals <NUM_TASKS>.

See release_ts -h for further options.

Other tools

• measure_syscall: A simple tool that measures the cost of invoking a LITMUS^RT system call.

• cycles: Display measured cycles per time interval, as determined by the cycle counter. Useful for converting benchmarking results.

• base_task: Example real-time task. To be used as a template for the development of single-threaded real-time tasks.

• base_mt_task: Example multi-threaded real-time task. To be used as a template for the development of multithreaded real-time tasks.

• uncache: Demo application showing how to allocate and use uncached pages (i.e., pages that bypass the cache).

• runtests: The LITMUS^RT test suite. By default, it runs the tests for the currently active plugin. Use this frequently when hacking on the core plugins. Add support for new plugins as needed. The tests can be found in tests/ directory.