Updated tracing page for 2010.2

- litmus_log now available as /dev/litmus/log
- Unit-Trace now available
- Other minor fixes to the page

2 files changed, 21 insertions, 31 deletions

diff --git a/doc/tracing.html b/doc/tracing.html
index c1a262b..fae0bd2 100644
--- a/doc/tracing.html
+++ b/doc/tracing.html
@@ -37,7 +37,7 @@ TITLE=Tracing with LITMUS^RT
 This document is part of the documentation of the <a href="../index.html">LITMUS<sup>RT</sup> project</a>.
 </div>
 
-<p>As of version 2008.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:</p>
+<p>As of version 2010.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:</p>
 
 <ol>
 <li><p><code>litmus_log</code>: This trace contains text messages (created with the <code>TRACE()</code>
@@ -49,17 +49,17 @@ macro, see <code>litmus.h</code>) that convey information useful for debugging.
 
 <h2>Accessing Trace Buffers</h2>
 
-<p>Currently, all three traces are exported to user space through character device drivers. The major numbers allocated by the drivers can be discovered by looking at <code>/proc/devices</code>. Usually, the major numbers are 251, 252, and 253 respectively.</p>
+<p><code>litmus_log</code> functionality is provided through the kernel's <code>misc</code> driver interface. As a result, <code>litmus_log</code> is automatically made available through <code>/dev/litmus/log</code> on systems with default udev rules.</p>
 
-<p>The per-processor buffers are accessible via the minor numbers of the drivers. Hence, proper device files can be created with the following script.</p>
+<p>The other two traces are exported to user space through standard character device drivers. The major numbers allocated by the drivers can be discovered by looking at <code>/proc/devices</code>. Usually, the major numbers are 252 and 253, respectively. The per-processor buffers are accessible via the minor numbers of the <code>sched_trace</code> driver.</p>
+
+<p>Thus, device files for <code>ft_trace</code> and <code>sched_trace</code> can be created with the following script.</p>
 
 <pre><code>#!/bin/bash
 
-LITMUS_LOG_MAJOR=`grep litmus_log /proc/devices | awk '{print $1}'`
 FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'`
 SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'`
 
-mknod litmus_log c $LITMUS_LOG_MAJOR 0
 mknod ft_trace   c $FT_TRACE_MAJOR   0
 
 NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1))
@@ -76,7 +76,7 @@ done
 
 <p>The <code>litmus_log</code> buffer can be read by simply opening the file and reading its contents:</p>
 
-<pre><code>cat litmus_log &gt; my_debug_log
+<pre><code>cat /dev/litmus/log &gt; my_debug_log
 </code></pre>
 
 <p>Kill the <code>cat</code> process to stop recording debug messages.</p>
@@ -160,7 +160,7 @@ Used to measure the time spent to enqueue a newly-released job in a ready queue.
 
 <p>Scheduling traces are also recorded using Feather-Trace. However, a different binary format is used. The definition and an explanation of the format can be found in the file <code>include/litmus/sched_trace.h</code> (in the kernel directory).</p>
 
-<p>Since <code>sched_trace</code> uses per-processor buffers several <code>ftcat</code> instances have to be launched. The <code>ft_tools</code> package includes a wrapper script called <code>st_trace</code> that automates this setup procedure. Note that one may have to modify <code>st_trace</code> to change the default location of the <code>sched_trace</code> device files. <code>st_trace</code> accepts a tag as the only argument. The tag is used to assign a unique name to the trace files.</p>
+<p>Since <code>sched_trace</code> uses per-processor buffers several <code>ftcat</code> instances have to be launched. The <code>ft_tools</code> package includes a wrapper script called <code>st_trace</code> that automates this setup procedure. Note that one may have to modify <code>st_trace</code> to change the default location of the <code>sched_trace</code> device files and the <code>ftcat</code> binary. <code>st_trace</code> accepts a tag as the only argument. The tag is used to assign a unique name to the trace files.</p>
 
 <p>The following example illustrates how <code>st_trace</code> is used with the tag <code>global-exp</code>.</p>
 
