diff options
author | Gary Bressler <garybressler@nc.rr.com> | 2010-04-27 14:07:50 -0400 |
---|---|---|
committer | Gary Bressler <garybressler@nc.rr.com> | 2010-04-27 14:07:50 -0400 |
commit | 9fcc1ebd1b764a6f306596a5bd9cd7b0bd6eb1be (patch) | |
tree | dbcd292d940005f9785ad4a505a2c5ad03ae0c01 | |
parent | 62f5f8afb1d2fa48f16c929672f8dd49a0281960 (diff) | |
parent | 51e246d367d043913a882080abde3d8bae5ce4d4 (diff) |
hopefully fixed conflict
-rw-r--r-- | doc/index.txt | 24 | ||||
-rwxr-xr-x | unit-trace | 27 |
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 ## |
33 | Command line usage:<br> | 33 | Command line usage:<br> |
34 | <codeblock>unit-trace <one or more trace files> [flags]</codeblock>. | 34 | <codeblock>unit-trace <one or more trace files> [flags]</codeblock>. |
35 | 35 | ||
36 | Each flag turns on or off a unit-trace submodule. The available submodules are | 36 | Each flag turns on or off a unit-trace submodule. The available submodules are |
37 | given below. | 37 | given 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 ### |
44 | Let's assume you're in a directory with a bunch of trace files with | 44 | Let's assume you're in a directory with a bunch of trace files with |
45 | the extension `.bin`. | 45 | the extension `.bin`. |
46 | Each 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. | 46 | Each 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 | ||
118 | If 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 | ||
120 | The visualizer can give you an on-the-fly visual representation of the input | 122 | The 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 | |||
144 | for the relevant task or CPU. The event symbols are as follows: | 146 | for 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 |
157 | attached to the x-axis, as is customary, rather than in a CPU's area.)</td></tr> | 159 | attached 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 | ||
161 | If you're unsure as | 163 | If you're unsure as |
@@ -170,7 +172,7 @@ being scheduled and being descheduled, respectively. <i>However</i>, if the visu | |||
170 | finds a start event but not an end event (or vice-versa), it assumes that the corresponding | 172 | finds a start event but not an end event (or vice-versa), it assumes that the corresponding |
171 | event occurred, but at a time not in the input stream. | 173 | event occurred, but at a time not in the input stream. |
172 | In other words, it assumes that such events are genuine. To represent this phenomenon, | 174 | In other words, it assumes that such events are genuine. To represent this phenomenon, |
173 | the visualizer shows the bar going "off the graph". | 175 | the visualizer shows the bar going "off the graph". |
174 | 176 | ||
175 | Interacting with the visualizer is easy. The scrollbars work in the obvious way. You can also | 177 | Interacting with the visualizer is easy. The scrollbars work in the obvious way. You can also |
176 | use the arrow keys to move, or use Ctrl+arrow keys to move faster. Mousing over an event gives | 178 | use 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 ## |
248 | This project was created by and is maintained by the [Real-Time Systems Group][group] at the [University of North Carolina at Chapel Hill][uncch], | 250 | This 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 | ||
252 | We would like to extend special thanks to Gary Bressler, who created and maintains the `visualizer` submodule as a volunteer with our group. | 254 | We would like to extend special thanks to Gary Bressler, who created and maintains the `visualizer` submodule as a volunteer with our group. |
@@ -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. | ||
14 | import unit_trace | ||
15 | from unit_trace import trace_reader | ||
16 | from unit_trace import sanitizer | ||
17 | from unit_trace import gedf_test | ||
18 | from unit_trace import gedf_inversion_stat_printer | ||
19 | from unit_trace import stdout_printer | ||
20 | from unit_trace import progress | ||
21 | from unit_trace import skipper | ||
22 | from unit_trace import maxer | ||
23 | from unit_trace import earliest | ||
24 | from unit_trace import latest | ||
25 | |||
26 | # Get trace files from command line arguments | 12 | # Get trace files from command line arguments |
27 | from optparse import OptionParser | 13 | from optparse import OptionParser |
28 | usage = "usage: %prog [options] <one or more trace files>" | 14 | usage = "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 | ||
49 | import unit_trace | ||
50 | |||
62 | # Read events from traces | 51 | # Read events from traces |
52 | from unit_trace import trace_reader | ||
63 | stream = trace_reader.trace_reader(traces) | 53 | stream = trace_reader.trace_reader(traces) |
64 | 54 | ||
65 | # Skip over records | 55 | # Skip over records |
66 | if options.skipnum > 0: | 56 | if 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 |
70 | if options.maxnum > 0: | 61 | if 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 |
74 | if options.earliest > 0: | 66 | if 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 |
78 | if options.latest > 0: | 71 | if 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 |
82 | if options.clean is True: | 76 | if 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. |
87 | if options.progress is True: | 82 | if 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 |
91 | if options.gedf is True: | 87 | if 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 |
109 | if options.stdout is True: | 106 | if 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 |