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
37This is an ASCII text file format to slog2 convertor.
38
39The ASCII text file format is described as follows:
40It basically contains 3 types of records, Category, Primitive or Composite,
41and YCoordMap.
42
431) Category defines the name, color and shape of the drawable
44 as well the sprintf style format string for the byteinfo array.
45 For example, below is a line that defines a Category.
46
47Category[ index=0 name=message topo=Arrow color=(255,255,255,255,true) width=3 <msg_tag=%d, msg_size=%d> ]
48Category[ index=10 name=Project_A topo=State color=(160,32,240,127,true) width=1 <jobID=%d\n account=%s user=%s> ]
49
50 where
51 index="the category index", positive integer.
52 name="the name of category", any ASCII string.
53 topo="shape of drawables". The supported topologies are
54 Arrow, Event, and State.
55 color="(Red, Green, Blue, Transparency, isModifiableIdentifier)",
56 width="width of drawables", usually 1.
57 The last entry is bounded by angle brackets "<" and ">".
58 The % conversion specifier supported are listed as follows:
59 %d 4-byte signed integer in Java (network) byte order.
60 %h 2-byte signed integer in Java (network) byte order.
61 %l 8-byte signed integer in Java (network) byte order.
62 %x 4-byte unsigned byte hex in Java (network) byte order.
63 %X 8-byte unsigned byte hex in Java (network) byte order.
64 %e 4-byte float pointing number in Java (network) byte order.
65 %E 8-byte float pointing number in Java (network) byte order.
66 %s string with length specified by a 2-byte network byte ordered integer.
67 Also, "\n" the newline character will be interpreted by Jumpshot to
68 split the long lines into multiple ones in popup info dialog box.
69
702) YCoordMap defines the mapping between lineID in each drawable to
71 the actual row in Jumpshot's screen. YCoordMap is optional because
72 the default mapping called Identity Map is alway present. Identity
73 Map is a one-to-one map where RowID = LineID.
74
753) Primitive and Composite are drawable types. Composite drawable
76 is a collection of Primitive drawables. Each Primitive is marked
77 by TimeBoundingBox between 2 timestamps, followed by Category index
78 and then actual coordinates of the drawables.
79 The last entry is the optional byteinfo array which is a passthrough
80 array in network byte order that supplies the arguments for the
81 sprintf style format string defined in Category.
82 Composite drawables ain't meaningful unless methods are specified to
83 define how Primitives should be displayed. Currently only one predefined
84 method, connect, is predefined in Jumpshot.
85 e.g.
86
87Primitive[ TimeBBox(0.000500,0.0010000) Category=10 (0.000500, 2) (0.0010000, 2) <12345;;Google_com;;tom> ]
88
89 TimeBBox("started timestamp","ended timestamp")
90 Category=<Category index defined in Category section>
91 (timestamp, lineID) is coordinate of a vertex of each drawable.
92 Event has one vertex, State and Arrow both have 2 vertices.
93 <....;;...> specifies the byteinfo array with delimiter ";;" that
94 separates number of byteinfo array values.
95 The number of byteinfo array values must match the number of
96 % conversion specifier defined in the corresponding Category.
97