1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
<center>
#Unit-Trace#
</center>
<span style="font-weight: bold">
Unit-Trace is a library of tools for parsing, testing, and visualizing real-time scheduler traces.
Unit-Trace is inspired by the philosophy of "unit testing", in which software is tested iteratively to ensure it behaves according to specification.
Unit-Trace aims to help scheduler developers not only determine whether or not bugs exist, but to actually aid in debugging by providing detailed
information about scheduler behavior.
</span>
## About This Document ##
This document contains instructions for people who want to use and/or contribute to Unit-Trace.
It is the complete documentation for Unit-Trace.
## Architecture ##
Before trying to use Unit-Trace, it will help to understand the architecture of Unit-Trace.
Unit-Trace performs various options on **trace files**. Oftentimes, when scheduler tracing takes
place, multiple trace files are generated for each experiment (e.g. one per CPU). We call a
related group of trace files a **trace**.
The user interacts with the tool using `unit-trace`, a Python script which is to be installed
on the local executable path.
`unit-trace` invokes operations provided by the `unit_trace` Python module, which is installed
in the local `site_packages` directory (the default install location for Python modules).
The `unit_trace` module provides submodule(s) for parsing trace files into a **stream** of Python objects (which we call **records**).
This stream is then passed from one `unit_trace` submodule to the next (like a pipe), undergoing
various transformations in the process, and ultimately arriving at one or more output submodules.
Intermediate modules generally add records; for example, the `gedf_test` module adds records to indicate
priority inversions, which can be treated appropriately by output submodules.
This architecture provides a clean and easy-to-use interface for both users and contributors.
The stream is implemented using Python iterators.
This allows records are evaluated lazily (i.e. on an as-needed basis), making it possible to pull into memory only
the records that are needed, and only as long as they are needed.
This is important for dealing with very large traces.
## Obtaining Unit-Trace ##
Members of UNC's Real-Time Group can obtain Unit-Trace using:
<codeblock>git clone ssh://cvs.cs.unc.edu/cvs/proj/litmus/repo/unit-trace.git</codeblock>
## Installing Unit-Trace ##
Unit-Trace is based on Python 2.6, so make sure that is available on your system.
Unit-Trace can be installed manually by copying the `unit-trace` script and `unit_trace` Python module, as described previously.
Alternatively, you can use `sudo install.py` to (re)install Unit-Trace.
## Using Unit-Trace ##
Type `unit-trace` (without options) to view usage information.
In summary, trace files must be specified.
Flags are used to enable any desired submodules.
Some flags have accompanying parameter(s) that are passed to the submodule.
The order in which submodules process records is pre-determined by the `unit-trace` script,
so the user can specify flags on the command line in any order.
## Example/Use Case ##
Suppose that Alice wants to perform G-EDF testing on the LITMUS<sup>RT</sup> traces included in the sample_traces/ folder.
The LITMUS<sup>RT</sup> tracing mechanism outputs superfluous events at the beginning of the trace that will not appear "correct" for
G-EDF testing (for example, multiple job releases that never complete, indicating the initialization of a task).
Alice uses the following command to print out (-o) the first 50 records (-m 50), looking for the end of the bogus records:
<codeblock>unit-trace -m 50 -o *.bin</codeblock>.
Seeing that she hasn't yet reached useful records, she uses the following command to print out (-o) 50 records (-m 50), skipping the
first 50 (-s 50).
<codeblock>unit-trace -m 50 -s 50 -o *.bin</codeblock>.
She is able to see that meaningful releases begin at time `37917282934190`.
She now commences G-EDF testing (-g), starting at the time of interest (-e <earliest time>).
Because of the lengthy output to be expected, she redirects to standard out.
She also uses the -c option to clean up additional records that are known to be erroneous, and
will break the G-EDF tester.
<codeblock>unit-trace -c -e 37917282934190 -g -o *.bin > output</codeblock>.
OK, everything worked. Alice can now grep through the output file and see priority inversions.
She sees a particularly long priority inversion, and decides to generate a visualization (-v) of part of the schedule.
<codeblock>unit-trace -c -e 37918340000000 -l 37919000000000 -v *.bin</codeblock>.
(NOTE: Currently, this still shows the entire schedule, which likely won't be feasible for larger traces and is a bug.)
## Submodules ##
### Input Submodules ###
<table border=1>
<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr>
<tr><td>trace_parser</td><td>(on by default)</td><td>(None)</td><td>Parses LITMUS<sup>RT</sup> traces</td></tr>
</table>
### Intermediate Submodules ###
<table border=1>
<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr>
<tr><td>earliest</td><td>-e</td><td>time</td><td>Filters out records before the given time</td></tr>
<tr><td>latest</td><td>-l</td><td>time</td><td>Filters out records after the given time</td></tr>
<tr><td>skipper</td><td>-s</td><td>number n</td><td>Skips the first n records</td></tr>
<tr><td>maxer</td><td>-m</td><td>number n</td><td>Allows at most n records to be parsed</td></tr>
<tr><td>sanitizer</td><td>-c</td><td>(None)</td><td>Cleans up LITMUS<sup>RT</sup> traces for G-EDF testing.</td></tr>
<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>
<tr><td>stats</td><td>-i</td><td>(None)</td><td>Outputs statistics about G-EDF inversions. To be deprecated (incorporated into G-EDF tester).</td></tr>
<tr><td>gedf_test</td><td>-g</td><td>(None)</td><td>Performs G-EDF testing.</td></tr>
</table>
### Output Submodules ###
<table border=1>
<tr><td>Name</td><td>Flag</td><td>Options</td><td>Description</td></tr>
<tr><td>stdout_printer</td><td>-o</td><td>(None)</td><td>Prints records to standard out</td></tr>
<tr><td>visualizer</td><td>-v</td><td>(None)</td><td>Visualizes records</td></tr>
</table>
## Development ##
TODO: Information on how to contribute will be documented thoroughly here.
## Documentation ##
The source code for this page is included in the `doc` folder that comes with Unit-Trace.
Contributors are required to make appropriate amendments to this documentation.
The source is stored in [Markdown format][markdown] in the file `index.txt` and can be built into HTML with `make`.
## Credits ##
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],
[Department of Computer Science][csdept]. A detailed explanation of the tool is available in [this paper][ospert_paper], from
[the 2009 OSPERT workshop][ospert].
We would like to extend special thanks to Gary Bressler, who created and maintains the `visualizer` submodule as a volunteer with our group.
We hope to have additional contributors in the future.
[group]: http://cs.unc.edu/~anderson/real-time
[uncch]: http://www.unc.edu
[csdept]: http://cs.unc.edu
[ospert_paper]: http://www.cs.unc.edu/%7Eanderson/papers/ospert09.pdf
[ospert]: http://www.artist-embedded.org/artist/Overview,1750.html
[markdown]: http://daringfireball.net/projects/markdown/
|
