From 2231847a582cc8cff3679aff63fcc97188ca8b7c Mon Sep 17 00:00:00 2001 From: Bjoern Brandenburg Date: Tue, 9 Dec 2008 15:20:36 +0100 Subject: Started work on Documentation --- doc/Makefile | 12 +++++++++ doc/gen_html.sh | 46 ++++++++++++++++++++++++++++++++ doc/tracing.html | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/tracing.text | 62 +++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 200 insertions(+) create mode 100644 doc/Makefile create mode 100755 doc/gen_html.sh create mode 100644 doc/tracing.html create mode 100644 doc/tracing.text (limited to 'doc') diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..ebe8c3a --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,12 @@ +SHELL=/bin/bash + +DOCS=tracing.html + +all: ${DOCS} + +clean: + rm -f ${DOCS} + +%.html: %.text + echo $$PWD + ./gen_html.sh $< > $@ diff --git a/doc/gen_html.sh b/doc/gen_html.sh new file mode 100755 index 0000000..62d4490 --- /dev/null +++ b/doc/gen_html.sh @@ -0,0 +1,46 @@ +#!/bin/bash + +function die { + echo "Error:" $* + exit 1 +} + +TITLE=$2 +FILE=$1 + + +[ -z "$FILE" ] && die "File missing!" + +# extract title from file if missing +[ -z "$TITLE" ] && TITLE=`sed -e '/^TITLE=$.*$/!d' -e 's/^TITLE=$.*$/\1/' $FILE` +# if no title specified used file name +[ -z "$TITLE" ] && TITLE=$FILE + +# check environment for markdown binary +[ -z "$MARKDOWN" ] && MARKDOWN=markdown2 + +cat < + + + + + + + $TITLE + + +EOF + +$MARKDOWN --extra code-friendly "$FILE" + +cat < + + + + +EOF diff --git a/doc/tracing.html b/doc/tracing.html new file mode 100644 index 0000000..679457f --- /dev/null +++ b/doc/tracing.html @@ -0,0 +1,80 @@ + + + + + + + + Tracing with LITMUS^RT + + + + + + +

Tracing with LITMUS^RT

+ +

There are three kind of traces in LITMUS^RT:

+ +

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.
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.
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.

+ +

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.

+ +

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

+ +

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

+ +

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 +---[snap]---

+ +

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

+ +

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.

+ + + + diff --git a/doc/tracing.text b/doc/tracing.text new file mode 100644 index 0000000..ecd641a --- /dev/null +++ b/doc/tracing.text @@ -0,0 +1,62 @@ + + + + +Tracing with LITMUS^RT +================================ + +There are three kind of traces in LITMUS^RT: + +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. 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. 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. + +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. + +The per-processor buffers are accessible via the minor numbers of the drivers. Hence, you can create the trace devices as follows: + +---[snip]--- + #!/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}'` + + 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 +---[snap]--- + +Alternatively, you can setup udev rules to create the devices on demand. + +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. -- cgit v1.2.2

Tracing with LITMUSRT

Tracing with LITMUS^RT