BPatch functions that block are now locked (on a finer grain than the rest of the...
[dyninst.git] / dyninstAPI / h / BPatch.h
1 /*
2  * Copyright (c) 1996-2004 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 _BPatch_h_
43 #define _BPatch_h_
44
45 #include <stdio.h>
46 #include "BPatch_dll.h"
47 #include "BPatch_Vector.h"
48 #include "BPatch_thread.h"
49 #include "BPatch_type.h"
50 #include "BPatch_eventLock.h"
51
52 #ifdef mips_unknown_ce2_11 //ccw 28 july 2000
53 #include "remoteDevice.h"
54 #endif
55
56 class BPatch_typeCollection;
57 class BPatch_libInfo;
58 class BPatch_module;
59 class BPatch_point;
60 class int_function;
61 class BPatch_asyncEventHandler;
62
63 typedef enum {
64     BPatchFatal, BPatchSerious, BPatchWarning, BPatchInfo
65 } BPatchErrorLevel;
66
67 typedef void (*BPatchErrorCallback)(BPatchErrorLevel severity,
68                                     int number,
69                                     const char **params);
70
71 typedef void (*BPatchDynLibraryCallback)(BPatch_thread *thr,
72                                          BPatch_module *mod,
73                                          bool load);
74
75 typedef void (*BPatchForkCallback)(BPatch_thread *parent, BPatch_thread *child);
76
77 typedef void (*BPatchExecCallback)(BPatch_thread *proc);
78
79 typedef void (*BPatchExitCallback)(BPatch_thread *proc,
80                                    BPatch_exitType exit_type);
81
82 typedef void (*BPatchSignalCallback)(BPatch_thread *proc, int sigNum);
83
84 typedef void (*BPatchOneTimeCodeCallback)(BPatch_thread *proc, void *userData, void *returnValue);
85
86 #ifdef IBM_BPATCH_COMPAT
87 typedef void *BPatch_Address;
88 typedef void (*BPatchLoggingCallback)(char *msg, int);
89 extern void setLogging_NP(BPatchLoggingCallback func, int);
90
91 typedef void (*BPatchThreadEventCallback)(BPatch_thread *thr, void *arg1, void *arg2);
92
93 #define BP_OK                   0
94 #define BP_Pending              1
95 #define BP_Delayed              2
96 #define BP_child                3
97 #define BP_state                4
98 #define BP_pthdbBadContext      5
99 #define BP_lastCode             6
100
101 extern int eCodes[BP_lastCode];
102
103 #endif
104
105 //  BPatch_stats is a collection of instrumentation statistics.
106 //  Introduced to export this information to paradyn, which 
107 //  produces a summary of these numbers upon application exit.
108 //  It probably makes more sense to maintain such numbers on a
109 //  per-process basis.  But is set up globally due to historical
110 //  precendent.   
111
112 typedef struct {
113   unsigned int pointsUsed;
114   unsigned int totalMiniTramps;
115   unsigned int trampBytes;
116   unsigned int ptraceOtherOps;
117   unsigned int ptraceOps;
118   unsigned int ptraceBytes;
119   unsigned int insnGenerated;
120 } BPatch_stats;
121
122 #ifdef DYNINST_CLASS_NAME
123 #undef DYNINST_CLASS_NAME
124 #endif
125 #define DYNINST_CLASS_NAME BPatch
126 class BPATCH_DLL_EXPORT BPatch : public BPatch_eventLock {
127     friend class BPatch_thread;
128     friend class BPatch_point;
129     friend class process;
130     friend class int_function;
131
132     BPatch_libInfo      *info;
133
134     BPatchErrorCallback         errorHandler;
135     BPatchDynLibraryCallback    dynLibraryCallback;
136     BPatchForkCallback          postForkCallback;
137     BPatchForkCallback          preForkCallback;
138     BPatchExecCallback          execCallback;
139     BPatchExitCallback          exitCallback;
140     BPatchOneTimeCodeCallback   oneTimeCodeCallback;
141     bool        typeCheckOn;
142     int         lastError;
143     bool        debugParseOn;
144     bool        baseTrampDeletionOn;
145
146     bool        getThreadEvent(bool block);
147     bool        getThreadEventOnly(bool block);
148     bool        havePendingEvent();
149
150     /* If true, trampolines can recurse to their heart's content.
151        Defaults to false */
152     bool        trampRecursiveOn;
153     bool        forceRelocation_NP;
154     /* If true, allows automatic relocation of functions if dyninst
155        deems it necessary.  Defaults to true */
156     bool        autoRelocation_NP;
157
158     /* If true, override requests to block while waiting for events,
159        polling instead */
160     bool asyncActive;
161
162     /* If true, deep parsing (anything beyond symtab info) is delayed until
163        accessed */
164     /* Note: several bpatch constructs have "access everything" behavior, 
165        which will trigger full parsing. This should be looked into. */
166     bool delayedParsing_;
167
168     BPatch_stats stats;
169     void updateStats();
170
171
172 public:
173     static BPatch                *bpatch;
174
175     BPatch_builtInTypeCollection *builtInTypes;
176     BPatch_typeCollection        *stdTypes;
177     BPatch_typeCollection        *APITypes; //API/User defined types
178     BPatch_type                  *type_Error;
179     BPatch_type                  *type_Untyped;
180     BPatch_asyncEventHandler     *eventHandler;
181
182 #ifdef mips_unknown_ce2_11 //ccw 28 july 2000
183     remoteDevice *rDevice;      //the ctor sets up the connection here and
184                                 //gets the tramptemplate from the CE device.
185 #endif
186
187     // The following are only to be called by the library:
188     //  These functions are not locked.
189     void registerProvisionalThread(int pid);
190     void registerForkedThread(int parentPid, int childPid, process *proc);
191     void registerForkingThread(int forkingPid, process *proc);
192     void registerExec(BPatch_thread *thread);
193     void registerNormalExit(BPatch_thread *thread, int exitcode);
194     void registerSignalExit(BPatch_thread *thread, int signalnum);
195     void registerThread(BPatch_thread *thread);
196     void unRegisterThread(int pid);
197     void launchDeferredOneTimeCode();
198
199     BPatch_thread *getThreadByPid(int pid, bool *exists = NULL);
200
201     static void reportError(BPatchErrorLevel severity, int number, const char *str);
202
203     void clearError() { lastError = 0; }
204     int getLastError() { return lastError; }
205     // End of functions that are for internal use only
206
207     public:
208
209     BPatch();
210
211     //  BPatch::~BPatch
212     //  destructor
213     API_EXPORT_DTOR(_dtor, (),
214
215     ~,BPatch,());
216
217     static const char *getEnglishErrorString(int number);
218     static void formatErrorString(char *dst, int size,
219                                   const char *fmt, const char **params);
220
221     // BPatch::isTypeChecked:
222     // returns whether type checking is on.
223     API_EXPORT(Int, (),
224
225     bool,isTypeChecked,());
226
227     // BPatch::parseDebugInfo:
228     // returns whether debugging information is set to be parsed
229     API_EXPORT(Int, (),
230
231     bool,parseDebugInfo,());
232
233     // BPatch::baseTrampDeletion:
234     // returns whether base trampolines are set to be deleted
235     API_EXPORT(Int, (),
236
237     bool,baseTrampDeletion,());
238
239     // BPatch::isTrampRecursive:
240     // returns whether trampolines are set to handle recursive instrumentation
241     API_EXPORT(Int, (),
242
243     bool,isTrampRecursive,());
244
245     // BPatch::hasForcedRelocation_NP:
246     // returns whether all instrumented functions will be relocated
247     API_EXPORT(Int, (),
248
249     bool,hasForcedRelocation_NP,());
250
251     // BPatch::autoRelocationsOn:
252     // returns whether functions will be relocated when appropriate
253     API_EXPORT(Int, (),
254
255     bool,autoRelocationOn,());
256
257     // BPatch::delayedParsingOn:
258     // returns whether inst info is parsed a priori, or on demand
259     API_EXPORT(Int, (),
260
261     bool,delayedParsingOn,());
262
263
264     //  User-specified callback functions...
265
266     //  BPatch::registerErrorCallback:
267     //  Register error handling/reporting callback
268     API_EXPORT(Int, (function),
269
270     BPatchErrorCallback, registerErrorCallback,(BPatchErrorCallback function));
271
272     //  BPatch::registerDynLibraryCallback:
273     //  Register callback for new library events (eg. load)
274     API_EXPORT(Int, (func),
275
276     BPatchDynLibraryCallback, registerDynLibraryCallback,(BPatchDynLibraryCallback func));
277
278     //  BPatch::registerPostForkCallback:
279     //  Register callback to handle mutatee fork events (before fork)
280     API_EXPORT(Int, (func),
281
282     BPatchForkCallback, registerPostForkCallback,(BPatchForkCallback func));
283
284     //  BPatch::registerPreForkCallback:
285     //  Register callback to handle mutatee fork events (before fork)
286     API_EXPORT(Int, (func),
287
288     BPatchForkCallback, registerPreForkCallback,(BPatchForkCallback func));
289
290     //  BPatch::registerExecCallback:
291     //  Register callback to handle mutatee exec events 
292     API_EXPORT(Int, (func),
293
294     BPatchExecCallback, registerExecCallback,(BPatchExecCallback func));
295
296     //  BPatch::registerExitCallback:
297     //  Register callback to handle mutatee exit events 
298     API_EXPORT(Int, (func),
299
300     BPatchExitCallback, registerExitCallback,(BPatchExitCallback func));
301
302     //  BPatch::registerOneTimeCodeCallback:
303     //  Register callback to run at completion of oneTimeCode 
304     API_EXPORT(Int, (func),
305
306     BPatchOneTimeCodeCallback, registerOneTimeCodeCallback,(BPatchOneTimeCodeCallback func));
307
308     //  BPatch::getThreads:
309     //  Get a vector of all threads in mutatee process
310     API_EXPORT(Int, (),
311
312     BPatch_Vector<BPatch_thread*> *,getThreads,());
313
314     //
315     //  General BPatch parameter settings:
316     //
317     
318     //  BPatch::setDebugParsing:
319     //  Turn on/off parsing of debug section(s)
320     API_EXPORT_V(Int, (x),
321
322     void,setDebugParsing,(bool x));
323
324     //  BPatch::setBaseTrampDeletion:
325     //  Turn on/off deletion of base tramp
326     API_EXPORT_V(Int, (x),
327
328     void,setBaseTrampDeletion,(bool x));
329
330     //  BPatch::setTypeChecking:
331     //  Turn on/off type checking
332     API_EXPORT_V(Int, (x),
333
334     void,setTypeChecking,(bool x));
335
336     //  BPatch::setTrampRecursive:
337     //  Turn on/off recursive trampolines
338     API_EXPORT_V(Int, (x),
339
340     void,setTrampRecursive,(bool x));
341
342     //  BPatch::setForcedRelocation_NP:
343     //  Turn on/off forced relocation of instrumted functions
344     API_EXPORT_V(Int, (x),
345
346     void,setForcedRelocation_NP,(bool x));
347
348     //  BPatch::setAutoRelocation_NP:
349     //  Turn on/off function relocations, performed when necessary
350     API_EXPORT_V(Int, (x),
351
352     void,setAutoRelocation_NP,(bool x));
353
354     //  BPatch::setDelayedParsing:
355     //  Turn on/off delayed parsing
356     API_EXPORT_V(Int, (x),
357
358     void,setDelayedParsing,(bool x));
359
360
361     // BPatch::createProcess:
362     // Create a new mutatee process
363     API_EXPORT(Int, (path, argv, envp, stdin_fd, stdout_fd, stderr_fd),
364
365     BPatch_thread *,createProcess,(const char *path,
366                                    const char *argv[],
367                                    const char *envp[] = NULL,
368                                    int stdin_fd=0,
369                                    int stdout_fd=1,
370                                    int stderr_fd=2));
371
372     // BPatch::attachProcess:
373     // Attach to mutatee process
374     API_EXPORT(Int, (path, pid),
375
376     BPatch_thread *,attachProcess,(const char *path, int pid));
377
378     // BPatch::createEnum:
379     // Create Enum types. 
380     API_EXPORT(Int, (name, elementNames, elementIds),
381
382     BPatch_type *,createEnum,(const char * name, BPatch_Vector<char *> elementNames,
383                               BPatch_Vector<int> elementIds));
384
385     // BPatch::createEnum:
386     // API selects elementIds
387     API_EXPORT(AutoId, (name, elementNames),
388
389     BPatch_type *,createEnum,(const char * name, BPatch_Vector<char *> elementNames));
390
391     // BPatch::createStruct:
392     // Create Struct types. 
393     API_EXPORT(Int, (name, fieldNames, fieldTypes),
394
395     BPatch_type *,createStruct,(const char * name, BPatch_Vector<char *> fieldNames,
396                                 BPatch_Vector<BPatch_type *> fieldTypes));
397
398     // BPatch::createUnion:
399     // Create Union types. 
400     API_EXPORT(Int, (name, fieldNames, fieldTypes),
401
402     BPatch_type *,createUnion,(const char * name, BPatch_Vector<char *> fieldNames,
403                                BPatch_Vector<BPatch_type *> fieldTypes));
404
405     // BPatch::createArray:
406     // Creates BPatch_array type or symtyperanges ( scalars with upper and
407     //lower bound).
408     API_EXPORT(Int, (name, ptr, low, hi),
409
410     BPatch_type *,createArray,(const char * name, BPatch_type * ptr,
411                                unsigned int low, unsigned int hi));
412
413     // BPatch::createPointer:
414     // Creates BPatch_pointer types      
415     API_EXPORT(Int, (name, ptr, size),
416
417     BPatch_type *,createPointer,(const char * name, BPatch_type * ptr,
418                                  int size = sizeof(void *)));
419
420     // BPatch::createScalar:
421     // Creates BPatch_scalar types
422     API_EXPORT(Int, (name, size),
423
424     BPatch_type *,createScalar,(const char * name, int size));
425     
426     // BPatch::createTypedef:
427     // Creates typedefs.
428     API_EXPORT(Int, (name, ptr),
429
430     BPatch_type *,createTypedef,(const char * name, BPatch_type * ptr));
431          
432     //  Polling/waiting functions 
433     API_EXPORT(Int, (),
434
435     bool,pollForStatusChange,());
436
437     public:
438     //  Since these two functions block, they do not obtain locks
439     //  on this layer (see C file) 
440     bool        waitForStatusChange();
441     bool        waitUntilStopped(BPatch_thread *appThread);
442
443     //  BPatch::getBPatchStatistics:
444     //  Get Instrumentation statistics
445     API_EXPORT(Int, (),
446
447     BPatch_stats &,getBPatchStatistics,());
448
449 #ifdef IBM_BPATCH_COMPAT
450     BPatchThreadEventCallback           RPCdoneCallback;
451
452     API_EXPORT(Int, (),
453     int,getLastErrorCode,());
454
455     API_EXPORT(Int, (cb),
456     BPatchThreadEventCallback,registerDetachDoneCallback,(BPatchThreadEventCallback cb)); 
457
458     API_EXPORT(Int, (cb),
459     BPatchThreadEventCallback,registerSnippetRemovedCallback,(BPatchThreadEventCallback cb));
460
461     API_EXPORT(Int, (func, sigNum),
462     BPatchExitCallback,registerSignalCallback,(BPatchThreadEventCallback func, int sigNum)); 
463
464     API_EXPORT(Int, (func),
465     BPatchExitCallback,registerExitCallback,(BPatchThreadEventCallback func));
466
467     API_EXPORT(Int, (cb),
468     BPatchThreadEventCallback,registerRPCTerminationCallback,(BPatchThreadEventCallback cb));
469
470 #endif
471
472 };
473
474
475 #if defined(IBM_BPATCH_COMPAT) && (defined(rs6000_ibm_aix4_1) || defined(rs6000_ibm_aix5_1)) 
476 #include <sys/ldr.h>
477
478 typedef struct LD_INFO {
479   union {
480     struct ld_info32 {
481       __I_FIELDS(__I_INT32, __I_PTR32, __I_FP32, __I_EMPTY)
482     }ld_info32;
483     struct ld_info64 {
484       __I_FIELDS(__I_INT64, __I_PTR64, __I_FP64, uint ldinfo_flags;)
485     }ld_info64;
486   } ld_info;
487 } LD_INFO;
488
489 #define LD_32(a,b) (a->ld_info.ld_info32.b)
490 #define LD_64(a,b) (a->ld_info.ld_info64.b)
491
492 #endif // AIX IBM BPATCH
493
494 #endif /* _BPatch_h_ */