From 3e9e2dc67655e4e681dc01f3b35916407eda5ce5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bjo=CC=88rn=20Brandenburg?= Date: Wed, 22 Jun 2016 11:28:09 +0200 Subject: Update README.md --- README.md | 172 ++++++++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 118 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 00a06a5..bb3ce58 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,148 @@ LITMUS^RT User-Space Library: liblitmus ======================================= -Copyright (c) 2007-2015 The LITMUS^RT Project & Contributors +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 +file `litmus.h` contains all necessary system calls and definitions to interact with the kernel services provided for real-time tasks. -Tools and Programs -================== +Documentation +------------- -* setsched [] - Select 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). +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. -* showsched - Print the name of the currently active scheduler. +- [LITMUS^RT tutorial at TuToR'16 @ CPSWeek'16](http:/www.litmus-rt.org/tutor16) -* rt_launch [-w] [-p ] ... - Launch the 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. +In particular, check out the online manual prepared for TuToR'16: - Tip: for debugging purposes, a couple of "rt_launch $EXE $PER find /", - for reasonable values of $EXE and $PER, generates a workload that - stresses the wakeup/suspend path of the scheduler pretty well. - Similarly, running "rt_launch $EXE $PER sha256sum `find /home | sort - -R`" produces a CPU-intensive workload that also includes significant - IO. +- [A Tour of LITMUS^RT](http://www.litmus-rt.org/tutor16/manual.html) -* rtspin [-w] [-p ] [-c CLASS] 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. +Some additional information is available on the LITMUS^RT wiki at: -* release_ts - Release the task system. This allows for synchronous task system - releases (i.e., ensure that all tasks share a common "time zero"). +- Some notes on the [user-space interface](https://wiki.litmus-rt.org/litmus/UserspaceTools). -* measure_syscall - A simple tool that measures the cost of a system call. +- General [installation instructions](https://wiki.litmus-rt.org/litmus/InstallationInstructions). -* cycles - Display measured cycles per time interval, as determined by the cycle - counter. Useful for converting benchmarking results. +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. -* base_task - Example real-time task. Can be used as a basis for the development - of single-threaded real-time tasks. +- HOWTO: [linking against liblitmus](https://wiki.litmus-rt.org/litmus/LinkAgainstLiblitmusTutorial). -* base_mt_task - Example multi-threaded real-time task. Use as a basis for the - development of multithreaded real-time tasks. +As of version 2016.1, LITMUS^RT supports reservation-based scheduling. +How to set up and use reservations is described in a separate document. -* uncache - Demo application showing how to allocate and use uncached pages (i.e., - pages that bypass the cache). +- HOWTO: [working with reservations](doc/howto-use-resctl.md) -* 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. -Further Reading -=============== +Getting Help +------------ -Some additional information is available on the LITMUS^RT Wiki at: +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). -- https://wiki.litmus-rt.org/litmus/UserspaceTools -- https://wiki.litmus-rt.org/litmus/InstallationInstructions +Tools and Programs in `liblitmus` +--------------------------------- -- https://wiki.litmus-rt.org/litmus/LinkAgainstLiblitmusTutorial +### setsched + +Run as: + + setsched [] + +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 ] ... + +Launch the 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 ] 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 ] + +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 ``. + +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. -- cgit v1.2.2