@@ -181,26 +181,21 @@ Disabling 9 events.
 /home/litmus/log3: 1234 bytes read.
 </code></pre>
 
-<p>Note that <code>st_trace</code> may have to be modified to change the default <code>sched_trace</code> device locations.</p>
+<p>Note that <code>st_trace</code> may have to be modified to change the default <code>sched_trace</code> device locations and the <code>ftcat</code> binary.</p>
 
 <p><strong>Hint</strong>: The dummy real-time task <code>rtspin</code> (distributed as part of the <code>liblitmus</code> package) may be useful when studying/testing the behavior of a scheduler plugin.</p>
 
-<h2>Post-Processing Scheduling Traces</h2>
-
-<p>The user space library and tools package <code>liblitmus</code> contains the necessary headers to write <code>sched_trace</code> post-processing and analysis tools (see <code>include/sched_trace.h</code> and <code>src/sched_trace.c</code>).</p>
-
-<p>The tool <code>showst</code> (distributed as part of <code>liblitmus</code>) can be used to inspect the binary traces recorded with <code>st_trace</code> and may provide a good starting point for the development of custom analysis tools.</p>
+<p>Recorded scheduling traces can be analyzed with <a href="http://cs.unc.edu/~mollison/unit-trace">Unit-Trace</a>. Alternatively,  the user space library and tools package <code>liblitmus</code> contains the necessary headers to write <code>sched_trace</code> post-processing and analysis tools (see <code>include/sched_trace.h</code> and <code>src/sched_trace.c</code>).</p>
 
 <h2>Concluding Remarks</h2>
 
-<p>At this point we only offer data <em>acquisition</em> tools since we have not yet had the time to develop release-quality <em>analysis</em> tools. <strong>Patches that improve the existing tools and contributions of new analysis and visualization tools are very much welcome!</strong></p>
-
 <p>For any questions please contact the current LITMUS<sup>RT</sup> maintainer (as indicated on the <a href="../index.html#collaborators">LITMUS<sup>RT</sup> homepage</a>).</p>
 
 <h2>Change History</h2>
 
 <ul>
 <li>Initially written by <a href="http://www.cs.unc.edu/~bbb">Bjoern B. Brandenburg</a> (bbb at cs.unc.edu) on 12/09/2008.</li>
+<li>Updated for LITMUS<sup>RT</sup> version 2010.2 by <a href="http://www.cs.unc.edu/~mollison">Mac Mollison</a> (mollison at cs.unc.edu) on 11/08/2010.</li>
 </ul>
 <script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
 </script>
diff --git a/doc/tracing.txt b/doc/tracing.txt
index e91a758..2e44e10 100644
--- a/doc/tracing.txt
+++ b/doc/tracing.txt
@@ -28,7 +28,7 @@ Tracing with LITMUS<sup>RT</sup>
 This document is part of the documentation of the <a href="../index.html">LITMUS<sup>RT</sup> project</a>.
 </div>
 
-As of version 2008.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:
+As of version 2010.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:
 
 1. `litmus_log`: This trace contains text messages (created with the `TRACE()`
 macro, see `litmus.h`) that convey information useful for debugging. There is one global
@@ -41,17 +41,17 @@ macro, see `litmus.h`) that convey information useful for debugging. There is on
 Accessing Trace Buffers
 -----------------------
 
-Currently, all three traces are exported to user space through character device drivers. The major numbers allocated by the drivers can be discovered by looking at `/proc/devices`. Usually, the major numbers are 251, 252, and 253 respectively.
+`litmus_log` functionality is provided through the kernel's `misc` driver interface. As a result, `litmus_log` is automatically made available through `/dev/litmus/log` on systems with default udev rules.
 
-The per-processor buffers are accessible via the minor numbers of the drivers. Hence, proper device files can be created with the following script.
+The other two traces are exported to user space through standard character device drivers. The major numbers allocated by the drivers can be discovered by looking at `/proc/devices`. Usually, the major numbers are 252 and 253, respectively. The per-processor buffers are accessible via the minor numbers of the `sched_trace` driver.
+
+Thus, device files for `ft_trace` and `sched_trace` can be created with the following script.
 
     #!/bin/bash
     
