Formatted first half of README.

2 files changed, 150 insertions, 143 deletions

diff --git a/README.md b/README.md
index e1a0815..57d9afa 100644
--- a/README.md
+++ b/README.md
@@ -1,118 +1,97 @@
-I. INTRODUCTION
-These scripts provide a common way for creating, running, parsing, and
-plotting experiments under LITMUS^RT. They are designed with the
-following principles in mind:
-
-1. Little or no configuration: all scripts use certain parameters to
-configure behavior. However, if the user does not give these
-parameters, the scripts will examine the properties of the user's
-system to pick a suitable default. Requiring user input is a last
-resort.
-
-2. Interruptability: the scripts save their work as they evaluate
-multiple directories. When the scripts are interrupted, or if new data
-is added to those directories, the scripts can be re-run and they will
-resume where they left off. This vastly decreases turnaround time for
-testing new features.
-
-3. Maximum Safety: where possible, scripts save metadata in their output
-directories about the data contained. This metadata can be used by
-the other scripts to safely use the data later.
-
-4. Independence / legacy support: none of these scripts assume their
-input was generated by another of these scripts. Three are designed to
-recognize generic input formats inspired by past LITMUS^RT
-experimental setups. (The exception to this is gen_exps.py, which
-has only user intput and creates output only for run_exps.py)
-
-5. Save everything: all output and parameters (even from subprocesses)
-is saved for debugging / reproducability. This data is saved in tmp/
-directories while scripts are running in case scripts fail.
-
-These scripts require that the following repos are in the user's PATH:
-1. liblitmus - for real-time executable simulation and task set release
-2. feather-trace-tools - for recording and parsing overheads and
-   scheduling events
-
-Optionally, additional features will be enabled if these repos are
-present in the PATH:
-1. rt-kernelshark - to record ftrace events for kernelshark visualization
-2. sched_trace - to output a file containing scheduling events as
-strings
-
-Each of these scripts is designed to operate independently of the
-others. For example, the parse_exps.py will find any feather trace
-files resembling ft-xyz.bin or xyz.ft and print out overhead
-statistics for the records inside. However, the scripts provide the
-most features (especially safety) when their results are chained
-together, like so:
+# About
+These Python scripts provide a common way for creating, running, parsing, and plotting experiments using [LITMUS^RT][litmus]. These scripts are:
 
+1. `gen_exps.py`: for creating sets of experiments
+2. `run_exps.py`: for running and tracing experiments
+3. `parse_exps.py`: for parsing LITMUS^RT trace data
+4. `plot_exps.py`: for plotting directories of csv data
+
+They are designed with the following principles in mind:
+
+1. Little or no configuration: all scripts use certain parameters to configure behavior. However, if the user does not give these parameters, the scripts will examine the properties of the user's system to pick a suitable default. Requiring user input is a last resort.
+
+2. Interruptability: the scripts save their work as they evaluate multiple directories. When the scripts are interrupted, or if new data is added to those directories, the scripts can be re-run and they will resume where they left off. This vastly decreases turnaround time for testing new features.
+
+3. Maximum Safety: where possible, scripts save metadata in their output directories about the data contained. This metadata can be used by the other scripts to safely use the data later.
+
+4. Independence / legacy support: none of these scripts assume their input was generated by another of these scripts. Three are designed to recognize generic input formats inspired by past LITMUS^RT experimental setups. (The exception to this is gen_exps.py, which has only user intput and creates output only for run_exps.py)
+
+5. Save everything: all output and parameters (even from subprocesses) is saved for debugging / reproducability. This data is saved in tmp/ directories while scripts are running in case scripts fail.
+
+# Dependencies
+These scripts were tested using Python 2.7.2. They have not been tested using Python 3. The [Matplotlib][matplotlib] Python library is needed for plotting.
+
+The `run_exps.py` script should almost always be run using a LITMUS^RT kernel. In addition to the kernel, the following LITMUS-related repos must be in the user's `PATH`:
+1. [liblitmus][liblitmus]: for real-time executable simulation and task set release
+2. [feather-trace-tools][feather-trace-tools]: for recording and parsing overheads and scheduling events
+
+Additional features will be enabled if these repos are present in the `PATH`:
+1. [rt-kernelshark][rt-kernelshark]: to record ftrace events for kernelshark visualization
+2. sched_trace ([UNC internal][rtunc]) to output a file containing scheduling events as strings
+
+# Details
+Each of these scripts is designed to operate independently of the others. For example, `parse_exps.py` will find any feather trace files resembling `ft-xyz.bin` or `xyz.ft` and print out overhead statistics for the records inside. However, the scripts provide the most features (especially safety) when their results are chained together, like so:
+
+```
 gen_exps.py --> [exps/*] --> run_exps.py  --> [run-data/*] --.
 .------------------------------------------------------------'
 '--> parse_exps.py --> [parse-data/*] --> plot_exps.py --> [plot-data/*.pdf]
+```
+
+1. Create experiments with `gen_exps.py` or some other script.
+2. Run experiments using `run_exps.py`, generating binary files in `run-data/`.
+3. Parse binary data in `run-data/` using `parse_exps.py`, generating csv files in `parse-data/`.
+4. Plot `parse-data` using `plot_exps.py`, generating pdfs in `plot-data/`.
+
+Each of these scripts will be described. The `run_exps.py` script is first because `gen_exps.py` creates schedule files which depend on `run_exps.py`.
+
 
