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