summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBjoern Brandenburg <bbb@Serenity.local>2008-12-09 10:32:38 -0500
committerBjoern Brandenburg <bbb@Serenity.local>2008-12-09 10:32:38 -0500
commit6fdbd51c6661dc513c12ac7ce5860e00444b6d3e (patch)
tree01a2ca9cc32b7bb26f4ab1ff3ce6c8e7105dc3f7
parent2231847a582cc8cff3679aff63fcc97188ca8b7c (diff)
first nice-looking documentation
Diffstat
-rw-r--r--doc/Makefile3
-rwxr-xr-xdoc/gen_html.sh2
-rw-r--r--doc/tracing.html74
-rw-r--r--doc/tracing.text79
-rw-r--r--inc/format-doc.css122
5 files changed, 231 insertions, 49 deletions
diff --git a/doc/Makefile b/doc/Makefile
index ebe8c3a..9806c33 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -7,6 +7,5 @@ all: ${DOCS}
7clean: 7clean:
8 rm -f ${DOCS} 8 rm -f ${DOCS}
9 9
10%.html: %.text 10%.html: %.text gen_html.sh
11 echo $$PWD
12 ./gen_html.sh $< > $@ 11 ./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 <<EOF
26 <head> 26 <head>
27 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> 27 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
28 <meta name="verify-v1" content="pZNmf5XyUUfAPdlSPbFSavMUsLgVsmBYOXzOhbIy2gw=" /> 28 <meta name="verify-v1" content="pZNmf5XyUUfAPdlSPbFSavMUsLgVsmBYOXzOhbIy2gw=" />
29 <link rel="stylesheet" type="text/css" href="../inc/format.css"/> 29 <link rel="stylesheet" type="text/css" href="../inc/format-doc.css"/>
30 <title>$TITLE</title> 30 <title>$TITLE</title>
31 </head> 31 </head>
32 <body> 32 <body>
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 @@
4 <head> 4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
6 <meta name="verify-v1" content="pZNmf5XyUUfAPdlSPbFSavMUsLgVsmBYOXzOhbIy2gw=" /> 6 <meta name="verify-v1" content="pZNmf5XyUUfAPdlSPbFSavMUsLgVsmBYOXzOhbIy2gw=" />
7 <link rel="stylesheet" type="text/css" href="../inc/format.css"/> 7 <link rel="stylesheet" type="text/css" href="../inc/format-doc.css"/>
8 <title>Tracing with LITMUS^RT</title> 8 <title>Tracing with LITMUS^RT</title>
9 </head> 9 </head>
10 <body> 10 <body>
@@ -33,43 +33,71 @@ TITLE=Tracing with LITMUS^RT
33 33
34<h1>Tracing with LITMUS<sup>RT</sup></h1> 34<h1>Tracing with LITMUS<sup>RT</sup></h1>
35 35
36<p>There are three kind of traces in LITMUS^RT:</p> 36<div class="preamble">
37This document is part of the documentation of the <a href="../index.html">LITMUS<sup>RT</sup> project</a>. <br/>
38Written by Bjoern B. Brandenburg (bbb at cs.unc.edu) on 12/09/2008.
39</div>
40
41<p>As of version 2008.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:</p>
37 42
38<ol> 43<ol>
39<li><p>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.</p></li> 44<li><p><code>litmus_log</code>: This trace contains text messages (created with the <code>TRACE()</code>
40<li><p>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.</p></li> 45macro, see <code>litmus.h</code>) that convey information useful for debugging. There is one global
41<li><p>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.</p></li> 46<code>litmus_log</code> 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.</p></li>
47<li><p><code>ft_trace</code>: This trace contains binary-encoded time stamps. It is used for overhead tracing. There is one <code>ft_trace</code> buffer per processor. The "ft" stands for <a href="http://www.cs.unc.edu/~bbb/feather-trace">Feather-Trace</a>. Feather-Trace is designed to create only negligible overhead when event sources are disabled, and to incur only low overhead when recording time stamps.</p></li>
48<li><p><code>sched_trace</code>: This trace contains binary-encoded scheduling event information, <em>e.g.</em>, an event can be recorded whenever a task got scheduled, a job was released, a job completed, etc. There is one <code>sched_trace</code> buffer per processor. <code>sched_trace</code> is also based on Feather-Trace and hence incurs only neglible overhead when event sources are disabled.</p></li>
42</ol> 49</ol>
43 50
44<p>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.</p> 51<h2>Accessing Trace Buffers</h2>
52
53<p>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 <code>/proc/devices</code>. Usually, the major numbers are 251, 252, and 253 respectively.</p>
45 54
46<p>The per-processor buffers are accessible via the minor numbers of the drivers. Hence, you can create the trace devices as follows:</p> 55<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>
47 56
48<p>---[snip]--- 57<pre><code>#!/bin/bash
49 #!/bin/bash</p>
50 58
51<p>LITMUS_LOG_MAJOR=<code>grep litmus_log /proc/devices | awk '{print $1}'</code> 59LITMUS_LOG_MAJOR=`grep litmus_log /proc/devices | awk '{print $1}'`
52 FT_TRACE_MAJOR=<code>grep ft_trace /proc/devices | awk '{print $1}'</code> 60FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'`
53 SCHED_TRACE_MAJOR=<code>grep sched_trace /proc/devices | awk '{print $1}'</code></p> 61SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'`
54 62
55<p>NUM_PROCS=$((<code>grep 'processor' /proc/cpuinfo | wc -l</code> - 1))</p> 63NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1))
64
65mknod litmus_log c $LITMUS_LOG_MAJOR 0
66for P in `seq 0 $NUM_PROCS`
67do
68 mknod "ft_trace$P" c $FT_TRACE_MAJOR $P
69 mknod "sched_trace$P" c $SCHED_TRACE_MAJOR $P
70done
71</code></pre>
56 72
57<p>mknod litmus_log c $LITMUS_LOG_MAJOR 0 73<p>Alternatively, you can setup <code>udev</code> rules to create the devices on demand. This, however, is beyond the scope of this document.</p>
58 for P in <code>seq 0 $NUM_PROCS</code>
59 do
60 mknod "ft_trace$P" c $FT_TRACE_MAJOR $P
61 mknod "sched_trace$P" c $SCHED_TRACE_MAJOR $P
62 done
63---[snap]---</p>
64 74
65<p>Alternatively, you can setup udev rules to create the devices on demand.</p> 75<h2>Recording Debug Traces</h2>
66 76
67<p>The litmus_log buffer can be read by simply opening the file and reading its contents:</p> 77<p>The <code>litmus_log</code> buffer can be read by simply opening the file and reading its contents:</p>
68 78
69<pre><code>cat litmus_log &gt; my_debug_log 79<pre><code>cat litmus_log &gt; my_debug_log
70</code></pre> 80</code></pre>
71 81
72<p>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.</p> 82<p>Kill the <code>cat</code> process to stop recording debug messages. No post-processing is required since the debug messages are plain text.</p>
83
84<p><strong>Hint</strong>: You can use <code>netcat</code> to send the debug messages to another machine via UDP to avoid filesystem activity.</p>
85
86<h2>Recording Overhead Traces</h2>
87
88<p><em>to be written</em></p>
89
90<h2>Post-Processing Overhead Traces</h2>
91
92<p><em>to be written</em></p>
93
94<h2>Recording Scheduling Traces</h2>
95
96<p><em>to be written</em></p>
97
98<h2>Post-Processing Overhead Traces</h2>
99
100<p><em>to be written</em></p>
73<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"> 101<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
74</script> 102</script>
75<script type="text/javascript"> 103<script type="text/javascript">
diff --git a/doc/tracing.text b/doc/tracing.text
index ecd641a..45df216 100644
--- a/doc/tracing.text
+++ b/doc/tracing.text
@@ -24,39 +24,72 @@ TITLE=Tracing with LITMUS^RT
24Tracing with LITMUS<sup>RT</sup> 24Tracing with LITMUS<sup>RT</sup>
25================================ 25================================
26 26
27There are three kind of traces in LITMUS^RT: 27<div class="preamble">
28This document is part of the documentation of the <a href="../index.html">LITMUS<sup>RT</sup> project</a>. <br/>
29Written by Bjoern B. Brandenburg (bbb at cs.unc.edu) on 12/09/2008.
30</div>
28 31
291. 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. 32As of version 2008.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:
30 33
312. 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. 341. `litmus_log`: This trace contains text messages (created with the `TRACE()`
35macro, see `litmus.h`) that convey information useful for debugging. There is one global
36`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.
32 37
333. 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. 382. `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](http://www.cs.unc.edu/~bbb/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.
34 39
35Currently, 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. 403. `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.
36 41
37The per-processor buffers are accessible via the minor numbers of the drivers. Hence, you can create the trace devices as follows: 42Accessing Trace Buffers
43-----------------------
38 44
39---[snip]--- 45Currently, 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.
40 #!/bin/bash
41 46
42 LITMUS_LOG_MAJOR=`grep litmus_log /proc/devices | awk '{print $1}'` 47The per-processor buffers are accessible via the minor numbers of the drivers. Hence, proper device files can be created with the following script.
43 FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'`
44 SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'`
45 48
46 NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1)) 49 #!/bin/bash
50
51 LITMUS_LOG_MAJOR=`grep litmus_log /proc/devices | awk '{print $1}'`
52 FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'`
53 SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'`
54
55 NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1))
56
57 mknod litmus_log c $LITMUS_LOG_MAJOR 0
58 for P in `seq 0 $NUM_PROCS`
59 do
60 mknod "ft_trace$P" c $FT_TRACE_MAJOR $P
61 mknod "sched_trace$P" c $SCHED_TRACE_MAJOR $P
62 done
47 63
48 mknod litmus_log c $LITMUS_LOG_MAJOR 0 64Alternatively, you can setup `udev` rules to create the devices on demand. This, however, is beyond the scope of this document.
49 for P in `seq 0 $NUM_PROCS`
50 do
51 mknod "ft_trace$P" c $FT_TRACE_MAJOR $P
52 mknod "sched_trace$P" c $SCHED_TRACE_MAJOR $P
53 done
54---[snap]---
55 65
56Alternatively, you can setup udev rules to create the devices on demand. 66Recording Debug Traces
67----------------------
57 68
58The litmus_log buffer can be read by simply opening the file and reading its contents: 69The `litmus_log` buffer can be read by simply opening the file and reading its contents:
59 70
60 cat litmus_log > my_debug_log 71 cat litmus_log > my_debug_log
61 72
62The 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. 73Kill the `cat` process to stop recording debug messages. No post-processing is required since the debug messages are plain text.
74
75**Hint**: You can use `netcat` to send the debug messages to another machine via UDP to avoid filesystem activity.
76
77Recording Overhead Traces
78-------------------------
79
80*to be written*
81
82Post-Processing Overhead Traces
83-------------------------------
84
85*to be written*
86
87Recording Scheduling Traces
88---------------------------
89
90*to be written*
91
92Post-Processing Overhead Traces
93-------------------------------
94
95*to be written*
diff --git a/inc/format-doc.css b/inc/format-doc.css
new file mode 100644
index 0000000..72c64e9
--- /dev/null
+++ b/inc/format-doc.css
@@ -0,0 +1,122 @@
1html {
2 background-color : #EFEBE7;
3 font-family : Arial, Helvetica, sans-serif;
4 margin-bottom : 0px;
5 margin-left : 0px;
6 margin-right : 0px;
7 margin-top : 0px;
8 padding-bottom : 0px;
9 padding-left : 0px;
10 padding-right : 0px;
11 padding-top : 0px;
12 }
13
14
15body {
16 background-position : top right;
17 background-repeat : no-repeat;
18
19 margin-top: 0px;
20 margin-bottom: 0px;
21 margin-right: 0px;
22 margin-left: 0px;
23 margin: 0px 0px 0px 0px;
24 padding-top: 1cm;
25 padding-bottom: 1cm;
26 padding-right: 1cm;
27 padding-left: 1cm;
28 }
29
30img {
31 border: 0px;
32}
33
34p {
35 font-size: 12pt;
36 }
37
38.alertbox {
39 border-color: red;
40 border-width: 2px;
41 border-style: solid;
42 padding: 0.1in;
43 margin-left: 1in;
44 margin-right: 1in;
45 margin-bottom: 0.5in;
46 background-color: #ffffff;
47}
48
49.box {
50 width: 8.5in;
51 padding-top: 0.1in;
52 padding-bottom: 0.1in;
53 padding-right: 0.1in;
54 padding-left: 0.1in;
55 margin-bottom: 1cm;
56 background-color: #ffffff;
57 margin-left: 1cm;
58 border-color: #afafaf;
59 border-width: 2px;
60 border-style: dashed;
61 }
62
63
64.boxsize {
65 width: 8.5in;
66 margin-top: 0cm;
67 margin-left: 1cm;
68 }
69
70
71a {
72// color: #47733c;
73 color: #6fb45e;
74 font-weight: bold;
75 text-decoration: underline;
76 }
77
78
79a:hover {
80 color: #d66836;
81 font-weight: bold;
82 }
83
84h1 {
85 text-align: center;
86 font: small-caps 34pt Georgia, "Times New Roman", Times, serif;
87}
88
89h2 {
90 font: normal normal 18pt Georgia, "Times New Roman", Times, serif;
91}
92
93.relname {
94 color: #eb4f0c;
95 margin-left: 0.25in;
96 font: italic 16pt Georgia, "Times New Roman", Times, serif;
97}
98
99.indented {
100 margin-left: 1.0cm;
101 }
102
103code {
104 font-family: Courier, monospace;
105}
106
107pre {
108 margin-left: 0.5cm;
109 margin-right: 0.5cm;
110 padding: 0.2cm;
111 background-color: #000000;
112 color: #cccccc;
113 border: 2px solid #eb4f0c;
114 font: 10pt "Courier New", Courier, mono;
115 overflow: auto;
116}
117
118.preamble {
119 text-align: center;
120 font-style: italic;
121 margin: 0.75cm;
122}
generated by cgit v1.2.2 (git 2.25.0) at 2025-03-20 17:50:23 -0400