1/*
2 * (C) 2001 by Argonne National Laboratory
3 * See COPYRIGHT in top-level directory.
4 */
5
6/*
7 * @author Anthony Chan
8 */
9
10 *********************************************************************
11 * Prefered reference for slog2sdk tools including Jumpshot-4 for *
12 * publications: *
13 * *
14 * An Efficient Format for Nearly Constant-Time Access to *
15 * Arbitrary Time Intervals in Large Trace Files. *
16 * Anthony Chan, William Gropp, and Ewing Lusk. *
17 * Scientific Programming, Volume 16, Number 2-3, *
18 * pages 155-165, 2008. *
19 * *
20 * Bibtex entry: *
21 * @article{slog2, *
22 * author = {Anthony Chan and William Gropp and Ewing Lusk}, *
23 * title = {An Efficient Format for Nearly Constant-Time *
24 * Access to Arbitrary Time Intervals in Large *
25 * Trace Files}, *
26 * journal = {Scientific Programming}, *
27 * volume = {16}, *
28 * number = {2-3}, *
29 * year = {2008}, *
30 * issn = {1058-9244}, *
31 * pages = {155--165}, *
32 * publisher = {IOS Press}, *
33 * address = {Amsterdam, The Netherlands, The Netherlands}, *
34 * } *
35 *********************************************************************
36
37
38This package provides both the Runtime and the Software Development
39environment for SLOG-2. The runtime environment includes a visualization
40tool for slog2 file, i.e. Jumpshot-4, and some utility programs like
41slog2print, slog2navigator, and logformat converter like clogTOslog2
42or some other trace format to slog2 converter. The development environment
43consists of a Java implementation of SLOG-2 Input/Output APIs, a Java
44implementation of TRACE-API for CLOG, a reference C implementation of
45TRACE-API and the JNI interface of TRACE-API and its Java counterparts.
46The development environment is mainly designed for TRACE-API implementors.
47
48For typical end users of SLOG-2, the runtime environment is what you
49are looking for. The runtime includes the following utility programs
50which are located in the bin/ directory after the package is configured
51and installed. The programs are
52
53jumpshot: A visualization tool for SLOG-2 file.
54logconvertor A GUI front end for all the logfile convertor.
55slog2filter A SLOG-2 formating and filtering program.
56slog2updater A SLOG-2 format update program.
57slog2print: A SLOG-2 serial printing program, i.e. scalable.
58slog2navigator: Another SLOG-2 printing program with navigation feature.
59 aka. baby jumpshot.
60
61clogprint: A CLOG printing program.
62clogTOslog2: A CLOG to SLOG-2 converter.
63
64traceprint: A custom TRACE printing program.
65traceTOslog2: A custom TRACE to SLOG-2 converter, this is created only
66 if configure option --with-trace-libdir is used.
67
68Each of the programs has a "-h" option to show its usage.
69
70The Development environment includes the RunTime environment and the
71extra directories: src/, trace_sample/ and possibly other trace_xxx/.
72The doc/ directory contains both the documentation for the runtime and
73development environment. The Development environment is Unix based
74but can be used under Windows's cygwin environment.
75
76For MS Windows user: As long as a Java2 runtime environment is installed,
77 Jumpshot can be launched with better JVM option by
78 clicking jumpshot_launcher.jar.
79
80
81
82To TRACE-API implementor:
83-------------------------
84The most helpful directory could be trace_sample/ which contains a
85reference implementation of TRACE-API written in C. The custom
86TRACE-API implementation converts ASCII definition of drawables
87(let's call it textlog) and passes those information through TRACE-API.
88There are 4 programs generated from this package. They are:
89
90textlog_print(.exe): C version of textlog print program
91textlogprint: Java version of textlog print and time order
92 checking program( with -tc option ).
93textlog_check_timeorder(.exe): C version of textlog time order checking
94 program.
95textlogTOslog2: textlog to SLOG-2 convertor
96
97As shown, the subpackage contains two version of TRACE printing
98programs. One is written in C and the other is written in Java.
99They are trace_print.c and Print.java. Both of them are in
100src/logformat/trace. Each program prints out the content of the trace
101file specified in the command line when the program is invoked. The C
102version of TRACE printing program aims to help TRACE-API implementor
103to debug their TRACE-API implementation. The Java print program invokes
104the Java interface of TRACE-API, i.e. JNI, and then calls the actual C
105implementation of TRACE-API through the JNI code in
106src/logformat/trace/logformat_trace_InputLog.c. So failure of using
107the Java printing program indicates incompatibility between the
108implementation and the JNI code provided here. Also the Java version
109of printing program has a command line option, -tc, which turns on the
110endtime-order checking code. Since the order of the drawables is passed
111to TRACE-API is cruical in visualization accuracy of the slog2 file, the
112time order checking code further makes sure that the TRACE-API
113implementation is being done correctly. There is no similar option in C
114version of TRACE printing program. Instead the functionality is provided
115through another C program, trace_check_timeorder.c.
116
117In order to avoid duplication of source and ease of maintainence
118and support, trace_sample is arranged in a way that only the TRACE-API
119implementation code is located in trace_sample/src. All the files
120that are needed to build a TRACE-API shared library( needed by Java )
121and utility programs remain in src/logformat/trace. The Makefile
122uses make's VPATH feature to achieve its goal. These files are
123trace_API.h, logformat_trace_InputLog.c, trace_print.c and
124trace_check_timeorder.c. In general, developer of TRACE-API only
125needs to modify variable IMPL_CSRC in trace_sample/src/Makefile.in.
126IMPL_CSRC defines the C programs needed to build a TRACE-API implementation.
127If you are interested to modify the name of the utility program like
128traceprint and traceTOslog2 to something more meaningful, you need
129to change TRACE_NAME define configure.ac. The TRACE_NAME replaces
130the prefix "trace" in traceprint and traceTOslog2. Remember to run
131autoconf afterward. If you need to add extra system header files to
132be checked by autoconf, e.g. through AC_CHECK_HEAEDERS, you need to
133run autoheader before running autoconf. Since the configure uses
134libtool to generate shared library, using the suggested infrastructure
135should increases portability(as well as ease of support from the author)
136of your TRACE-API implementation.
137
138traceprint.jar and traceTOslog2.jar require libTraceInput.so(for Unix)
139or TraceInput.dll(for Windows) to run. The name of the shared library,
140TraceInput, has been hardwired into the jar files. That means the shared
141library has to be named "TraceInput". For more details, see
142trace_sample/src/Makefile.in(or Makefile). Essentially, libTraceInput.so
143or TraceInput.dll is created by linking
144src/logformat/trace/logformat_trace_InputLog.o with the object files of the
145TRACE-API implementation.
146
147
148Recommended Directory structure for custom TRACE-API implementation:
149--------------------------------------------------------------------
150It is recommended for all TRACE-API implementors to create a separate
151directory to develop their TRACE-API implementation, i.e. don't write
152any code in any SLOG-2 and Jumpshot directories, i.e. src/. The suggested
153directory structure is to create new directory, say trace_myformat/, at
154the same level at the top level directory, i.e. at the same level as
155as this README. Under trace_myformat/, there should be subdirectories like
156src/, include/, bin/, lib/, logfiles/. A reference Makefile, which is
157located trace_sample/src, serves as a template to interact with the JNI
158code provided in src/logformat/trace. As usual, all source files, .c
159and .h, go to src/, or .h files go to include/, all executables built
160go to bin/, all libraries go to lib/. Any logfiles created should be
161stored in logfiles/. After the code is fully debugged, and you don't
162need any support from the author, you can move your custom TRACE-API code
163anywhere you want.
164
165
166Directory structure of the Java code:
167-------------------------------------
168Main Java source directories are (all of them are under src/):
169logformat/clog, logformat/clogTOdrawable, logformat/trace, logformat/slog2
170and base/drawable and viewer/timelines.
171
172logformat/clog: this directory contains a CLOG parser.
173logformat/clogTOdrawable: this directory contains a CLOG to Drawable converter.
174
175logformat/trace: this directory contains Java Native Interface to TRACE-API,
176 i.e. all the required Java and C code to interface between
177 C implementation of TRACE-API and the Java SLOG-2 code.
178
179logformat/slog2: this directory contains both the Input and Output API for
180 SLOG-2. Both ClogToSlog2 and TraceToSlog2 converter are
181 defined here. It also defines a SLOG-2 navigator and
182 print programs.
183
184base/drawable: this directory contains all the definitions of drawable
185 related classes. The Java interface of TRACE-API is
186 defined here and is in file src/base/drawable/InputAPI.java
187
188viewer/*: this directories are the bulk of the new Jumpshot for SLOG-2.
189
190
191The next important directory is probably the top level lib/ directory
192where all the executable jar files are located. The utility programs
193mentioned above has its bytecode archived by the following jar file
194of the same name. They are
195
196slog2filter.jar: executable jar file that filters or modifies the content
197 of the slog2 file, e.g. removal of undesirable categories
198 and their drawables.
199
200slog2updater.jar: executable jar file that updates the file with older slog2
201 format to the latest slog2 format.
202
203slog2print.jar: executable jar file prints the slog2 file
204 usage: java -jar slog2print.jar slog2filename
205
206slog2navigator.jar: executable jar file that navigates in the slog2 file
207 usage: java -jar slog2navigator slog2filename
208
209traceprint.jar: executable jar file prints the trace file
210 usage: java -Djava.library.path=<location_to_libTraceInput.so>
211 -jar traceprint.jar tracefilename
212
213traceTOslog2.jar: executable jar file converts trace to slog2 file
214 usage: java -Djava.library.path=<location_to_libTraceInput.so>
215 -jar traceTOslog2.jar tracefilename
216
217clogprint.jar: executable jar file prints the clog file
218 usage: java -jar traceprint.jar clogfilename
219
220clogTOslog2.jar: executable jar file converts clog to slog2 file
221 usage: java -jar traceTOslog2.jar clogfilename
222
223jumpshot.jar: executable jar file that visualizes slog2 file and convert
224 clog, rlog and ute files to slog2 file.
225 usage: java -Xms64m -Xmx256m -jar jumpshot.jar [filename]
226
227jumpshot_launcher.jar: executable jar file that launchs jumpshot.jar
228 usage:java -jar jumpshot_launcher
229
230
231Using SLOG2 command line utility programs
232-----------------------------------------
2331) Modifocation of SLOG2 File's Structure:
234 slog2filter that can reconfigure slog2 treenode features,
235 like tree leaf size and number of child nodes per parent node through
236 command like
237
238 e.g. slog2filter -ls 128k flash2.slog2
239
240 which will create a flash2.slog2.slog2 file with slog2 leaf size = 128k
241 instead of the default 64k. This is useful to readjust the number of
242 preview bands in Jumpshot if the default one does not produce a desirable
243 view in Jumpshot.
244
2452) Print Specific Information of SLOG2 File:
246 a) slog2print prints drawables in the 4 time orders as listed by
247 "slog2print -h".
248 b) Also, slog2print can print specific features of slog2 file,
249 like CategoryMap, DirectoryTree, Y-Coordinate Map....
250
251 e.g. slog2print -c flash2.slog2
252
253 which prints the CategoryMap of flash2.slog2
254
2553) Removal of Undesirable Categories of Drawables:
256 slog2filter can delete specific categories of drawables.
257 i.e. using "slog2print -c" to identify the category indexes of undesirable
258 drawables, say id1,id2,...idN. Then do
259
260 slog2repair -r id1,id2,...idN -o new_flash2.slog2 flash2.slog2
261
262 which will create a new_flash2.slog2 file that does not have drawables
263 with category indexes, id1,id2,...idN, and with similar file structure
264 as the original one.
265
2664) Format Updater:
267 slog2updater updates the logfile with older slog2 format to the latest one.
268
269 slog2filter -o fpilog_new.slog2 fpilog_old.slog2
270
271 which converts the fpilog_old.slog2 with older slog2 format to the
272 latest one named fpilog_new.slog2.
273
274