1 /* 2 * (C) 2001 by Argonne National Laboratory 3 * See COPYRIGHT in top-level directory. 4 */ 5 6 /* 7 * @author Bill Gropp, Anthony Chan 8 */ 9 10 /* 11 * API to read a trace file for the SLOG algorithm 12 */ 13 14 #if defined(__cplusplus) 15 extern "C" { 16 #endif 17 18 typedef struct _trace_file *TRACE_file; 19 20 #if defined( WIN32 ) 21 #define TRACE_EXPORT __declspec(dllexport) 22 #define TRACE_int64_t __int64 23 #else 24 #define TRACE_EXPORT 25 #define TRACE_int64_t long long 26 #endif 27 28 /*E 29 TRACE_Rec_Kind_t - Types of records returned by the TRACE API 30 31 Types: 32 + TRACE_EOF - End of file. Indicates that no more items are available. 33 . TRACE_PRIMITIVE_DRAWABLE - Primitive Drawable; 34 for example, an event, state or arrow. 35 . TRACE_COMPOSITE_DRAWABLE - Composite Drawable; 36 a collection of primitive drawables. 37 . TRACE_CATEGORY - Category, describing classes of drawables. 38 - TRACE_YCOORDMAP - Y-axis Coordinate map, describing how to 39 interpret or label the y coordinate values 40 41 Notes: 42 These record types represent the type of data that the TRACE API presents to 43 the calling program. The source file that the TRACE API is reading may 44 or may not contain any of these record types. In fact, most trace files 45 will not contain any of these record types; instead, the implementation of 46 the TRACE API will read the source trace file and create these from the 47 raw data in the original source file. 48 E*/ 49 typedef enum { TRACE_EOF=0, 50 TRACE_PRIMITIVE_DRAWABLE=1, 51 TRACE_COMPOSITE_DRAWABLE=2, 52 TRACE_CATEGORY=3, 53 TRACE_YCOORDMAP=4 } 54 TRACE_Rec_Kind_t; 55 56 /* 57 Predefined Shapes ID - for 'TRACE_Category_head_t' 58 */ 59 #define TRACE_SHAPE_EVENT 0 60 #define TRACE_SHAPE_STATE 1 61 #define TRACE_SHAPE_ARROW 2 62 63 /* 64 Predefined Method IDs - for 'TRACE_Get_next_category()' 65 and 'TRACE_Get_next_ycoordmap()' 66 */ 67 #define TRACE_METHOD_CONNECT_COMPOSITE_STATE 1 68 69 /*S 70 TRACE_Category_head_t - Structure defining the basic information about a 71 category 72 73 + index - integer value by which records will identify themselves 74 as belonging to this category. index is assumed to be non-negative. 75 negative index is reserved for internal use. 76 . shape - Shape of the category. This is an integer defined by the drawing 77 program; the value 'TRACE_SHAPE_EVENT' (=0) is reserved for an event 78 ( a marker at one point on a timeline ), the value 'TRACE_SHAPE_STATE' (=1) 79 is reserved for a basic state (a rectangle along a timeline), 80 'TRACE_SHAPE_ARROW' (=2) is reserved for an arrow (such as used to 81 describe a message from a send state to a receive state), 82 . red, green, blue - Color of the shape; each is in the range [0,255] 83 . alpha - Transparency value, in the range of [0,255]. Some display programs 84 may ignore this value. An alpha value of 255 means that the color 85 is completely opaque and an alpha value of 0 means that the color 86 is completely transparent. (reference java.awt.Color) 87 - width - the pixel width of the stroke when drawing the shape. Some display 88 programs may ignore this value. 89 90 S*/ 91 typedef struct { 92 int index; 93 int shape; 94 int red, green, blue, alpha; 95 int width; 96 } TRACE_Category_head_t; 97 98 /* 99 . name - name of the category (See below) 100 101 Questions: 102 A prior version left the 'name' out of the 'TRACE_Category_head_t'. 103 This was done to separate the frequently accessed data (shape, color, 104 width) that is needed to render a member of this category from the data 105 needed to describe the category on a legend and to describe a particular 106 instance (the label). A more recent version included 'char *name', but 107 the API provided no way to allocate or free the associated storage for 108 this data. I have removed 'name' until the issues are resolved. 109 110 */ 111 112 TRACE_EXPORT 113 int TRACE_Open( const char filespec[], TRACE_file *fp ); 114 115 TRACE_EXPORT 116 int TRACE_Close( TRACE_file *fp ); 117 118 /* 119 TRACE_EXPORT 120 int TRACE_Get_total_time( const TRACE_file fp, 121 double *starttime, double *endtime ); 122 */ 123 124 TRACE_EXPORT 125 int TRACE_Peek_next_kind( const TRACE_file fp, TRACE_Rec_Kind_t *next_kind ); 126 127 TRACE_EXPORT 128 int TRACE_Get_next_method( const TRACE_file fp, 129 char method_name[], char method_extra[], 130 int *methodID ); 131 132 TRACE_EXPORT 133 int TRACE_Peek_next_category( const TRACE_file fp, 134 int *n_legend, int *n_label, 135 int *n_methodIDs ); 136 137 TRACE_EXPORT 138 int TRACE_Get_next_category( const TRACE_file fp, 139 TRACE_Category_head_t *head, 140 int *n_legend, char legend_base[], 141 int *legend_pos, const int legend_max, 142 int *n_label, char label_base[], 143 int *label_pos, const int label_max, 144 int *n_methodIDs, int methodID_base[], 145 int *methodID_pos, const int methodID_max ); 146 147 TRACE_EXPORT 148 int TRACE_Peek_next_ycoordmap( TRACE_file fp, 149 int *n_rows, int *n_columns, 150 int *max_column_name, 151 int *max_title_name, 152 int *n_methodIDs ); 153 154 TRACE_EXPORT 155 int TRACE_Get_next_ycoordmap( TRACE_file fp, 156 char *title_name, 157 char **column_names, 158 int *coordmap_sz, int coordmap_base[], 159 int *coordmap_pos, const int coordmap_max, 160 int *n_methodIDs, int methodID_base[], 161 int *methodID_pos, const int methodID_max ); 162 163 TRACE_EXPORT 164 int TRACE_Peek_next_primitive( const TRACE_file fp, 165 double *starttime, double *endtime, 166 int *n_tcoords, int *n_ycoords, int *n_bytes ); 167 168 TRACE_EXPORT 169 int TRACE_Get_next_primitive( const TRACE_file fp, 170 int *category_index, 171 int *n_tcoords, double tcoord_base[], 172 int *tcoord_pos, const int tcoord_max, 173 int *n_ycoords, int ycoord_base[], 174 int *ycoord_pos, const int ycoord_max, 175 int *n_bytes, char byte_base[], 176 int *byte_pos, const int byte_max ); 177 178 TRACE_EXPORT 179 int TRACE_Peek_next_composite( const TRACE_file fp, 180 double *starttime, double *endtime, 181 int *n_primitives, int *n_bytes ); 182 183 TRACE_EXPORT 184 int TRACE_Get_next_composite( const TRACE_file fp, 185 int *category_index, 186 int *n_bytes, char byte_base[], 187 int *byte_pos, const int byte_max ); 188 189 190 TRACE_EXPORT 191 int TRACE_Get_position( TRACE_file fp, TRACE_int64_t *offset ); 192 193 TRACE_EXPORT 194 int TRACE_Set_position( TRACE_file fp, TRACE_int64_t offset ); 195 196 TRACE_EXPORT 197 const char *TRACE_Get_err_string( int ierr ); 198 199 #if defined(__cplusplus) 200 } 201 #endif 202