Update README.md

1 files 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 [<PLUGIN>]
-  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 <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.
+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 <PARTITION>] [-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 [<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.