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