Added TR_SYNC, which is sent by DYNINSTbreakPoint right after call
[dyninst.git] / visi / h / visualization.h
1 /*
2  * Copyright (c) 1996 Barton P. Miller
3  * 
4  * We provide the Paradyn Parallel Performance Tools (below
5  * described as Paradyn") on an AS IS basis, and do not warrant its
6  * validity or performance.  We reserve the right to update, modify,
7  * or discontinue this software at any time.  We shall have no
8  * obligation to supply such updates or modifications or any other
9  * form of support to you.
10  * 
11  * This license is for research uses.  For such uses, there is no
12  * charge. We define "research use" to mean you may freely use it
13  * inside your organization for whatever purposes you see fit. But you
14  * may not re-distribute Paradyn or parts of Paradyn, in any form
15  * source or binary (including derivatives), electronic or otherwise,
16  * to any other organization or entity without our permission.
17  * 
18  * (for other uses, please contact us at paradyn@cs.wisc.edu)
19  * 
20  * All warranties, including without limitation, any warranty of
21  * merchantability or fitness for a particular purpose, are hereby
22  * excluded.
23  * 
24  * By your use of Paradyn, you understand and agree that we (or any
25  * other person or entity with proprietary rights in Paradyn) are
26  * under no obligation to provide either maintenance services,
27  * update services, notices of latent defects, or correction of
28  * defects for Paradyn.
29  * 
30  * Even if advised of the possibility of such damages, under no
31  * circumstances shall we (or any other person or entity with
32  * proprietary rights in the software licensed hereunder) be liable
33  * to you or any third party for direct, indirect, or consequential
34  * damages of any character regardless of type of action, including,
35  * without limitation, loss of profits, loss of use, loss of good
36  * will, or computer failure or malfunction.  You agree to indemnify
37  * us (and any other person or entity with proprietary rights in the
38  * software licensed hereunder) for any and all liability it may
39  * incur to third parties resulting from your use of Paradyn.
40  */
41
42 #ifndef _visualization_h
43 #define _visualization_h
44
45 //////////////////////////////////////////////////////////////////
46 //  This file should be included in all visualizations. It 
47 //  contains definitions for all the Paradyn visi interface routines.  
48 // 
49 //  This file should not contain any C++ code. It is intended to be 
50 //  used  by either C or C++ visis, and therefore it should be able  
51 //  to be compiled by a C compiler.
52 //////////////////////////////////////////////////////////////////
53
54 #if defined(__cplusplus)
55 extern "C" {
56 #endif
57
58 #include "visiTypes.h"
59 /////////////////////////////////////////////////////////////
60 // these functions invoke upcalls to a visi interface client
61 // (call from visualization process to paradyn)
62 /////////////////////////////////////////////////////////////
63 //
64 // get a new set of metrics and resources from Paradyn
65 // currently, passing a list of met-res pairs is not supported 
66 // (i.e. these parameters are ignored)
67 //
68 extern void visi_GetMetsRes(char *metres,  // predefined list met-res pairs
69                             int numElements); 
70
71 //
72 // stop data collection for a metric/resource pair
73 // arguments are the datagrid indicies associated with the
74 // metric and resource to stop
75 //
76 extern void visi_StopMetRes(int metricIndex,int resourceIndex); 
77
78 //
79 // define a new phase to paradyn, can specify a name for the phase
80 // passing 0 for name argument will cause visiLib to create a 
81 // unique name for the phase
82 // passing 1 for withPerfConsult or withVisis will cause a new
83 // new PerfConsult search or visi to be started with the new phase, 
84 // passing 0  will just start a new phase
85 //
86 extern void visi_DefinePhase(char *phase_name,
87                              unsigned withPerfConsult,
88                              unsigned withVisis);
89
90 //
91 // request to Paradyn to display error message
92 //
93 extern void visi_showErrorVisiCallback(const char *msg);
94
95 ////////////////////////////////////////////////////////////////
96 //   initialization routines 
97 ////////////////////////////////////////////////////////////////
98 //
99 // Visi Initialization routine, returns a file descriptor that  
100 // is used to communicate with Paradyn.  This file descriptor 
101 // should be added by the visi as a source of input with the
102 // visiLib routine "visi_callback" as the callback routine 
103 // associated with this file descriptor.
104 // This routine should be called before entering the visualization's
105 // main loop, and before calling any other visi-interface routines
106 //
107 extern int  visi_Init();
108
109 //
110 // callback associated with paradyn-visualization interface routines
111 //
112 extern int visi_callback();
113
114 //
115 // registration callback routine for paradyn events
116 // sets eventCallbacks[event] to callback routine provided by user
117 // returns -1 on error, otherwise returns 0 
118 //
119 extern int visi_RegistrationCallback(visi_msgTag event,int (*callBack)(int));
120
121 //
122 // cleans up visi interface data structs
123 // Visualizations should call this routine before exiting 
124 extern void visi_QuitVisi();
125
126 // **********************************************
127 //
128 //  Data Grid Routines
129 //
130 // **********************************************
131 //
132 // returns the ith metric name or 0 on error   
133 //
134 extern const char *visi_MetricName(int metric_num);
135
136 //
137 // returns the ith metric units name or 0 on error   
138 //
139 extern const char *visi_MetricUnits(int metric_num);
140
141 //
142 // returns the ith metric units label for data values or 0 on error   
143 //
144 extern const char *visi_MetricLabel(int metric_num);
145
146 //
147 // returns the ith metric units label for average aggregate data values,
148 // or 0 on error   
149 //
150 extern const char *visi_MetricAveLabel(int metric_num);
151
152 //
153 // returns the ith metric units label for sum aggregate data values,
154 // or 0 on error   
155 //
156 extern const char *visi_MetricSumLabel(int metric_num);
157
158 //
159 // returns the ith resource's name,  or 0 on error   
160 //
161 extern const char *visi_ResourceName(int resource_num);
162
163 //
164 //  returns the number of metrics in the data grid
165 //
166 extern int visi_NumMetrics();
167
168 //
169 //  returns the number of resources in the data grid
170 //
171 extern int visi_NumResources();
172
173 //
174 //  returns the number of phases currently defined in the system   
175 //
176 extern unsigned visi_NumPhases();
177
178 //
179 // returns the start time of the phase for which this visi is defined
180 //
181 extern visi_timeType visi_GetStartTime();
182
183 //
184 // returns the name of the phase for which this visi is defined
185 //
186 extern const char *visi_GetMyPhaseName();
187
188 //
189 // returns the handle of the phase for which this visi is defined or
190 // -1 on error
191 //
192 extern int visi_GetMyPhaseHandle();
193
194 //
195 // returns the handle of the ith phase or -1 on error
196 //
197 extern int visi_GetPhaseHandle(unsigned phase_num);
198
199 //
200 // returns phase name for the ith phase, or returns 0 on error
201 //
202 extern const char *visi_GetPhaseName(unsigned phase_num);
203
204 //
205 // returns phase start time for the ith phase, or returns -1.0 on error
206 //
207 extern visi_timeType visi_GetPhaseStartTime(unsigned phase_num);
208
209 //
210 // returns phase end time for the ith phase, or returns -1.0 on error
211 //
212 extern visi_timeType visi_GetPhaseEndTime(unsigned phase_num);
213
214 //
215 // returns phase bucket width for the ith phase, or returns -1.0 on error
216 //
217 extern visi_timeType visi_GetPhaseBucketWidth(unsigned phase_num);
218
219 //
220 // returns the average of all the data bucket values for the metric/resource
221 // pair "metric_num" and "resource_num", returns NaN value on error 
222 //
223 extern visi_sampleType visi_AverageValue(int metric_num, int resource_num);
224
225 //
226 // returns the sum of all the data bucket values for the metric/resource
227 // pair "metric_num" and "resource_num", returns NaN value on error 
228 //
229 extern visi_sampleType visi_SumValue(int metric_num, int resource_num);
230
231 //
232 // returns the data value in bucket "bucket_num" for the metric/resource pair 
233 // "metric_num" and "resource_num", returns NaN value on error 
234 //
235 extern visi_sampleType visi_DataValue(int metric_num, int resource_num, 
236                                       int bucket_num);
237
238 //
239 // returns the data values for the metric/resource pair "metric_num" 
240 // and "resource_num", returns NaN value on error 
241 //
242 extern const visi_sampleType *visi_DataValues(int metric_num, int resource_num);
243
244 //
245 //  returns 1 if the data grid cell corresponding to metric_num   
246 //  and resource_num contains data, otherwise returns 0 
247 //
248 extern int visi_Valid(int metric_num, int resource_num);
249
250 //
251 //  returns 1 if the data collection has been enabled for metric_num   
252 //  and resource_num, otherwise returns 0  
253 //
254 extern int visi_Enabled(int metric_num, int resource_num);
255
256
257 //
258 //  returns the number of buckets in each data grid cell's histogram  
259 //
260 extern int visi_NumBuckets();
261
262 //
263 //  returns the buckets width (in seconds) of each data grid cell's histogram  
264 //
265 extern visi_timeType visi_BucketWidth();
266
267 //
268 // returns the first data bucket with valid data values 
269 //
270 extern int visi_FirstValidBucket(int metric_num, int resource_num);
271
272 //
273 // returns the last data bucket with valid data values 
274 //
275 extern int visi_LastBucketFilled(int metric_num,int resource_num);
276
277 //
278 // returns 1 if there are invalid spans of data between the first
279 // valid bucket and the last bucket filled, otherwise returns 0
280 //
281 extern int visi_InvalidSpans(int metric_num,int resource_num);
282
283 //
284 // returns the user data associated with metric_num and resource_num
285 // returns 0 on error
286 //
287 extern void *visi_GetUserData(int metric_num, int resource_num);
288
289 //
290 // sets the user data associated with metric_num and resource_num
291 // returns 1 on success, or returns 0 on error
292 //
293 extern int visi_SetUserData(int metric_num, int resource_num, void *data);
294
295 //
296 // print every stepth bucket to stderr
297 //
298 extern void visi_PrintDataBuckets(int step);
299
300 #if defined(__cplusplus)
301 };
302 #endif /* defined(__cplusplus) */
303
304 #endif