diff options
author | Björn Brandenburg <bbb@mpi-sws.org> | 2016-06-22 05:28:09 -0400 |
---|---|---|
committer | Björn Brandenburg <bbb@mpi-sws.org> | 2016-06-22 05:28:09 -0400 |
commit | 3e9e2dc67655e4e681dc01f3b35916407eda5ce5 (patch) | |
tree | 8cb8efcd0c83d3a93f387af8b17acce599b82d9d | |
parent | eacdec74addc7d31453f7754822f4edc79daddc7 (diff) |
Update README.md
-rw-r--r-- | README.md | 172 |
1 files changed, 118 insertions, 54 deletions
@@ -1,84 +1,148 @@ | |||
1 | LITMUS^RT User-Space Library: liblitmus | 1 | LITMUS^RT User-Space Library: liblitmus |
2 | ======================================= | 2 | ======================================= |
3 | 3 | ||
4 | Copyright (c) 2007-2015 The LITMUS^RT Project & Contributors | 4 | Copyright (c) 2007-2016 The LITMUS^RT Project & Contributors |
5 | http://www.litmus-rt.org | 5 | http://www.litmus-rt.org |
6 | 6 | ||
7 | Released as open source under the terms of the GNU General Public License | 7 | Released as open source under the terms of the GNU General Public License |
8 | (GPL2). | 8 | (GPL2). |
9 | 9 | ||
10 | Overview | 10 | Overview |
11 | ======== | 11 | -------- |
12 | This library and the included tools provide the user-space interface to | 12 | This library and the included tools provide the user-space interface to |
13 | LITMUS^RT. Real-time tasks should link against this library. The header | 13 | LITMUS^RT. Real-time tasks should link against this library. The header |
14 | file "litmus.h" contains all necessary system calls and definitions to | 14 | file `litmus.h` contains all necessary system calls and definitions to |
15 | interact with the kernel services provided for real-time tasks. | 15 | interact with the kernel services provided for real-time tasks. |
16 | 16 | ||
17 | Tools and Programs | 17 | Documentation |
18 | ================== | 18 | ------------- |
19 | 19 | ||
20 | * setsched [<PLUGIN>] | 20 | For a gentle introduction to LITMUS^RT and its userspace tools, we |
21 | Select the active scheduler. Must be run as root. Run without argument to be | 21 | recommend to check out the materials that were prepared for the |
22 | presented with a list of available plugins (requires 'dialog' to be | 22 | LITMUS^RT tutorial presented at TuToR'16 @ CPSWeek'16. |
23 | installed). | ||
24 | 23 | ||
25 | * showsched | 24 | - [LITMUS^RT tutorial at TuToR'16 @ CPSWeek'16](http:/www.litmus-rt.org/tutor16) |
26 | Print the name of the currently active scheduler. | ||
27 | 25 | ||
28 | * rt_launch [-w] [-p <PARTITION>] <WCET> <PERIOD> <PROGRAM> <ARGS>... | 26 | In particular, check out the online manual prepared for TuToR'16: |
29 | Launch the program <PROGRAM> as a real-time task provisioned with the | ||
30 | given worst-case execution time and priod. Any additional parameters | ||
31 | are passed on to the real-time task. The -w option makes the task wait | ||
32 | for a sytem release. Run rt_launch -h for further options. | ||
33 | 27 | ||
34 | Tip: for debugging purposes, a couple of "rt_launch $EXE $PER find /", | 28 | - [A Tour of LITMUS^RT](http://www.litmus-rt.org/tutor16/manual.html) |
35 | for reasonable values of $EXE and $PER, generates a workload that | ||
36 | stresses the wakeup/suspend path of the scheduler pretty well. | ||
37 | Similarly, running "rt_launch $EXE $PER sha256sum `find /home | sort | ||
38 | -R`" produces a CPU-intensive workload that also includes significant | ||
39 | IO. | ||
40 | 29 | ||
41 | * rtspin [-w] [-p <PARTITION>] [-c CLASS] WCET PERIOD DURATION | 30 | Some additional information is available on the LITMUS^RT wiki at: |
42 | A simple spin loop for emulating purely CPU-bound workloads. Not very | ||
43 | realistic, but a good tool for debugging. The -w option makes the task | ||
44 | wait for a sytem release. Run rtspin -h for further options. | ||
45 | 31 | ||
46 | * release_ts | 32 | - Some notes on the [user-space interface](https://wiki.litmus-rt.org/litmus/UserspaceTools). |
47 | Release the task system. This allows for synchronous task system | ||
48 | releases (i.e., ensure that all tasks share a common "time zero"). | ||
49 | 33 | ||
50 | * measure_syscall | 34 | - General [installation instructions](https://wiki.litmus-rt.org/litmus/InstallationInstructions). |
51 | A simple tool that measures the cost of a system call. | ||
52 | 35 | ||
53 | * cycles | 36 | When writing real-time applications that need to make use of |
54 | Display measured cycles per time interval, as determined by the cycle | 37 | LITMUS^RT-specific interfaces and facilities, the application binary |
55 | counter. Useful for converting benchmarking results. | 38 | needs to be linked against `liblitmus` (this library). Instructions for |
39 | how to do so are provided on the LITMUS^RT wiki. | ||
56 | 40 | ||
57 | * base_task | 41 | - HOWTO: [linking against liblitmus](https://wiki.litmus-rt.org/litmus/LinkAgainstLiblitmusTutorial). |
58 | Example real-time task. Can be used as a basis for the development | ||
59 | of single-threaded real-time tasks. | ||
60 | 42 | ||
61 | * base_mt_task | 43 | As of version 2016.1, LITMUS^RT supports reservation-based scheduling. |
62 | Example multi-threaded real-time task. Use as a basis for the | 44 | How to set up and use reservations is described in a separate document. |
63 | development of multithreaded real-time tasks. | ||
64 | 45 | ||
65 | * uncache | 46 | - HOWTO: [working with reservations](doc/howto-use-resctl.md) |
66 | Demo application showing how to allocate and use uncached pages (i.e., | ||
67 | pages that bypass the cache). | ||
68 | 47 | ||
69 | * runtests | ||
70 | The LITMUS^RT test suite. By default, it runs the tests for the | ||
71 | currently active plugin. Use this frequently when hacking on the core | ||
72 | plugins. Add support for new plugins as needed. The tests can be found | ||
73 | in tests/ directory. | ||
74 | 48 | ||
75 | Further Reading | 49 | Getting Help |
76 | =============== | 50 | ------------ |
77 | 51 | ||
78 | Some additional information is available on the LITMUS^RT Wiki at: | 52 | For any questions, bug reports, suggestions, etc. pertaining to |
53 | LITMUS^RT or `liblitmus`, please contact the [LITMUS^RT mailing | ||
54 | list](https://wiki.litmus-rt.org/litmus/Mailinglist). | ||
79 | 55 | ||
80 | - https://wiki.litmus-rt.org/litmus/UserspaceTools | ||
81 | 56 | ||
82 | - https://wiki.litmus-rt.org/litmus/InstallationInstructions | 57 | Tools and Programs in `liblitmus` |
58 | --------------------------------- | ||
83 | 59 | ||
84 | - https://wiki.litmus-rt.org/litmus/LinkAgainstLiblitmusTutorial | 60 | ### setsched |
61 | |||
62 | Run as: | ||
63 | |||
64 | setsched [<PLUGIN>] | ||
65 | |||
66 | Selects the active scheduler. Must be run as root. Run without argument | ||
67 | to be presented with a list of available plugins (requires 'dialog' to | ||
68 | be installed). | ||
69 | |||
70 | ### showsched | ||
71 | |||
72 | Run as: | ||
73 | |||
74 | showsched | ||
75 | |||
76 | Print the name of the currently active scheduler. | ||
77 | |||
78 | ### rt_launch | ||
79 | |||
80 | Run as: | ||
81 | |||
82 | rt_launch [-w] [-p <PARTITION>] <WCET> <PERIOD> <PROGRAM> <ARGS>... | ||
83 | |||
84 | Launch the program `<PROGRAM>` as a real-time task provisioned with the | ||
85 | given worst-case execution time and priod. Any additional parameters are | ||
86 | passed on to the real-time task. The -w option makes the task wait for a | ||
87 | sytem release. Run `rt_launch -h` for further options. | ||
88 | |||
89 | Tip: for debugging purposes, a couple of | ||
90 | |||
91 | rt_launch $EXEC_TIME $PERIOD find / | ||
92 | |||
93 | real-time processes, for reasonable values of `$EXEC_TIME` and | ||
94 | `$PERIOD`, generates a workload that stresses the wakeup/suspend path of | ||
95 | the scheduler pretty well. Similarly, running | ||
96 | |||
97 | rt_launch $EXEC_TIME $PERIOD sha256sum `find /home | sort -R | ||
98 | |||
99 | produces a CPU-intensive workload that also includes significant IO. | ||
100 | |||
101 | ### rt_spin | ||
102 | |||
103 | Run as: | ||
104 | |||
105 | rtspin [-w] [-p <PARTITION>] WCET PERIOD DURATION | ||
106 | |||
107 | A simple spin loop for emulating purely CPU-bound workloads. Not very | ||
108 | realistic, but a good tool for debugging. The `-w` option makes the task | ||
109 | wait for a sytem release. Run `rtspin -h` for further options. | ||
110 | |||
111 | The parameters `WCET` and `PERIOD` must be given in milliseconds, the | ||
112 | paramter `DURATION` must be given in seconds. | ||
113 | |||
114 | ### release_ts | ||
115 | |||
116 | Run as: | ||
117 | |||
118 | release_ts [-f <NUM_TASKS>] | ||
119 | |||
120 | Release the task system. This allows for synchronous task system | ||
121 | releases (i.e., ensure that all tasks share a common "time zero"). The | ||
122 | `-f` option makes `release_ts` wait until the number of tasks waiting | ||
123 | for the task system release equals `<NUM_TASKS>`. | ||
124 | |||
125 | See `release_ts -h` for further options. | ||
126 | |||
127 | |||
128 | ### Other tools | ||
129 | |||
130 | * `measure_syscall`: A simple tool that measures the cost of invoking a | ||
131 | LITMUS^RT system call. | ||
132 | |||
133 | * `cycles`: Display measured cycles per time interval, as determined by | ||
134 | the cycle counter. Useful for converting benchmarking results. | ||
135 | |||
136 | * `base_task`: Example real-time task. To be used as a template for the | ||
137 | development of single-threaded real-time tasks. | ||
138 | |||
139 | * `base_mt_task`: Example multi-threaded real-time task. To be used as a | ||
140 | template for the development of multithreaded real-time tasks. | ||
141 | |||
142 | * `uncache`: Demo application showing how to allocate and use uncached | ||
143 | pages (i.e., pages that bypass the cache). | ||
144 | |||
145 | * `runtests`: The LITMUS^RT test suite. By default, it runs the tests | ||
146 | for the currently active plugin. Use this frequently when hacking on the | ||
147 | core plugins. Add support for new plugins as needed. The tests can be | ||
148 | found in [tests/](tests/) directory. | ||