-0. Create experiments with gen_exps.py or some other script.
-1. Run experiments using run_exps.py, generating binary files in run-data/.
-2. Parse binary data in run-data using parse_exps.py, generating csv
-   files in parse-data/.
-3. Plot parse-data using plot_exps.py, generating pdfs in plot-data.
-
-Each of these scripts will be described. The run_exps.py script is
-first because gen_exps.py creates schedule files which depend on run_exps.py.
-
-
-II. RUN_EXPS
-Usage: run_exps.py [OPTIONS] [SCHED_FILE]... [SCHED_DIR]...
-       where a SCHED_DIR resembles:
-         SCHED_DIR/
-            SCHED_FILE
-            PARAM_FILE
-
-Output: OUT_DIR/[files] or OUT_DIR/SCHED_DIR/[files] or
-        OUT_DIR/SCHED_FILE/[files] depending on input
-        If all features are enabled, these files are:
-        OUT_DIR/[.*/]
-           trace.slog    # LITMUS logging
-           st-[1..m].bin # sched_trace data
-           ft.bin        # feather-trace overhead data
-           trace.dat     # ftrace data for kernelshark
-           params.py     # Schedule parameters
-           exec-out.txt  # Standard out from schedule processes
-           exec-err.txt  # Standard err '''
-
-Defaults: SCHED_FILE = sched.py, PARAM_FILE = params.py,
-          DURATION = 30, OUT_DIR = run-data/
-
-The run_exps.py script reads schedule files and executes real-time
-task systems, recording all overhead, logging, and trace data which is
-enabled in the system. For example, if trace logging is enabled,
-rt-kernelshark is found in the path, but feather-trace is disabled
-(the devices are not present), only trace-logs and kernelshark logs
-will be recorded.
-
-When run_exps.py is running a schedule file, temporary data is saved
-in a 'tmp' directory in the same directory as the schedule file. When
-execution completes, this data is moved into a directory under the
-run_exps.py output directory (default: 'run-data/', can be changed with
-the -o option). When multiple schedules are run, each schedule's data
-is saved in a unique directory under the output directory.
-
-If a schedule has been run and it's data is in the output directory,
-run_exps.py will not re-run the schedule unless the -f option is
-specified. This is useful if your system crashes midway through a set
-of experiments.
+## run_exps.py
+*Usage*: `run_exps.py [OPTIONS] [SCHED_FILE]... [SCHED_DIR]...`
+
+where a `SCHED_DIR` resembles:
+```
+SCHED_DIR/
+        SCHED_FILE
+        PARAM_FILE
+```
+
+*Output*: `OUT_DIR/[files]` or `OUT_DIR/SCHED_DIR/[files]` or `OUT_DIR/SCHED_FILE/[files]` depending on input
+
+If all features are enabled, these files are:
+```
+OUT_DIR/[SCHED_(FILE|DIR)/]
+        trace.slog    # LITMUS logging
+        st-[1..m].bin # sched_trace data
+        ft.bin        # feather-trace overhead data
+        trace.dat     # ftrace data for kernelshark
+        params.py     # Schedule parameters
+        exec-out.txt  # Standard out from schedule processes
+        exec-err.txt  # Standard err '''
+```
+
+*Defaults*: `SCHED_FILE = sched.py, PARAM_FILE = params.py, DURATION = 30, OUT_DIR = run-data/`
+
+This script reads *schedule files* (described below) and executes real-time task systems, recording all overhead, logging, and trace data which is enabled in the system. For example, if trace logging is enabled, rt-kernelshark is found in the path, but feather-trace is disabled (the devices are not present), only trace logs and rt-kernelshark logs will be recorded.
+
+When `run_exps.py` is running a schedule file, temporary data is saved in a `tmp` directory in the same directory as the schedule file. When execution completes, this data is moved into a directory under the `run_exps.py` output directory (default: `run-data/`, can be changed with the `-o` option). When multiple schedules are run, each schedule's data is saved in a unique directory under the output directory.
+
+If a schedule has been run and it's data is in the output directory, `run_exps.py` will not re-run the schedule unless the `-f` option is specified. This is useful if your system crashes midway through a set of experiments.
 
 Schedule files have one of the following two formats:
 
