summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--doc/tracing.html25
-rw-r--r--doc/tracing.txt27
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
37This document is part of the documentation of the <a href="../index.html">LITMUS<sup>RT</sup> project</a>. 37This document is part of the documentation of the <a href="../index.html">LITMUS<sup>RT</sup> project</a>.
38</div> 38</div>
39 39
40<p>As of version 2008.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:</p> 40<p>As of version 2010.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:</p>
41 41
42<ol> 42<ol>
43<li><p><code>litmus_log</code>: This trace contains text messages (created with the <code>TRACE()</code> 43<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.
49 49
50<h2>Accessing Trace Buffers</h2> 50<h2>Accessing Trace Buffers</h2>
51 51
52<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> 52<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>
53 53
54<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> 54<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>
55
56<p>Thus, device files for <code>ft_trace</code> and <code>sched_trace</code> can be created with the following script.</p>
55 57
56<pre><code>#!/bin/bash 58<pre><code>#!/bin/bash
57 59
58LITMUS_LOG_MAJOR=`grep litmus_log /proc/devices | awk '{print $1}'`
59FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'` 60FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'`
60SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'` 61SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'`
61 62
62mknod litmus_log c $LITMUS_LOG_MAJOR 0
63mknod ft_trace c $FT_TRACE_MAJOR 0 63mknod ft_trace c $FT_TRACE_MAJOR 0
64 64
65NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1)) 65NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1))
@@ -76,7 +76,7 @@ done
76 76
77<p>The <code>litmus_log</code> 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>
78 78
79<pre><code>cat litmus_log &gt; my_debug_log 79<pre><code>cat /dev/litmus/log &gt; my_debug_log
80</code></pre> 80</code></pre>
81 81
82<p>Kill the <code>cat</code> process to stop recording debug messages.</p> 82<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.
160 160
161<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> 161<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>
162 162
163<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> 163<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>
164 164
165<p>The following example illustrates how <code>st_trace</code> is used with the tag <code>global-exp</code>.</p> 165<p>The following example illustrates how <code>st_trace</code> is used with the tag <code>global-exp</code>.</p>
166 166
@@ -181,26 +181,21 @@ Disabling 9 events.
181/home/litmus/log3: 1234 bytes read. 181/home/litmus/log3: 1234 bytes read.
182</code></pre> 182</code></pre>
183 183
184<p>Note that <code>st_trace</code> may have to be modified to change the default <code>sched_trace</code> device locations.</p> 184<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>
185 185
186<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> 186<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>
187 187
188<h2>Post-Processing Scheduling Traces</h2> 188<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>
189
190<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>
191
192<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>
193 189
194<h2>Concluding Remarks</h2> 190<h2>Concluding Remarks</h2>
195 191
196<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>
197
198<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> 192<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>
199 193
200<h2>Change History</h2> 194<h2>Change History</h2>
201 195
202<ul> 196<ul>
203<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> 197<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>
198<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>
204</ul> 199</ul>
205<script src="http://www.google-analytics.com/urchin.js" type="text/javascript"> 200<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
206</script> 201</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>
28This document is part of the documentation of the <a href="../index.html">LITMUS<sup>RT</sup> project</a>. 28This document is part of the documentation of the <a href="../index.html">LITMUS<sup>RT</sup> project</a>.
29</div> 29</div>
30 30
31As of version 2008.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>: 31As of version 2010.2, there are three tracing mechanisms available in LITMUS<sup>RT</sup>:
32 32
331. `litmus_log`: This trace contains text messages (created with the `TRACE()` 331. `litmus_log`: This trace contains text messages (created with the `TRACE()`
34macro, see `litmus.h`) that convey information useful for debugging. There is one global 34macro, 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
41Accessing Trace Buffers 41Accessing Trace Buffers
42----------------------- 42-----------------------
43 43
44Currently, 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. 44`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.
45 45
46The per-processor buffers are accessible via the minor numbers of the drivers. Hence, proper device files can be created with the following script. 46The 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.
47
48Thus, device files for `ft_trace` and `sched_trace` can be created with the following script.
47 49
48 #!/bin/bash 50 #!/bin/bash
49 51
50 LITMUS_LOG_MAJOR=`grep litmus_log /proc/devices | awk '{print $1}'`
51 FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'` 52 FT_TRACE_MAJOR=`grep ft_trace /proc/devices | awk '{print $1}'`
52 SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'` 53 SCHED_TRACE_MAJOR=`grep sched_trace /proc/devices | awk '{print $1}'`
53 54
54 mknod litmus_log c $LITMUS_LOG_MAJOR 0
55 mknod ft_trace c $FT_TRACE_MAJOR 0 55 mknod ft_trace c $FT_TRACE_MAJOR 0
56 56
57 NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1)) 57 NUM_PROCS=$((`grep 'processor' /proc/cpuinfo | wc -l` - 1))
@@ -68,7 +68,7 @@ Recording Debug Traces
68 68
69The `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:
70 70
71 cat litmus_log > my_debug_log 71 cat /dev/litmus/log > my_debug_log
72 72
73Kill the `cat` process to stop recording debug messages. 73Kill the `cat` process to stop recording debug messages.
74 74
@@ -147,7 +147,7 @@ Recording Scheduling Traces
147 147
148Scheduling 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). 148Scheduling 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).
149 149
150Since `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. 150Since `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.
151 151
152The following example illustrates how `st_trace` is used with the tag `global-exp`. 152The following example illustrates how `st_trace` is used with the tag `global-exp`.
153 153
@@ -167,24 +167,19 @@ The following example illustrates how `st_trace` is used with the tag `global-ex
167 /home/litmus/log2: 1234 bytes read. 167 /home/litmus/log2: 1234 bytes read.
168 /home/litmus/log3: 1234 bytes read. 168 /home/litmus/log3: 1234 bytes read.
169 169
170Note that `st_trace` may have to be modified to change the default `sched_trace` device locations. 170Note that `st_trace` may have to be modified to change the default `sched_trace` device locations and the `ftcat` binary.
171 171
172**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. 172**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.
173 173
174Post-Processing Scheduling Traces 174Recorded 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`).
175---------------------------------
176
177The 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`).
178
179The 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.
180 175
181Concluding Remarks 176Concluding Remarks
182------------------ 177------------------
183 178
184At 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!**
185
186For any questions please contact the current LITMUS<sup>RT</sup> maintainer (as indicated on the [LITMUS<sup>RT</sup> homepage](../index.html#collaborators)). 179For any questions please contact the current LITMUS<sup>RT</sup> maintainer (as indicated on the [LITMUS<sup>RT</sup> homepage](../index.html#collaborators)).
187 180
188Change History 181Change History
189-------------- 182--------------
190- Initially written by <a href="http://www.cs.unc.edu/~bbb">Bjoern B. Brandenburg</a> (bbb at cs.unc.edu) on 12/09/2008. 183- Initially written by <a href="http://www.cs.unc.edu/~bbb">Bjoern B. Brandenburg</a> (bbb at cs.unc.edu) on 12/09/2008.
184- 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.
185
generated by cgit v1.2.2 (git 2.25.0) at 2025-03-21 09:24:13 -0400