Update README and installation instructions

2 files changed, 56 insertions, 29 deletions

diff --git a/INSTALL b/INSTALL
index 4891f0a..4e7ad77 100644
--- a/INSTALL
+++ b/INSTALL
@@ -2,20 +2,22 @@
 Liblitmus Installation Instructions
 ===================================
 
+See also: https://wiki.litmus-rt.org/litmus/InstallationInstructions
+
 Dependencies
 ------------
 
-Liblitmus has no dependencies besides the kernel. During compilation, the
-Makefile will attempt to copy required headers from the kernel source tree into
-the library source tree.
+Liblitmus has no dependencies besides the kernel. During compilation,
+the Makefile will attempt to copy required headers from the kernel
+source tree into the library source tree.
 
 
 Configuration
 -------------
 
-The build system reads a local configuration file named '.config' (just like the
-kernel, but much simpler). There are three variables that affect the
-compilation process:
+The build system reads a local configuration file named '.config' (just
+like the kernel, but much simpler). There are three variables that
+affect the compilation process:
 
         LITMUS_KERNEL --- Path (relative or absolute) to the LITMUS^RT kernel
                           source tree. The default value is
@@ -23,7 +25,7 @@ compilation process:
                           the kernel somewhere else.
 
         ARCH          --- The target architecture. Currently, liblitmus can be
-                          build for i386, x86_64, sparc64, and arm.  The default
+                          build for i386, x86_64, and arm. The default
                           value is the host architecture.
 
         CROSS_COMPILE --- A prefix for the compiler and linker to use. Works
diff --git a/README b/README
index accdf72..a0b8e6e 100644
--- a/README
+++ b/README
@@ -1,12 +1,8 @@
 LITMUS^RT User-Space Library: liblitmus
 =======================================
 
-  Copyright (c) 2007, 2008, 2009, 2010
-  The University of North Carolina at Chapel Hill
-  Department of Computer Science
-  Real-Time Systems Group
-  Dr. Anderson & students
-  http://www.cs.unc.edu/~anderson/litmus-rt/
+Copyright (c) 2007-2015 The LITMUS^RT Project & Contributors
+http://www.litmus-rt.org
 
 Released as open source under the terms of the GNU General Public License
 (GPL2).
@@ -14,9 +10,9 @@ Released as open source under the terms of the GNU General Public License
 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.
+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.
 
 Tools and Programs
 ==================
@@ -28,31 +24,60 @@ Tools and Programs
   Print the name of the currently active scheduler. Schedulers are selected at
   boot time with the "rtsched=<NAME>" kernel parameter.
 
-* rt_launch [-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.
+* 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 $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.
 
 * rtspin [-w] [-p <PARTITION>] [-c CLASS] WCET PERIOD DURATION
-  rtspin -l
-  A simple spin loop for emulating purely CPU-bound workloads.
-  Not very realistic, but a good tool for debugging.
-    -l   Start a little calibration loop.
-    -w   Wait for task-system release.
+  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.
 
 * release_ts
-  Release the task system. This allows for synchronous task system releases.
+  Release the task system. This allows for synchronous task system
+  releases (i.e., ensure that all tasks share a common "time zero").
 
 * measure_syscall
   A simple tool that measures the cost of a system call.
 
 * cycles
-  Display cycles per time interval.
+  Display measured cycles per time interval, as determined by the cycle
+  counter. Useful for converting benchmarking results.
 
 * base_task
   Example real-time task. Can be used as a basis for the development
   of single-threaded real-time tasks.
 
 * base_mt_task
-  Example multi-threaded real-time task. Use as a basis for the development of
-  multithreaded real-time tasks.
+  Example multi-threaded real-time task. Use as a basis 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.
+
+Further Reading
+===============
+
+Some additional information is available on the LITMUS^RT Wiki at:
+
+- https://wiki.litmus-rt.org/litmus/UserspaceTools
+
+- https://wiki.litmus-rt.org/litmus/InstallationInstructions
+
+- https://wiki.litmus-rt.org/litmus/LinkAgainstLiblitmusTutorial