-a) simple format
+1. simple format
+```
        path/to/proc{proc_value}
        ...
        path/to/proc{proc_value}
        [real_time_task: default rtspin] task_arguments...
        ...
        [real_time_task] task_arguments...
+```
 
 b) python format
+```python
        {'proc':[
            ('path/to/proc','proc_value'),
             ...,
@@ -124,55 +103,67 @@ b) python format
            ('real_time_task', 'task_arguments')
         ]
        }
+```
 
-The following creates a simple 3-task system with utilization 2.0,
-which is then run under the GSN-EDF plugin:
+The following creates a simple 3-task system with utilization 2.0, which is then run under the `GSN-EDF` plugin:
 
+```bash
 $ echo "10 20
 30 40
 60 90" > test.sched
 $ run_exps.py -s GSN-EDF test.sched
-
-The following will write a release master using
-/proc/litmus/release_master:
-
+[Exp test/test.sched]: Enabling sched_trace
+...
+[Exp test/test.sched]: Switching to GSN-EDF
+[Exp test/test.sched]: Starting 3 tracers
+[Exp test/test.sched]: Starting the programs
+[Exp test/test.sched]: Sleeping until tasks are ready for release...
+[Exp test/test.sched]: Releasing 3 tasks
+[Exp test/test.sched]: Waiting for program to finish...
+[Exp test/test.sched]: Saving results in /root/schedules/test/run-data/test.sched
+[Exp test/test.sched]: Stopping tracers
+[Exp test/test.sched]: Switching to Linux scheduler
+[Exp test/test.sched]: Experiment done!
+Experiments run:        1
+  Successful:           1
+  Failed:               0
+  Already Done:         0
+  Invalid environment:  0
+
+```
+
+The following will write a release master using `/proc/litmus/release_master`:
+
+```bash
 $ echo "release_master{2}
 10 20" > test.sched && run_exps.py -s GSN-EDF test.sched
+```
 
-A longer form can be used for proc entries not in /proc/litmus:
+A longer form can be used for proc entries not under `/proc/litmus`:
 
+```bash
 $ echo "/proc/sys/something{hello}"
 10 20" > test.sched
+```
 
-You can specify your own spin programs to run as well instead of
-rtspin by putting their name at the beginning of the line.
+You can specify your own spin programs to run as well instead of rtspin by putting their name at the beginning of the line. This example also shows how you can reference files in the same directory as the schedule file on the command line.
 
+```bash
 $ echo "colorspin -f color1.csv 10 20" > test.sched
+```
 
-This example also shows how you can reference files in the same
-directory as the schedule file on the command line.
-
-You can specify parameters for an experiment in a file instead of on
-the command line using params.py (the -p option lets you choose the
-name of this file if params.py is not for you):
+You can specify parameters for an experiment in a file instead of on the command line using params.py (the `-p` option lets you choose the name of this file if params.py is not for you):
 
+```bash
 $ echo "{'scheduler':'GSN-EDF', 'duration':10}" > params.py
 $ run_exps.py test.sched
+```
 
-You can also run multiple experiments with a single command, provided
-a directory with a schedule file exists for each. By default, the
-program will look for sched.py for the schedule file and params.py for
-the parameter file, but this behavior can be changed using the -p and
--c options.
-
-You can include non-relevant parameters which run_exps.py does not
-understand in params.py. These parameters will be saved with the data
-output by run_exps.py. This is useful for tracking variations in
-system parameters versus experimental results.
+You can also run multiple experiments with a single command, provided a directory with a schedule file exists for each. By default, the program will look for sched.py for the schedule file and params.py for the parameter file, but this behavior can be changed using the `-p` and `-c` options.
 
-In the following example, multiple experiments are demonstrated and an
-extra parameter 'test-param' is included:
+You can include non-relevant parameters which `run_exps.py` does not understand in `params.py`. These parameters will be saved with the data output by `run_exps.py`. This is useful for tracking variations in system parameters versus experimental results. In the following example, multiple experiments are demonstrated and an extra parameter `test-param` is included:
 
+```bash
 $ mkdir test1
 # The duration will default to 30 and need not be specified
 $ echo "{'scheduler':'C-EDF', 'test-param':1} > test1/params.py
@@ -180,31 +171,42 @@ $ echo "10 20" > test1/sched.py
 $ cp -r test1 test2
 $ echo "{'scheduler':'GSN-EDF', 'test-param':2}"> test2/params.py
 $ run_exps.py test*
+```
 
