summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorGary Bressler <garybressler@nc.rr.com>2010-04-27 14:07:50 -0400
committerGary Bressler <garybressler@nc.rr.com>2010-04-27 14:07:50 -0400
commit9fcc1ebd1b764a6f306596a5bd9cd7b0bd6eb1be (patch)
treedbcd292d940005f9785ad4a505a2c5ad03ae0c01
parent62f5f8afb1d2fa48f16c929672f8dd49a0281960 (diff)
parent51e246d367d043913a882080abde3d8bae5ce4d4 (diff)
hopefully fixed conflict
-rw-r--r--doc/index.txt24
-rwxr-xr-xunit-trace27
2 files changed, 26 insertions, 25 deletions
diff --git a/doc/index.txt b/doc/index.txt
index 135579b..600590b 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -31,7 +31,7 @@ Make sure `~/bin` is on your `PATH`.
31 31
32## Using Unit-Trace ## 32## Using Unit-Trace ##
33Command line usage:<br> 33Command line usage:<br>
34<codeblock>unit-trace &lt;one or more trace files&gt; [flags]</codeblock>. 34<codeblock>unit-trace &lt;one or more trace files&gt; [flags]</codeblock>.
35 35
36Each flag turns on or off a unit-trace submodule. The available submodules are 36Each flag turns on or off a unit-trace submodule. The available submodules are
37given below. 37given below.
@@ -42,7 +42,7 @@ For a quick usage reference (including a list of modules), type `unit-trace` on
42 42
43### Example Use Case ### 43### Example Use Case ###
44Let's assume you're in a directory with a bunch of trace files with 44Let's assume you're in a directory with a bunch of trace files with
45the extension `.bin`. 45the extension `.bin`.
46Each trace file is assumed to be the trace of a single CPU, and all trace files in the directory are from the same experimental run. 46Each trace file is assumed to be the trace of a single CPU, and all trace files in the directory are from the same experimental run.
47(The sample_traces directory, included with Unit Trace, will work for this example.) 47(The sample_traces directory, included with Unit Trace, will work for this example.)
48 48
@@ -80,7 +80,7 @@ Some submodules have further documentation, appearing later in this document.
80 80
81### Input Submodules ### 81### Input Submodules ###
82<table border=1> 82<table border=1>
83<tr><td>Name</td><td>Flag</td><td>Parameters</td><td>Description</td></tr> 83<tr><th>Name</th><th>Flag</th><th>Parameters</th><th>Description</th></tr>
84<tr> 84<tr>
85<td>trace_parser</td> 85<td>trace_parser</td>
86<td>always on, unless/until modules for other trace formats are contributed</td> 86<td>always on, unless/until modules for other trace formats are contributed</td>
@@ -88,7 +88,7 @@ Some submodules have further documentation, appearing later in this document.
88</table> 88</table>
89### Filter Submodules ### 89### Filter Submodules ###
90<table border=1> 90<table border=1>
91<tr><td>Name</td><td>Flag</td><td>Parameters</td><td>Description</td></tr> 91<tr><th>Name</th><th>Flag</th><th>Parameters</th><th>Description</th></tr>
92<tr><td>earliest</td><td>-e</td><td>time</td><td>Filters out records before the given event ID. (Event IDs are assigned in order of event record timestamp, and are displayed by the `stdio_printer` submodule.)</td></tr> 92<tr><td>earliest</td><td>-e</td><td>time</td><td>Filters out records before the given event ID. (Event IDs are assigned in order of event record timestamp, and are displayed by the `stdio_printer` submodule.)</td></tr>
93<tr><td>latest</td><td>-l</td><td>time</td><td>Filters out records after the given event ID.</td></tr> 93<tr><td>latest</td><td>-l</td><td>time</td><td>Filters out records after the given event ID.</td></tr>
94<tr><td>skipper</td><td>-s</td><td>number n</td><td>Skips the first n records</td></tr> 94<tr><td>skipper</td><td>-s</td><td>number n</td><td>Skips the first n records</td></tr>
@@ -97,24 +97,26 @@ Some submodules have further documentation, appearing later in this document.
97</table> 97</table>
98### Test Submodules ### 98### Test Submodules ###
99<table border=1> 99<table border=1>
100<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr> 100<tr><th>Name</th><th>Flag</th><th>Options</th><th>Description</th></tr>
101<tr><td>gedf_test</td><td>-g</td><td>(None)</td><td>Performs G-EDF testing.</td></tr> 101<tr><td>gedf_test</td><td>-g</td><td>(None)</td><td>Performs G-EDF testing.</td></tr>
102</table> 102</table>
103### Output Submodules ### 103### Output Submodules ###
104<table border=1> 104<table border=1>
105<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr> 105<tr><th>Name</th><th>Flag</th><th>Options</th><th>Description</th></tr>
106<tr><td>stdout_printer</td><td>-o</td><td>(None)</td><td>Prints records to standard out. You should probably redirect the output to a file when you use this.</td></tr> 106<tr><td>stdout_printer</td><td>-o</td><td>(None)</td><td>Prints records to standard out. You should probably redirect the output to a file when you use this.</td></tr>
107<tr><td>visualizer</td><td>-v</td><td>(None)</td><td>Visualizes records. You should probably use filters in conjunction with this submodule. Otherwise, it'll take forever to render, and do you <i>really</i> want to visualize the <i>entire</i> trace, anyway?</td></tr> 107<tr><td>visualizer</td><td>-v</td><td>(None)</td><td>Visualizes records. You should probably use filters in conjunction with this submodule. Otherwise, it'll take forever to render, and do you <i>really</i> want to visualize the <i>entire</i> trace, anyway?</td></tr>
108<tr><td>gedf_inversion_stat_printer</td><td>-i</td><td>number n</td><td>Outputs statistics about G-EDF inversions, and the n longest inversions. (You can specify n as 0 if you want.)</td></tr> 108<tr><td>gedf_inversion_stat_printer</td><td>-i</td><td>number n</td><td>Outputs statistics about G-EDF inversions, and the n longest inversions. (You can specify n as 0 if you want.)</td></tr>
109</table> 109</table>
110### Miscellaneous Submodules ### 110### Miscellaneous Submodules ###
111<table border=1> 111<table border=1>
112<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr> 112<tr><th>Name</th><th>Flag</th><th>Options</th><th>Description</th></tr>
113<tr><td>progress</td><td>-p</td><td>(None)</td><td>Outputs progress info (e.g number of records parsed so far, total time to process trace) to std error.</td></tr> 113<tr><td>progress</td><td>-p</td><td>(None)</td><td>Outputs progress info (e.g number of records parsed so far, total time to process trace) to std error.</td></tr>
114</table> 114</table>
115 115
116## Specific Submodule Documentation ## 116## Specific Submodule Documentation ##
117 117
118If you want to learn more about specific submodules, you are looking in the right place.
119
118### The Visualizer Module ### 120### The Visualizer Module ###
119 121
120The visualizer can give you an on-the-fly visual representation of the input 122The visualizer can give you an on-the-fly visual representation of the input
@@ -144,7 +146,7 @@ identifier gives the chronological sequence of events in the input stream
144for the relevant task or CPU. The event symbols are as follows: 146for the relevant task or CPU. The event symbols are as follows:
145 147
146<table border=1> 148<table border=1>
147<tr><td>Symbol Description</td><td>Event Type</td><td>Meaning</td></tr> 149<tr><th>Symbol Description</th><th>Event Type</th><th>Meaning</th></tr>
148<tr><td>Large colored bar</td><td>Scheduled</td><td>A job was scheduled during the period spanned by the bar.</td> 150<tr><td>Large colored bar</td><td>Scheduled</td><td>A job was scheduled during the period spanned by the bar.</td>
149<tr><td>Black triangle</td><td>Suspend (Block)</td><td>A task blocked at this time.</td></tr> 151<tr><td>Black triangle</td><td>Suspend (Block)</td><td>A task blocked at this time.</td></tr>
150<tr><td>White triangle</td><td>Resume (Unblock)</td><td>A task resumed execution at this time.</td></tr> 152<tr><td>White triangle</td><td>Resume (Unblock)</td><td>A task resumed execution at this time.</td></tr>
@@ -155,7 +157,7 @@ attached to the x-axis, as is customary, rather than in a CPU's area.)</td></tr>
155<tr><td>Large down arrow</td><td>Deadline</td><td>A job's deadline occurs at this time. (Appears only in Task Mode.)</td></tr> 157<tr><td>Large down arrow</td><td>Deadline</td><td>A job's deadline occurs at this time. (Appears only in Task Mode.)</td></tr>
156<tr><td>Small down arrow</td><td>Deadline</td><td>A job's deadline occurs at this time. (Appears only in CPU Mode. These appear 158<tr><td>Small down arrow</td><td>Deadline</td><td>A job's deadline occurs at this time. (Appears only in CPU Mode. These appear
157attached to the x-axis, as is customary, rather than in a CPU's area.)</td></tr> 159attached to the x-axis, as is customary, rather than in a CPU's area.)</td></tr>
158<tr><td>Small colored bar</td><td>Priority Inversion</td><td>(Appears only in conjuction with the gedf_test module.) A priority inversion occurred for some task: that is, the task in question <i>should</i> have been scheduled at the depicted time, but wasn't. In Task Mode these are organized by task (and appear gray since color would be redundant), and in CPU mode they appear at the bottom, colored by task.</td></tr> 160<tr><td>Small colored bar</td><td>Priority Inversion</td><td>(Appears only in conjuction with the gedf_test module.) A priority inversion occurred for some task: that is, the task in question <i>should</i> have been scheduled at the depicted time, but wasn't. In Task Mode these are organized by task (and appear gray since color would be redundant), and in CPU mode they appear at the bottom, colored by task.</td></tr>
159</table> 161</table>
160 162
161If you're unsure as 163If you're unsure as
@@ -170,7 +172,7 @@ being scheduled and being descheduled, respectively. <i>However</i>, if the visu
170finds a start event but not an end event (or vice-versa), it assumes that the corresponding 172finds a start event but not an end event (or vice-versa), it assumes that the corresponding
171event occurred, but at a time not in the input stream. 173event occurred, but at a time not in the input stream.
172In other words, it assumes that such events are genuine. To represent this phenomenon, 174In other words, it assumes that such events are genuine. To represent this phenomenon,
173the visualizer shows the bar going "off the graph". 175the visualizer shows the bar going "off the graph".
174 176
175Interacting with the visualizer is easy. The scrollbars work in the obvious way. You can also 177Interacting with the visualizer is easy. The scrollbars work in the obvious way. You can also
176use the arrow keys to move, or use Ctrl+arrow keys to move faster. Mousing over an event gives 178use the arrow keys to move, or use Ctrl+arrow keys to move faster. Mousing over an event gives
@@ -246,7 +248,7 @@ Unit-Trace is released under the [Simplified BSD License][license].
246 248
247## Credits ## 249## Credits ##
248This project was created by and is maintained by the [Real-Time Systems Group][group] at the [University of North Carolina at Chapel Hill][uncch], 250This project was created by and is maintained by the [Real-Time Systems Group][group] at the [University of North Carolina at Chapel Hill][uncch],
249[Department of Computer Science][csdept]. A detailed explanation of the tool is available in [this paper][ospert_paper], from 251[Department of Computer Science][csdept]. A detailed explanation of the tool is available in [this paper][ospert_paper], from
250[the 2009 OSPERT workshop][ospert]. 252[the 2009 OSPERT workshop][ospert].
251 253
252We would like to extend special thanks to Gary Bressler, who created and maintains the `visualizer` submodule as a volunteer with our group. 254We would like to extend special thanks to Gary Bressler, who created and maintains the `visualizer` submodule as a volunteer with our group.
diff --git a/unit-trace b/unit-trace
index c66f5ac..5362113 100755
--- a/unit-trace
+++ b/unit-trace
@@ -9,20 +9,6 @@
9# Setup 9# Setup
10################################################################################ 10################################################################################
11 11
12# Import the modules we need. You should not need to know about
13# their internals.
14import unit_trace
15from unit_trace import trace_reader
16from unit_trace import sanitizer
17from unit_trace import gedf_test
18from unit_trace import gedf_inversion_stat_printer
19from unit_trace import stdout_printer
20from unit_trace import progress
21from unit_trace import skipper
22from unit_trace import maxer
23from unit_trace import earliest
24from unit_trace import latest
25
26# Get trace files from command line arguments 12# Get trace files from command line arguments
27from optparse import OptionParser 13from optparse import OptionParser
28usage = "usage: %prog [options] <one or more trace files>" 14usage = "usage: %prog [options] <one or more trace files>"
@@ -59,36 +45,47 @@ if len(traces) < 1:
59# Pipeline 45# Pipeline
60################################################################################ 46################################################################################
61 47
48# Import the unit_trace module
49import unit_trace
50
62# Read events from traces 51# Read events from traces
52from unit_trace import trace_reader
63stream = trace_reader.trace_reader(traces) 53stream = trace_reader.trace_reader(traces)
64 54
65# Skip over records 55# Skip over records
66if options.skipnum > 0: 56if options.skipnum > 0:
57 from unit_trace import skipper
67 stream = skipper.skipper(stream, options.skipnum) 58 stream = skipper.skipper(stream, options.skipnum)
68 59
69# Enforce max number of records to parse 60# Enforce max number of records to parse
70if options.maxnum > 0: 61if options.maxnum > 0:
62 from unit_trace import maxer
71 stream = maxer.maxer(stream, options.maxnum) 63 stream = maxer.maxer(stream, options.maxnum)
72 64
73# Enfore earliest timestamp 65# Enfore earliest timestamp
74if options.earliest > 0: 66if options.earliest > 0:
67 from unit_trace import earliest
75 stream = earliest.earliest(stream,options.earliest) 68 stream = earliest.earliest(stream,options.earliest)
76 69
77# Enfore latest timestamp 70# Enfore latest timestamp
78if options.latest > 0: 71if options.latest > 0:
72 from unit_trace import latest
79 stream = latest.latest(stream,options.latest) 73 stream = latest.latest(stream,options.latest)
80 74
81# Filter out garbage events 75# Filter out garbage events
82if options.clean is True: 76if options.clean is True:
77 from unit_trace import sanitizer
83 stream = sanitizer.sanitizer(stream) 78 stream = sanitizer.sanitizer(stream)
84 79
85# Display progress information using stderr 80# Display progress information using stderr
86# e.g. # records completed so far, total time, etc. 81# e.g. # records completed so far, total time, etc.
87if options.progress is True: 82if options.progress is True:
83 from unit_trace import progress
88 stream = progress.progress(stream) 84 stream = progress.progress(stream)
89 85
90# Produce G-EDF error records 86# Produce G-EDF error records
91if options.gedf is True: 87if options.gedf is True:
88 from unit_trace import gedf_test
92 stream = gedf_test.gedf_test(stream) 89 stream = gedf_test.gedf_test(stream)
93 90
94# Filter some records out 91# Filter some records out
@@ -107,6 +104,7 @@ stream1, stream2, stream3 = itertools.tee(stream,3)
107 104
108# Call standard out printer 105# Call standard out printer
109if options.stdout is True: 106if options.stdout is True:
107 from unit_trace import stdout_printer
110 stdout_printer.stdout_printer(stream1) 108 stdout_printer.stdout_printer(stream1)
111 109
112# Print G_EDF inversion statistics 110# Print G_EDF inversion statistics
@@ -116,6 +114,7 @@ if options.num_inversions > -1:
116 sys.stderr.write("You must enable the G-EDF test module to print" + 114 sys.stderr.write("You must enable the G-EDF test module to print" +
117 " G-EDF inversion statistics\n") 115 " G-EDF inversion statistics\n")
118 else: 116 else:
117 from unit_trace import gedf_inversion_stat_printer
119 gedf_inversion_stat_printer.gedf_inversion_stat_printer(stream2,options.num_inversions) 118 gedf_inversion_stat_printer.gedf_inversion_stat_printer(stream2,options.num_inversions)
120 119
121# Call visualizer 120# Call visualizer