From 670ae348b73cb154ee76df4f6150d9d03b31ff03 Mon Sep 17 00:00:00 2001 From: Mac Mollison Date: Mon, 8 Nov 2010 12:35:18 -0500 Subject: Updated tracing page for 2010.2 - litmus_log now available as /dev/litmus/log - Unit-Trace now available - Other minor fixes to the page --- doc/tracing.html | 25 ++++++++++--------------- doc/tracing.txt | 27 +++++++++++---------------- 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 LITMUSRT project. -

As of version 2008.2, there are three tracing mechanisms available in LITMUSRT:

+

As of version 2010.2, there are three tracing mechanisms available in LITMUSRT:

  1. litmus_log: This trace contains text messages (created with the TRACE() @@ -49,17 +49,17 @@ macro, see litmus.h) that convey information useful for debugging.

    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))
@@ -76,7 +76,7 @@ done
 
 
    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.
    
@@ -160,7 +160,7 @@ Used to measure the time spent to enqueue a newly-released job in a ready queue.
 
 
    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.
    
 
@@ -181,26 +181,21 @@ Disabling 9 events.
 /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. 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 LITMUSRT maintainer (as indicated on the LITMUSRT homepage).
    
 
 
    Change History
    
 
 
      
 
    • Initially written by Bjoern B. Brandenburg (bbb at cs.unc.edu) on 12/09/2008.
      • 
+
    • Updated for LITMUSRT version 2010.2 by Mac Mollison (mollison at cs.unc.edu) on 11/08/2010.
      • 
 
    
 
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 LITMUSRT
 This document is part of the documentation of the LITMUSRT project.
 
 
-As of version 2008.2, there are three tracing mechanisms available in LITMUSRT:
+As of version 2010.2, there are three tracing mechanisms available in LITMUSRT:
 
 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 LITMUSRT maintainer (as indicated on the [LITMUSRT homepage](../index.html#collaborators)).
 
 Change History
 --------------
 - Initially written by Bjoern B. Brandenburg (bbb at cs.unc.edu) on 12/09/2008.
+- Updated for LITMUSRT version 2010.2 by Mac Mollison (mollison at cs.unc.edu) on 11/08/2010.
+
-- 
cgit v1.2.2