-Finally, you can specify system properties in params.py which the
-environment must match for the experiment to run. These are useful if
-you have a large batch of experiments which must be run under
-different kernels. The first property is a regular expression for the
-uname of the system:
+Finally, you can specify system properties in `params.py` which the environment must match for the experiment to run. These are useful if you have a large batch of experiments which must be run under different kernels or kernel configurations. The first property is a regular expression for the name of the kernel:Invalid environment for experiment 'test.sched'
+Kernel name does not match '.*linux.*'.
+Experiments run:        1
+  Successful:           0
+  Failed:               0
+  Already Done:         0
+  Invalid Environment:  1
 
+```bash
 $ uname -r
 3.0.0-litmus
 $ cp params.py old_params.py
 $ echo "{'uname': r'.*linux.*'}" >> params.py
-# run_exps.py will now complain of an invalid environment for this
-experiment
+$ run_exps.py -s GSN-EDF test.sched
+Invalid environment for experiment 'test.sched'
+Kernel name does not match '.*linux.*'.
+Experiments run:        1
+  Successful:           0
+  Failed:               0
+  Already Done:         0
+  Invalid Environment:  1
 $ cp old_params.py params.py
 $ echo "{'uname': r'.*litmus.*'}" >> params.py
 # run_exps.py will now succeed
+```
 
-The second property are kernel configuration options. These assume the
-configuration is stored at /boot/config-`uname -r`. You can specify
-these like so:
+The second property is kernel configuration options. These assume the configuration is stored at `/boot/config-```uname -r`` `. You can specify these like so:
 
+```bash
+# Only executes on ARM systems with the release master enabled
 $ echo "{'config-options':{
 'RELEASE_MASTER' : 'y',
 'ARM' : 'y'}}" >> params.py
-# Only executes on ARM systems with the release master enabled
+```
 
 
 III. GEN_EXPS
@@ -505,3 +507,9 @@ However, when a single directory of directories is given, the script
 assumes the experiments are related and can make line styles match in
 different plots and more effectively parallelize the plotting.
 
+[litmus]: https://github.com/LITMUS-RT/litmus-rt
+[liblitmus]: https://github.com/LITMUS-RT/liblitmus
+[rt-kernelshark]: https://github.com/LITMUS-RT/rt-kernelshark
+[feather-trace-tools]: https://github.com/LITMUS-RT/feather-trace-tools
+[rtunc]: http://www.cs.unc.edu/~anderson/real-time/
+[matplotlib]: http://matplotlib.org/
\ No newline at end of file
diff --git a/run_exps.py b/run_exps.py
index dc15701..6873877 100755
--- a/run_exps.py
+++ b/run_exps.py
@@ -15,12 +15,11 @@ from run.experiment import Experiment,ExperimentDone
 from run.proc_entry import ProcEntry
 
 class InvalidKernel(Exception):
-    def __init__(self, kernel, wanted):
+    def __init__(self, kernel):
         self.kernel = kernel
-        self.wanted = wanted
 
     def __str__(self):
-        return "Kernel '%s' does not match '%s'." % (self.kernel, self.wanted)
+        return "Kernel name does not match '%s'." % self.kernel
 
 ConfigResult = namedtuple('ConfigResult', ['param', 'wanted', 'actual'])
 class InvalidConfig(Exception):
@@ -119,7 +118,7 @@ def load_experiment(sched_file, scheduler, duration, param_file, out_dir):
     exp_name = os.path.split(dir_name)[1] + "/" + fname
 
     params = {}
-    kernel = ""
+    kernel = copts = ""
 
     param_file = param_file or \
       "%s/%s" % (dir_name, conf.DEFAULTS['params_file'])
@@ -259,7 +258,7 @@ def main():
             print("Experiment '%s' already completed at '%s'" % (exp, out_base))
         except (InvalidKernel, InvalidConfig) as e:
             invalid += 1
-            print("Invalid environment for experiment '%s'")
+            print("Invalid environment for experiment '%s'" % exp)
             print(e)
         except:
             print("Failed experiment %s" % exp)
@@ -273,7 +272,7 @@ def main():
     print("  Successful:\t\t%d" % succ)
     print("  Failed:\t\t%d" % failed)
     print("  Already Done:\t\t%d" % done)
-    print("  Invalid environment:\t\t%d" % invalid)
+    print("  Invalid Environment:\t%d" % invalid)
 
 
 if __name__ == '__main__':