diff options
author | Mac Mollison <mollison@cs.unc.edu> | 2010-04-03 19:24:59 -0400 |
---|---|---|
committer | Mac Mollison <mollison@cs.unc.edu> | 2010-04-03 19:24:59 -0400 |
commit | 010139704cf40d1acb084e6088bc8cb855bf5095 (patch) | |
tree | 8cb81de8c7b18182938ba2030f12be1b1ac4743c | |
parent | ae3ba00d4f644cc57ba784a7185466e07a561f01 (diff) | |
parent | f511446bc9f8e54ac02c39b75389f568e9c2d6e1 (diff) |
Merge branch 'master' into blocking
-rw-r--r-- | README | 105 | ||||
-rw-r--r-- | doc/LICENSE | 22 | ||||
-rw-r--r-- | doc/index.txt | 6 |
3 files changed, 27 insertions, 106 deletions
@@ -1,105 +0,0 @@ | |||
1 | See the LITMUS Wiki page for a general explanation of this tool. | ||
2 | |||
3 | unit_trace consists of two modules and a core. The ``core'' is basically | ||
4 | a bunch of code, implemented as Python iterators, which converts the | ||
5 | raw trace data into a sequence of record objects, implemented in | ||
6 | Python. The modules are: | ||
7 | |||
8 | 1) A simple module that outputs the contents of each record to | ||
9 | stdout. This module, along with most of the core, can be found in the | ||
10 | reader/ directory. There is a sample script -- look at | ||
11 | sample_script.py in the reader/ directory (it's pretty | ||
12 | self-explanatory). Note that Mac is the one who coded most of the | ||
13 | this, though I can probably try to answer any questions about it since | ||
14 | I've had to go in there from time to time. | ||
15 | |||
16 | 2) The visualizer. Now, the GUI as it stands is very basic -- it's | ||
17 | basically just a shell for the core visualizer component. How to open | ||
18 | a file is obvious -- but note that you can open several files at a | ||
19 | time (since more often than not a trace consists of more than one | ||
20 | file, typically one for each CPU). | ||
21 | |||
22 | Most of the code for this is in the viz/ directory, but to run it, the | ||
23 | file you want to execute is visualizer.py (in the main directory). | ||
24 | |||
25 | A few notes on how to use the GUI: | ||
26 | |||
27 | -- How to scroll is pretty obvious, though I still need to implement | ||
28 | keypresses (very trivial, but when making a GUI component from | ||
29 | scratch it always seems like there are a million little things that | ||
30 | you need to do :) | ||
31 | |||
32 | -- You can view either by task or by CPU; click the tabs at the top. | ||
33 | |||
34 | -- Mousing over the items (not the axes, though, since those are | ||
35 | pretty self-explanatory) gives you information about the item that | ||
36 | you moused over, displayed at the bottom. | ||
37 | |||
38 | -- You can select items. You can click them individually, one at a | ||
39 | time, or you can drag or ctrl-click to select multiple. | ||
40 | |||
41 | -- What you have selected is independent of what mode (task or CPU) | ||
42 | you are operating in. So if you are curious, say, when a certain | ||
43 | job is running compared to other jobs on the same CPU, you can | ||
44 | click a job in task mode and then switch to CPU mode, and it will | ||
45 | remain selected. | ||
46 | |||
47 | -- Right-click to get a menu of all the items you have selected (in | ||
48 | the future this menu will be clickable, so that you can get the | ||
49 | information about an item in its own window). | ||
50 | |||
51 | -- It is a bit laggy when lots of stuff is on the screen at once. This | ||
52 | should be fairly easy to optimize, if I have correctly identified | ||
53 | the problem, but it's not a huge issue (it's not _that_ slow). | ||
54 | |||
55 | But wait, there's more: | ||
56 | |||
57 | -- As of now unit-trace has no way to determine the algorithm that was | ||
58 | used on the trace you're loading. This is important since certain | ||
59 | sections of code work only with G-EDF in particular. The point of | ||
60 | having this special code is either to filter out bogus data or to | ||
61 | generate extra information about the schedule (e.g. priority | ||
62 | inversions). Of course, you can leave these extra steps out and | ||
63 | it will still work, but you might get extra ``bogus'' information | ||
64 | generated by the tracer or you might not get all the information | ||
65 | you want. | ||
66 | |||
67 | -- To add or remove these extra steps, take a look at visualizer.py | ||
68 | and sample_script.py. You will see some code like this: | ||
69 | |||
70 | stream = reader.trace_reader.trace_reader(file_list) | ||
71 | #stream = reader.sanitizer.sanitizer(stream) | ||
72 | #stream = reader.gedf_test.gedf_test(stream) | ||
73 | |||
74 | Uncommenting those lines will run the extra steps in the pipeline. | ||
75 | The sanitizer filters out some bogus data (stuff like ``pid 0''), | ||
76 | but so far it's only been coded for a select number of traces. | ||
77 | gedf_test generates extra information about G-EDF schedules | ||
78 | (the traces that are named st-g?-?.bin). If you try to run | ||
79 | gedf_test on anything else, it will most likely fail. | ||
80 | |||
81 | -- What traces are you going to use? Well, you will probably want to | ||
82 | use your own, but there are some samples you can try in the traces/ | ||
83 | directory (a couple of them do give error messages, however). | ||
84 | |||
85 | How to install: | ||
86 | |||
87 | You should type | ||
88 | |||
89 | git clone -b wip-gary ssh://cvs.cs.unc.edu/cvs/proj/litmus/repo/unit-trace.git | ||
90 | |||
91 | to check out the repository. Note that you shouldn't check out the | ||
92 | master branch, as it's pretty outdated. It's all Python so far, so no | ||
93 | compiling or anything like that is necessary. | ||
94 | |||
95 | Requirements: | ||
96 | |||
97 | You're going to need Python 2.5 to run this. You'll also need to | ||
98 | install the pycairo and pygtk libraries. If anyone has questions about | ||
99 | how to do this or what these are, ask me. | ||
100 | |||
101 | Miscellanies: | ||
102 | |||
103 | Of course, let me know if you find any bugs (I'm sure there are | ||
104 | plenty, though, since this is fairly alpha software), if you're | ||
105 | unable to run it, or if you have any questions. \ No newline at end of file | ||
diff --git a/doc/LICENSE b/doc/LICENSE new file mode 100644 index 0000000..30a9810 --- /dev/null +++ b/doc/LICENSE | |||
@@ -0,0 +1,22 @@ | |||
1 | Copyright (c) 2010, UNC Real-Time Systems Group | ||
2 | All rights reserved. | ||
3 | |||
4 | Redistribution and use in source and binary forms, with or without | ||
5 | modification, are permitted provided that the following conditions are met: | ||
6 | |||
7 | * Redistributions of source code must retain the above copyright notice, | ||
8 | this list of conditions and the following disclaimer. | ||
9 | * Redistributions in binary form must reproduce the above copyright notice, | ||
10 | this list of conditions and the following disclaimer in the documentation | ||
11 | and/or other materials provided with the distribution. | ||
12 | |||
13 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND | ||
14 | ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED | ||
15 | WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | ||
16 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE | ||
17 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | ||
18 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR | ||
19 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER | ||
20 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, | ||
21 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | ||
22 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | ||
diff --git a/doc/index.txt b/doc/index.txt index cc9c766..135e734 100644 --- a/doc/index.txt +++ b/doc/index.txt | |||
@@ -18,7 +18,7 @@ Members of UNC's Real-Time Group can obtain Unit-Trace using:<br> | |||
18 | <codeblock>git clone ssh://cvs.cs.unc.edu/cvs/proj/litmus/repo/unit-trace.git</codeblock> | 18 | <codeblock>git clone ssh://cvs.cs.unc.edu/cvs/proj/litmus/repo/unit-trace.git</codeblock> |
19 | 19 | ||
20 | ## Installing Unit-Trace ## | 20 | ## Installing Unit-Trace ## |
21 | Unit-Trace is based on Python 2.6, so make sure that is available on your system. | 21 | Dependencies: Python 2.6; for the visualizer, pygtk and pycairo. |
22 | 22 | ||
23 | Unit_Trace consists of a Python module called `unit_trace` (encapsulated in the `unit_trace` directory) and a font-end script called `unit-trace`. | 23 | Unit_Trace consists of a Python module called `unit_trace` (encapsulated in the `unit_trace` directory) and a font-end script called `unit-trace`. |
24 | 24 | ||
@@ -144,6 +144,9 @@ Contributors are required to make appropriate amendments to this documentation. | |||
144 | 144 | ||
145 | The source is stored in [Markdown format][markdown] in the file `index.txt` and can be built into HTML with `make`. | 145 | The source is stored in [Markdown format][markdown] in the file `index.txt` and can be built into HTML with `make`. |
146 | 146 | ||
147 | ## License ## | ||
148 | Unit-Trace is released under the [Simplified BSD License][license]. | ||
149 | |||
147 | ## Credits ## | 150 | ## Credits ## |
148 | 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], | 151 | 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], |
149 | [Department of Computer Science][csdept]. A detailed explanation of the tool is available in [this paper][ospert_paper], from | 152 | [Department of Computer Science][csdept]. A detailed explanation of the tool is available in [this paper][ospert_paper], from |
@@ -161,3 +164,4 @@ We hope to have additional contributors in the future. | |||
161 | [ospert]: http://www.artist-embedded.org/artist/Overview,1750.html | 164 | [ospert]: http://www.artist-embedded.org/artist/Overview,1750.html |
162 | [markdown]: http://daringfireball.net/projects/markdown/ | 165 | [markdown]: http://daringfireball.net/projects/markdown/ |
163 | [mac]: mailto:mollison@cs.unc.edu | 166 | [mac]: mailto:mollison@cs.unc.edu |
167 | [license]: LICENSE | ||