1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
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](http:/www.litmus-rt.org/tutor16)
In particular, check out the online manual prepared for TuToR'16:
- [A Tour of LITMUS^RT](http://www.litmus-rt.org/tutor16/manual.html)
Some additional information is available on the LITMUS^RT wiki at:
- Some notes on the [user-space interface](https://wiki.litmus-rt.org/litmus/UserspaceTools).
- General [installation instructions](https://wiki.litmus-rt.org/litmus/InstallationInstructions).
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](https://wiki.litmus-rt.org/litmus/LinkAgainstLiblitmusTutorial).
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](doc/howto-use-resctl.md)
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](doc/table-driven-scheduling.md)
Getting Help
------------
For any questions, bug reports, suggestions, etc. pertaining to
LITMUS^RT or `liblitmus`, please contact the [LITMUS^RT mailing
list](https://wiki.litmus-rt.org/litmus/Mailinglist).
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/](tests/) directory.
|