-    LITMUS_LOG_MAJOR=`grep litmus_log /proc/devices | awk '{print $1}'`
     FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'`
     SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'`
     
-    mknod litmus_log c $LITMUS_LOG_MAJOR 0
     mknod ft_trace   c $FT_TRACE_MAJOR   0
     
     NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1))
@@ -68,7 +68,7 @@ Recording Debug Traces
 
 The `litmus_log` buffer can be read by simply opening the file and reading its contents:
 
-        cat litmus_log > my_debug_log
+        cat /dev/litmus/log > my_debug_log
 
 Kill the `cat` process to stop recording debug messages.
 
@@ -147,7 +147,7 @@ Recording Scheduling Traces
 
 Scheduling traces are also recorded using Feather-Trace. However, a different binary format is used. The definition and an explanation of the format can be found in the file `include/litmus/sched_trace.h` (in the kernel directory).
 
-Since `sched_trace` uses per-processor buffers several `ftcat` instances have to be launched. The `ft_tools` package includes a wrapper script called `st_trace` that automates this setup procedure. Note that one may have to modify `st_trace` to change the default location of the `sched_trace` device files. `st_trace` accepts a tag as the only argument. The tag is used to assign a unique name to the trace files.
+Since `sched_trace` uses per-processor buffers several `ftcat` instances have to be launched. The `ft_tools` package includes a wrapper script called `st_trace` that automates this setup procedure. Note that one may have to modify `st_trace` to change the default location of the `sched_trace` device files and the `ftcat` binary. `st_trace` accepts a tag as the only argument. The tag is used to assign a unique name to the trace files.
 
 The following example illustrates how `st_trace` is used with the tag `global-exp`.
 
@@ -167,24 +167,19 @@ The following example illustrates how `st_trace` is used with the tag `global-ex
         /home/litmus/log2: 1234 bytes read.
         /home/litmus/log3: 1234 bytes read.
 
-Note that `st_trace` may have to be modified to change the default `sched_trace` device locations.
+Note that `st_trace` may have to be modified to change the default `sched_trace` device locations and the `ftcat` binary.
 
 **Hint**: The dummy real-time task `rtspin` (distributed as part of the `liblitmus` package) may be useful when studying/testing the behavior of a scheduler plugin.
 
-Post-Processing Scheduling Traces
----------------------------------
-
-The user space library and tools package `liblitmus` contains the necessary headers to write `sched_trace` post-processing and analysis tools (see `include/sched_trace.h` and `src/sched_trace.c`).
-
-The tool `showst` (distributed as part of `liblitmus`) can be used to inspect the binary traces recorded with `st_trace` and may provide a good starting point for the development of custom analysis tools.
+Recorded scheduling traces can be analyzed with [Unit-Trace](http://cs.unc.edu/~mollison/unit-trace). Alternatively,  the user space library and tools package `liblitmus` contains the necessary headers to write `sched_trace` post-processing and analysis tools (see `include/sched_trace.h` and `src/sched_trace.c`).
 
 Concluding Remarks
 ------------------
 
-At this point we only offer data *acquisition* tools since we have not yet had the time to develop release-quality *analysis* tools. **Patches that improve the existing tools and contributions of new analysis and visualization tools are very much welcome!**
-
 For any questions please contact the current LITMUS<sup>RT</sup> maintainer (as indicated on the [LITMUS<sup>RT</sup> homepage](../index.html#collaborators)).
 
 Change History
 --------------
 - Initially written by <a href="http://www.cs.unc.edu/~bbb">Bjoern B. Brandenburg</a> (bbb at cs.unc.edu) on 12/09/2008.
+- Updated for LITMUS<sup>RT</sup> version 2010.2 by <a href="http://www.cs.unc.edu/~mollison">Mac Mollison</a> (mollison at cs.unc.edu) on 11/08/2010.
+