Update copyright to LGPL on all files
[dyninst.git] / dyninstAPI / h / BPatch.h
1 /*
2  * Copyright (c) 1996-2009 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  * By your use of Paradyn, you understand and agree that we (or any
12  * other person or entity with proprietary rights in Paradyn) are
13  * under no obligation to provide either maintenance services,
14  * update services, notices of latent defects, or correction of
15  * defects for Paradyn.
16  * 
17  * This library is free software; you can redistribute it and/or
18  * modify it under the terms of the GNU Lesser General Public
19  * License as published by the Free Software Foundation; either
20  * version 2.1 of the License, or (at your option) any later version.
21  * 
22  * This library is distributed in the hope that it will be useful,
23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
25  * Lesser General Public License for more details.
26  * 
27  * You should have received a copy of the GNU Lesser General Public
28  * License along with this library; if not, write to the Free Software
29  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
30  */
31
32 #ifndef _BPatch_h_
33 #define _BPatch_h_
34
35 #include <stdio.h>
36 #include "BPatch_dll.h"
37 #include "BPatch_Vector.h"
38 #include "BPatch_thread.h"
39 #include "BPatch_type.h"
40 #include "BPatch_eventLock.h"
41 #include "BPatch_process.h"
42
43 class BPatch_typeCollection;
44 class BPatch_libInfo;
45 class BPatch_module;
46 class int_function;
47 class process;
48
49 //Keep old versions defined, that way someone can test if we're more
50 // at or more recent than version 5.1 with '#if defined(DYNINST_5_1)'
51 //If they want to get the current version, they should use DYNINST_MAJOR,
52 // DYNINST_MINOR, and DYNINST_SUBMINOR
53 #define DYNINST_5_1
54 #define DYNINST_5_2
55 #define DYNINST_6_0
56
57 #define DYNINST_MAJOR 6
58 #define DYNINST_MINOR 0
59 #define DYNINST_SUBMINOR 0
60
61 #ifdef IBM_BPATCH_COMPAT
62 typedef void *BPatch_Address;
63 #endif
64
65 //  BPatch_stats is a collection of instrumentation statistics.
66 //  Introduced to export this information to paradyn, which 
67 //  produces a summary of these numbers upon application exit.
68 //  It probably makes more sense to maintain such numbers on a
69 //  per-process basis.  But is set up globally due to historical
70 //  precendent.   
71
72 typedef struct {
73   unsigned int pointsUsed;
74   unsigned int totalMiniTramps;
75   unsigned int trampBytes;
76   unsigned int ptraceOtherOps;
77   unsigned int ptraceOps;
78   unsigned int ptraceBytes;
79   unsigned int insnGenerated;
80 } BPatch_stats;
81
82
83 class EventRecord;
84
85 #ifdef DYNINST_CLASS_NAME
86 #undef DYNINST_CLASS_NAME
87 #endif
88 #define DYNINST_CLASS_NAME BPatch
89 class BPATCH_DLL_EXPORT BPatch : public BPatch_eventLock {
90     friend class BPatch_thread;
91     friend class BPatch_process;
92     friend class BPatch_point;
93     friend class process;
94     friend class int_function;
95     friend class SignalHandler;
96     friend class BPatch_asyncEventHandler;
97     friend bool handleSigStopNInt(EventRecord &ev);
98
99     BPatch_libInfo *info; 
100
101     bool        typeCheckOn;
102     int         lastError;
103     bool        debugParseOn;
104     bool        baseTrampDeletionOn;
105
106     /* If true, trampolines can recurse to their heart's content.
107        Defaults to false */
108     bool        trampRecursiveOn;
109
110     bool        forceRelocation_NP;
111     /* If true, allows automatic relocation of functions if dyninst
112        deems it necessary.  Defaults to true */
113     bool        autoRelocation_NP;
114
115     /* If true, we save FPRs in situations we normally would 
116        Defaults to true */
117     bool saveFloatingPointsOn;
118
119     /* If true, we will use liveness calculations to avoid saving
120        registers on platforms that support it. 
121        Defaults to true. */
122     bool livenessAnalysisOn_;
123     /* How far through the CFG do we follow calls? */
124     int livenessAnalysisDepth_;
125
126     /* If true, override requests to block while waiting for events,
127        polling instead */
128     bool asyncActive;
129
130     /* If true, deep parsing (anything beyond symtab info) is delayed until
131        accessed */
132     /* Note: several bpatch constructs have "access everything" behavior, 
133        which will trigger full parsing. This should be looked into. */
134     bool delayedParsing_;
135
136     bool instrFrames;
137
138     BPatch_stats stats;
139     void updateStats();
140
141         /* this is used to denote the fully qualified name of the prelink command on linux */
142         char *systemPrelinkCommand;
143
144         // Wrapper - start process running if it was not deleted. 
145         // We use this at the end of callbacks to user code, since those
146         // callbacks may delete BPatch objects. 
147         void continueIfExists(int pid);
148
149     /* flag that is set when a mutatee's runnning status changes,
150        for use with pollForStatusChange */
151    bool mutateeStatusChange;
152    bool waitingForStatusChange;
153
154    /* Internal notification file descriptor - a pipe */
155    int notificationFDOutput_;
156    int notificationFDInput_;
157    // Easier than non-blocking reads... there is either 1 byte in the pipe or 0.
158    bool FDneedsPolling_;
159    public:  
160    /* And auxiliary functions for the above */
161    /* These are NOT part of the API, do not use externally */
162    void signalNotificationFD(); // Called when an event happens
163    void clearNotificationFD(); // Called during poll/waitForStatusChange
164    void createNotificationFD(); // Creates the FD
165    
166 public:
167     static BPatch                *bpatch;
168
169         static BPatch *getBPatch();
170     BPatch_builtInTypeCollection *builtInTypes;
171     BPatch_typeCollection        *stdTypes;
172     BPatch_typeCollection        *APITypes; //API/User defined types
173     BPatch_type                  *type_Error;
174     BPatch_type                  *type_Untyped;
175
176     // The following are only to be called by the library:
177     //  These functions are not locked.
178     void registerProvisionalThread(int pid);
179     void registerForkedProcess(process *parentProc, process *childProc);
180     void registerForkingProcess(int forkingPid, process *proc);
181
182     void registerExecExit(process *proc);
183     void registerExecCleanup(process *proc, char *arg0);
184
185     void registerNormalExit(process *proc, int exitcode);
186     void registerSignalExit(process *proc, int signalnum);
187
188     void registerThreadExit(process *proc, long tid, bool exiting);
189     bool registerThreadCreate(BPatch_process *proc, BPatch_thread *newthr);
190
191     void registerProcess(BPatch_process *process, int pid=0);
192     void unRegisterProcess(int pid, BPatch_process *proc);
193
194     void launchDeferredOneTimeCode();
195
196     void registerLoadedModule(process *process, mapped_module *mod);
197     void registerUnloadedModule(process *process, mapped_module *mod);
198
199     BPatch_thread *getThreadByPid(int pid, bool *exists = NULL);
200     BPatch_process *getProcessByPid(int pid, bool *exists = NULL);
201
202     static void reportError(BPatchErrorLevel severity, int number, const char *str);
203
204     void clearError() { lastError = 0; }
205     int getLastError() { return lastError; }
206     // End of functions that are for internal use only
207
208     public:
209
210     BPatch();
211
212     //  BPatch::~BPatch
213     //  destructor
214     API_EXPORT_DTOR(_dtor, (),
215
216     ~,BPatch,());
217
218     static const char *getEnglishErrorString(int number);
219     static void formatErrorString(char *dst, int size,
220                                   const char *fmt, const char * const *params);
221
222     // BPatch::isTypeChecked:
223     // returns whether type checking is on.
224     API_EXPORT(Int, (),
225
226     bool,isTypeChecked,());
227
228     // BPatch::parseDebugInfo:
229     // returns whether debugging information is set to be parsed
230     API_EXPORT(Int, (),
231
232     bool,parseDebugInfo,());
233
234     // BPatch::baseTrampDeletion:
235     // returns whether base trampolines are set to be deleted
236     API_EXPORT(Int, (),
237
238     bool,baseTrampDeletion,());
239
240     // BPatch::setPrelinkCommand
241     // sets the fully qualified path name of the prelink command
242     API_EXPORT_V(Int, (command),
243
244         void,setPrelinkCommand,(char *command));
245
246     // BPatch::getPrelinkCommand
247     // gets the fully qualified path name of the prelink command
248     API_EXPORT(Int, (),
249
250         char*,getPrelinkCommand,());
251
252     // BPatch::isTrampRecursive:
253     // returns whether trampolines are set to handle recursive instrumentation
254     API_EXPORT(Int, (),
255
256     bool,isTrampRecursive,());
257
258     // BPatch::isMergeTramp:
259     // returns whether base tramp and mini-tramp is merged
260     API_EXPORT(Int, (),
261
262     bool,isMergeTramp,());        
263
264     // BPatch::saveFPROn:
265     // returns whether base tramp and mini-tramp is merged
266     API_EXPORT(Int, (),
267
268     bool,isSaveFPROn,());        
269
270     // BPatch::hasForcedRelocation_NP:
271     // returns whether all instrumented functions will be relocated
272     API_EXPORT(Int, (),
273
274     bool,hasForcedRelocation_NP,());
275
276     // BPatch::autoRelocationsOn:
277     // returns whether functions will be relocated when appropriate
278     API_EXPORT(Int, (),
279
280     bool,autoRelocationOn,());
281
282
283     // BPatch::delayedParsingOn:
284     // returns whether inst info is parsed a priori, or on demand
285     API_EXPORT(Int, (),
286
287     bool,delayedParsingOn,());
288
289     // Liveness...
290     API_EXPORT(Int, (),
291     bool, livenessAnalysisOn, ());
292
293     API_EXPORT(Int, (),
294                int, livenessAnalysisDepth, ());
295
296     //  User-specified callback functions...
297
298     //  BPatch::registerErrorCallback:
299     //  Register error handling/reporting callback
300     API_EXPORT(Int, (function),
301
302     BPatchErrorCallback, registerErrorCallback,(BPatchErrorCallback function));
303
304     //  BPatch::registerDynLibraryCallback:
305     //  Register callback for new library events (eg. load)
306     API_EXPORT(Int, (func),
307
308     BPatchDynLibraryCallback, registerDynLibraryCallback,(BPatchDynLibraryCallback func));
309
310     //  BPatch::registerPostForkCallback:
311     //  Register callback to handle mutatee fork events (before fork)
312     API_EXPORT(Int, (func),
313
314     BPatchForkCallback, registerPostForkCallback,(BPatchForkCallback func));
315
316     //  BPatch::registerPreForkCallback:
317     //  Register callback to handle mutatee fork events (before fork)
318     API_EXPORT(Int, (func),
319
320     BPatchForkCallback, registerPreForkCallback,(BPatchForkCallback func));
321
322     //  BPatch::registerExecCallback:
323     //  Register callback to handle mutatee exec events 
324     API_EXPORT(Int, (func),
325     BPatchExecCallback, registerExecCallback,(BPatchExecCallback func));
326
327     //  BPatch::registerExitCallback:
328     //  Register callback to handle mutatee exit events 
329     API_EXPORT(Int, (func),
330
331     BPatchExitCallback, registerExitCallback,(BPatchExitCallback func));
332
333     //  BPatch::registerOneTimeCodeCallback:
334     //  Register callback to run at completion of oneTimeCode 
335     API_EXPORT(Int, (func),
336     BPatchOneTimeCodeCallback, registerOneTimeCodeCallback,(BPatchOneTimeCodeCallback func));
337
338     //  BPatch::registerThreadEventCallback
339     //  Registers a callback to run when a thread is created
340     API_EXPORT(Int, (type,cb),
341     bool,registerThreadEventCallback,(BPatch_asyncEventType type, 
342                                       BPatchAsyncThreadEventCallback cb));
343
344     //  BPatch::removeThreadEventCallback
345     //  Registers a callback to run when a thread is destroyed
346     API_EXPORT(Int, (type,cb),
347     bool,removeThreadEventCallback,(BPatch_asyncEventType type,
348                                     BPatchAsyncThreadEventCallback cb));
349
350     //  BPatch::registerDynamicCallCallback
351     //  Specifies a user-supplied function to be called when a dynamic call is
352     //  executed.
353
354     API_EXPORT(Int, (cb),
355     bool,registerDynamicCallCallback,(BPatchDynamicCallSiteCallback cb));
356
357     API_EXPORT(Int, (cb),
358     bool,removeDynamicCallCallback,(BPatchDynamicCallSiteCallback cb));
359
360
361     //  BPatch::registerUserEventCallback
362     //  
363     //  Specifies a user defined function to call when a "user event" 
364     //  occurs, user events are trigger by calls to the function 
365     //  DYNINSTuserMessage(void *, int) in the runtime library.
366     //  
367     //  BPatchUserEventCallback is:
368     //  void (*BPatchUserEventCallback)(void *msg, unsigned int msg_size);
369
370     API_EXPORT(Int, (cb),
371     bool,registerUserEventCallback,(BPatchUserEventCallback cb)); 
372
373     API_EXPORT(Int, (cb),
374     bool,removeUserEventCallback,(BPatchUserEventCallback cb));
375
376     // BPatch::registerSignalHandlerCallback 
377     // 
378     // If the mutator produces a signal matching an element of
379     // signal_numbers, the callback is invoked, returning the point
380     // that caused the exception, the signal number, and a Vector
381     // representing the address of signal handler(s) in the mutatee
382     // for the exception.  In Windows this is the handler stack, each
383     // function of which is invoked until one is found that agrees to
384     // handle the exception.  In Unix there will be at most one
385     // handler for the signal number, the handler registered with
386     // syscalls signal() or sigaction(), or the default system
387     // handler, in which case we return an empty vector.
388      API_EXPORT(Int, (cb,signal_numbers), 
389                 bool,registerSignalHandlerCallback,
390                 (BPatchSignalHandlerCallback cb, 
391                  BPatch_Set<long> *signal_numbers)); 
392
393      API_EXPORT(Int, (cb), 
394      bool,removeSignalHandlerCallback,(BPatchSignalHandlerCallback cb)); 
395
396
397     //  BPatch::getThreads:
398     //  Get a vector of all threads
399     API_EXPORT(Int, (),
400     BPatch_Vector<BPatch_thread*> *,getThreads,());
401
402     //  BPatch::getThreads:
403     //  Get a vector of all processes 
404     API_EXPORT(Int, (),
405     BPatch_Vector<BPatch_process*> *,getProcesses,());
406
407     //
408     //  General BPatch parameter settings:
409     //
410     
411     //  BPatch::setDebugParsing:
412     //  Turn on/off parsing of debug section(s)
413     API_EXPORT_V(Int, (x),
414
415     void,setDebugParsing,(bool x));
416
417     //  BPatch::setBaseTrampDeletion:
418     //  Turn on/off deletion of base tramp
419     API_EXPORT_V(Int, (x),
420
421     void,setBaseTrampDeletion,(bool x));
422
423     //  BPatch::setTypeChecking:
424     //  Turn on/off type checking
425     API_EXPORT_V(Int, (x),
426
427     void,setTypeChecking,(bool x));
428
429     API_EXPORT_V(Int, (b),
430     void,setInstrStackFrames,(bool b));
431
432     API_EXPORT(Int, (),
433     bool,getInstrStackFrames,());
434
435     //  BPatch::setTypeChecking:
436     //  Turn on/off line info truncating
437     API_EXPORT_V(Int, (x),
438
439     void,truncateLineInfoFilenames,(bool x));
440
441     //  BPatch::setTrampRecursive:
442     //  Turn on/off recursive trampolines
443     API_EXPORT_V(Int, (x),
444
445     void,setTrampRecursive,(bool x));
446
447     //  BPatch::setMergeTramp:
448     //  Turn on/off merged base & mini-tramps
449     API_EXPORT_V(Int, (x),
450
451     void,setMergeTramp,(bool x));
452
453     //  BPatch::setSaveFPR:
454     //  Turn on/off merged base & mini-tramps
455     API_EXPORT_V(Int, (x),
456
457     void,setSaveFPR,(bool x));
458
459     //  BPatch::setForcedRelocation_NP:
460     //  Turn on/off forced relocation of instrumted functions
461     API_EXPORT_V(Int, (x),
462
463     void,setForcedRelocation_NP,(bool x));
464
465     //  BPatch::setAutoRelocation_NP:
466     //  Turn on/off function relocations, performed when necessary
467     API_EXPORT_V(Int, (x),
468
469     void,setAutoRelocation_NP,(bool x));
470
471     //  BPatch::setDelayedParsing:
472     //  Turn on/off delayed parsing
473     API_EXPORT_V(Int, (x),
474
475     void,setDelayedParsing,(bool x));
476
477     // Liveness...
478     API_EXPORT_V(Int, (x),
479     void, setLivenessAnalysis, (bool x));
480
481     API_EXPORT_V(Int, (x),
482                  void, setLivenessAnalysisDepth, (int x));
483
484     // BPatch::processCreate:
485     // Create a new mutatee process
486     API_EXPORT(Int, (path, argv, envp, stdin_fd, stdout_fd, stderr_fd),
487     BPatch_process *,processCreate,(const char *path,
488                                     const char *argv[],
489                                     const char **envp = NULL,
490                                     int stdin_fd=0,
491                                     int stdout_fd=1,
492                                     int stderr_fd=2));
493
494     // BPatch::processAttach
495     // Attach to mutatee process
496     API_EXPORT(Int, (path, pid),
497     BPatch_process *,processAttach,(const char *path, int pid));
498
499     // BPatch::createProcess:
500     // Create a new mutatee process
501     API_EXPORT(Int, (path, argv, envp, stdin_fd, stdout_fd, stderr_fd),
502     BPatch_thread *,createProcess,(const char *path,
503                                    const char *argv[],
504                                    const char **envp = NULL,
505                                    int stdin_fd=0,
506                                    int stdout_fd=1,
507                                    int stderr_fd=2));
508
509     // BPatch::openBinary
510     // Open a binary for static instrumentation
511     //
512     // The second parameter really should be a boolean, but the value
513     // gets reset between the openBinary and openBinaryInt calls--is
514     // this a gcc bug???
515     // 
516     API_EXPORT(Int, (path, openDependencies), 
517                BPatch_binaryEdit *, openBinary, (const char *path, bool openDependencies = false));
518
519     // BPatch::attachProcess:
520     // Attach to mutatee process
521     API_EXPORT(Int, (path, pid),
522     BPatch_thread *,attachProcess,(const char *path, int pid));
523
524     // BPatch::createEnum:
525     // Create Enum types. 
526     API_EXPORT(Int, (name, elementNames, elementIds),
527
528     BPatch_type *,createEnum,(const char * name, BPatch_Vector<char *> &elementNames,
529                               BPatch_Vector<int> &elementIds));
530
531     // BPatch::createEnum:
532     // API selects elementIds
533     API_EXPORT(AutoId, (name, elementNames),
534
535     BPatch_type *,createEnum,(const char * name, BPatch_Vector<char *> &elementNames));
536
537     // BPatch::createStruct:
538     // Create Struct types. 
539     API_EXPORT(Int, (name, fieldNames, fieldTypes),
540
541     BPatch_type *,createStruct,(const char * name, BPatch_Vector<char *> &fieldNames,
542                                 BPatch_Vector<BPatch_type *> &fieldTypes));
543
544     // BPatch::createUnion:
545     // Create Union types. 
546     API_EXPORT(Int, (name, fieldNames, fieldTypes),
547
548     BPatch_type *,createUnion,(const char * name, BPatch_Vector<char *> &fieldNames,
549                                BPatch_Vector<BPatch_type *> &fieldTypes));
550
551     // BPatch::createArray:
552     // Creates BPatch_array type or symtyperanges ( scalars with upper and
553     //lower bound).
554     API_EXPORT(Int, (name, ptr, low, hi),
555
556     BPatch_type *,createArray,(const char * name, BPatch_type * ptr,
557                                unsigned int low, unsigned int hi));
558
559     // BPatch::createPointer:
560     // Creates BPatch_pointer types      
561     API_EXPORT(Int, (name, ptr, size),
562
563     BPatch_type *,createPointer,(const char * name, BPatch_type * ptr,
564                                  int size = sizeof(void *)));
565
566     // BPatch::createScalar:
567     // Creates BPatch_scalar types
568     API_EXPORT(Int, (name, size),
569
570     BPatch_type *,createScalar,(const char * name, int size));
571     
572     // BPatch::createTypedef:
573     // Creates typedefs.
574     API_EXPORT(Int, (name, ptr),
575
576     BPatch_type *,createTypedef,(const char * name, BPatch_type * ptr));
577          
578     // User programs are required to call pollForStatusChange or
579     // waitForStatusChange before user-level callback functions
580     // are executed (for example, fork, exit, or a library load). 
581
582     // Non-blocking form; returns immediately if no callback is
583     // ready, or executes callback(s) then returns.
584     API_EXPORT(Int, (),
585     bool,pollForStatusChange,());
586
587     // Blocks until a callback is ready.
588     API_EXPORT(Int, (),
589     bool,waitForStatusChange,());
590
591     // For user programs that block on other things as well,
592     // we provide a (simulated) file descriptor that can be added
593     // to a poll or select fdset. When a callback is prepared the BPatch
594     // layer writes to this fd, thus making poll/select return. The user
595     // program should then call pollForStatusChange. The BPatch layer
596     // will handle clearing the file descriptor; all the program must do 
597     // is call pollForStatusChange or waitForStatusChange.
598     API_EXPORT(Int, (),
599     int, getNotificationFD, ());
600
601     //  BPatch:: waitUntilStopped:
602     //  Block until specified process has stopped.
603     API_EXPORT(Int, (appThread),
604
605     bool,waitUntilStopped,(BPatch_thread *appThread));
606
607     //  BPatch::getBPatchStatistics:
608     //  Get Instrumentation statistics
609     API_EXPORT(Int, (),
610
611     BPatch_stats &,getBPatchStatistics,());
612
613
614     API_EXPORT_V(Int, (major, minor, subminor),
615     void ,getBPatchVersion,(int &major, int &minor, int &subminor));
616
617 };
618
619 #endif /* _BPatch_h_ */