Updated the documentation to describe the visualizer, made unit-trace itself not require gtk/cairo, and a few other minor things.

1 files changed, 76 insertions, 3 deletions

diff --git a/doc/index.txt b/doc/index.txt
index 9360e40..135579b 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -115,9 +115,82 @@ Some submodules have further documentation, appearing later in this document.
 
 ## Specific Submodule Documentation ##
 
-Here, documentation is provided for submodules for which relevant information is not considered to be self-evident.
+### The Visualizer Module ###
+
+The visualizer can give you an on-the-fly visual representation of the input
+stream, with the ability to scroll through a graph of the schedule and inspect
+various elements of it. To run the visualizer, add the `-v`
+option when invoking unit-trace. Note that you don't have to run the visualizer
+by itself -- for instance, you can both run the visualizer and get input to
+stdout by combining the `-v` and `-o`
+options. The information that goes into the visualizer is dependent on the
+input parameters you specify. For example, if you use `-e`
+and `-l` to specify a time range, the visualizer will
+generate a graph restricted to that time range.
+
+When the visualizer starts up, you'll see the beginning of the graph which the
+visualizer automatically generated. We'll first discuss the axes.
+The x-axis gives time (in whatever units
+the trace file was using). The meanings of the markings by y-axis depend on whether you
+are in Task Mode or CPU Mode. (You can change between Task Mode and
+CPU Mode by clicking the tabs at the top.) In Task Mode, the schedule is organized
+by task, so each item listed to the left of the y-axis gives
+the name of a task that was running (at present, the name of a task is its PID).
+Likewise, in CPU Mode the schedule is organized by CPU number, and each item
+gives the identifier of a CPU that at one point was used by at least one task.
+
+The horizontal cross-section demarcated by each task name or CPU
+identifier gives the chronological sequence of events in the input stream
+for the relevant task or CPU. The event symbols are as follows:
 
-(So far, it hasn't been necessary to add anything here, but once questions arise, it will become clear which submodules need to be documented more fully.)
+<table border=1>
+<tr><td>Symbol Description</td><td>Event Type</td><td>Meaning</td></tr>
+<tr><td>Large colored bar</td><td>Scheduled</td><td>A job was scheduled during the period spanned by the bar.</td>
+<tr><td>Black triangle</td><td>Suspend (Block)</td><td>A task blocked at this time.</td></tr>
+<tr><td>White triangle</td><td>Resume (Unblock)</td><td>A task resumed execution at this time.</td></tr>
+<tr><td>"T" shape</td><td>Complete</td><td>A task signaled its completion of a job at this time.</td></tr>
+<tr><td>Large up arrow</td><td>Release</td><td>A job release occurred. (Appears only in Task Mode.)</td></tr>
+<tr><td>Small up arrow</td><td>Release</td><td>A job release occurred. (Appears only in CPU Mode. These appear
+attached to the x-axis, as is customary, rather than in a CPU's area.)</td></tr>
+<tr><td>Large down arrow</td><td>Deadline</td><td>A job's deadline occurs at this time. (Appears only in Task Mode.)</td></tr>
+<tr><td>Small down arrow</td><td>Deadline</td><td>A job's deadline occurs at this time. (Appears only in CPU Mode. These appear
+attached to the x-axis, as is customary, rather than in a CPU's area.)</td></tr>
+<tr><td>Small colored bar</td><td>Priority Inversion</td><td>(Appears only in conjuction with the gedf_test module.) A priority inversion occurred for some task: that is, the task in question <i>should</i> have been scheduled at the depicted time, but wasn't. In Task Mode these are organized by task (and appear gray since color would be redundant), and in CPU mode they appear at the bottom, colored by task.</td></tr> 
+</table>
+
+If you're unsure as
+to what a certain symbol means, you can also mouse over it in the visualizer
+and read the description at the bottom of the screen.
+
+Also, a note about the `Scheduled` (and `Priority Inversion`) events: each of these events actually
+corresponds to two events in the input stream. Namely, a `Scheduled` event is really a `Switch To`
+event paired with a `Switch Away` event, and a `Priority Inversion` event is really an
+`Inversion Start` event paired with an `Inversion End` event. These events of course correspond to
+being scheduled and being descheduled, respectively. <i>However</i>, if the visualizer module
+finds a start event but not an end event (or vice-versa), it assumes that the corresponding
+event occurred, but at a time not in the input stream.
+In other words, it assumes that such events are genuine. To represent this phenomenon,
+the visualizer shows the bar going "off the graph". 
+
+Interacting with the visualizer is easy. The scrollbars work in the obvious way. You can also
+use the arrow keys to move, or use Ctrl+arrow keys to move faster. Mousing over an event gives
+a description of the event at the bottom. You can also click an event to
+select it. Hold down Ctrl to select multiple events. You can also drag a box around multiple
+events to select them. You can even combine this with the Ctrl key to select multiple
+boxes of events in succession. Your selection is independent of the mode you are in --
+thus if you wanted to see e.g. what CPUs a task was running on from time A to time B,
+you could just select all the events under the task in question in Task Mode and then
+switch over to CPU mode. Right-click and you will get a context menu containing each event
+you selected. Selecting an item in the menu gives you detailed information about the event
+in its own window.
+
+If you want to see what's happening at a certain time, but don't want to bother scrolling there
+manually, you can select `View->Move to Time` and type in the time you want to move to.
+
+You can also zoom by either going to `View->Zoom In/Out`, or by holding down Ctrl and scrolling
+the mouse wheel.
+
+To exit the Unit-Trace visualizer, go to `File->Quit` or click the close button.
 
 ## Gotchas ##
 
@@ -150,7 +223,7 @@ The following "rules" are currently in place:
 ### Architecture ###
 If you are interested in contributing to Unit-Trace, you probably ought to know a bit about its overall architecture.
 
-Generally speaking, each Unit-Trace submodules is a Python generator. It accepts a Python iterator object as input and returns a Python iterator
+Generally speaking, each Unit-Trace submodule is a Python generator. It accepts a Python iterator object as input and returns a Python iterator
 object as output. (You may want to look up the relevant Python terminology.)
 
 The exceptions are input submodules, which do not take any input other than a list of trace files, and the output submodules, which do not return