From 6fdbd51c6661dc513c12ac7ce5860e00444b6d3e Mon Sep 17 00:00:00 2001 From: Bjoern Brandenburg Date: Tue, 9 Dec 2008 16:32:38 +0100 Subject: first nice-looking documentation --- doc/Makefile | 3 +-- doc/gen_html.sh | 2 +- doc/tracing.html | 74 +++++++++++++++++++++++++++++++++++----------------- doc/tracing.text | 79 +++++++++++++++++++++++++++++++++++++++----------------- 4 files changed, 109 insertions(+), 49 deletions(-) (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile index ebe8c3a..9806c33 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,6 +7,5 @@ all: ${DOCS} clean: rm -f ${DOCS} -%.html: %.text - echo $$PWD +%.html: %.text gen_html.sh ./gen_html.sh $< > $@ diff --git a/doc/gen_html.sh b/doc/gen_html.sh index 62d4490..d14b679 100755 --- a/doc/gen_html.sh +++ b/doc/gen_html.sh @@ -26,7 +26,7 @@ cat < - + $TITLE diff --git a/doc/tracing.html b/doc/tracing.html index 679457f..ba5b4e3 100644 --- a/doc/tracing.html +++ b/doc/tracing.html @@ -4,7 +4,7 @@ - + Tracing with LITMUS^RT @@ -33,43 +33,71 @@ TITLE=Tracing with LITMUS^RT

Tracing with LITMUSRT

-

There are three kind of traces in LITMUS^RT:

+
+This document is part of the documentation of the LITMUSRT project.
+Written by Bjoern B. Brandenburg (bbb at cs.unc.edu) on 12/09/2008. +
+ +

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

    -

  1. litmus_log: This trace contains text messages (created with the TRACE() macro) that convey information useful for debugging. Enabling this trace (at compile time) incurs high overheads. There is one global litmus_log buffer for the whole system.

    2. -

  2. ft_trace: This trace contains binary-encoded time stamps. It is used for overhead tracing. There is one ft_trace buffer per processor. The "ft" stands for Feather-Trace.

    3. -

  3. sched_trace: This trace contains binary-encoded scheduling event information, e.g., a task got scheduled, a job was released, a job completed, etc. There is one sched_trace buffer per processor.

    4. +

  4. 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 +litmus_log buffer for the whole system. Debug tracing must be enabled at compile time. Note that debug tracing creates significant overhead because string formatting takes place.

    5. +

  5. ft_trace: This trace contains binary-encoded time stamps. It is used for overhead tracing. There is one ft_trace buffer per processor. The "ft" stands for Feather-Trace. Feather-Trace is designed to create only negligible overhead when event sources are disabled, and to incur only low overhead when recording time stamps.

    6. +

  6. sched_trace: This trace contains binary-encoded scheduling event information, e.g., an event can be recorded whenever a task got scheduled, a job was released, a job completed, etc. There is one sched_trace buffer per processor. sched_trace is also based on Feather-Trace and hence incurs only neglible overhead when event sources are disabled.

-

Currently, all three traces are exported through character device drivers. You can find out the major numbers for the drivers by looking at /proc/devices. Usually, the major numbers should be 251, 252, and 253 respectively.

+

Accessing Trace Buffers

+ +

Currently, all three traces are exported to user space through character device drivers. You can discover the major numbers allocated by the drivers by looking at /proc/devices. Usually, the major numbers are 251, 252, and 253 respectively.

-

The per-processor buffers are accessible via the minor numbers of the drivers. Hence, you can create the trace devices as follows:

+

The per-processor buffers are accessible via the minor numbers of the drivers. Hence, proper device files can be created with the following script.

-

---[snip]--- - #!/bin/bash

+
#!/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}'

+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}'`
 
-
NUM_PROCS=$((grep 'processor' /proc/cpuinfo | wc -l - 1))

+NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1))
+
+mknod litmus_log c $LITMUS_LOG_MAJOR 0
+for P in `seq 0 $NUM_PROCS`
+do
+    mknod "ft_trace$P"    c  $FT_TRACE_MAJOR     $P
+    mknod "sched_trace$P" c  $SCHED_TRACE_MAJOR  $P
+done
+
-

mknod litmus_log c $LITMUS_LOG_MAJOR 0 - for P in seq 0 $NUM_PROCS - do - mknod "ft_trace$P" c $FT_TRACE_MAJOR $P - mknod "sched_trace$P" c $SCHED_TRACE_MAJOR $P - done ----[snap]---

+

Alternatively, you can setup udev rules to create the devices on demand. This, however, is beyond the scope of this document.

-

Alternatively, you can setup udev rules to create the devices on demand.

+

Recording Debug Traces

-

The litmus_log buffer can be read by simply opening the file and reading its contents:

+

The litmus_log buffer can be read by simply opening the file and reading its contents:

cat litmus_log > my_debug_log
-

The other files only produce output after events have been enabled. I yet have to release the tool to enable events, but hope to do so later today.

+

Kill the cat process to stop recording debug messages. No post-processing is required since the debug messages are plain text.

+ +

Hint: You can use netcat to send the debug messages to another machine via UDP to avoid filesystem activity.

+ +

Recording Overhead Traces

+ +

to be written

+ +

Post-Processing Overhead Traces

+ +

to be written

+ +

Recording Scheduling Traces

+ +

to be written

+ +

Post-Processing Overhead Traces

+ +

to be written