Update copyright to LGPL on all files
[dyninst.git] / dyninstAPI / h / BPatch_point.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_point_h_
33 #define _BPatch_point_h_
34
35 #include "BPatch_dll.h"
36 #include "BPatch_Vector.h"
37 #include "BPatch_eventLock.h"
38 #include "BPatch_snippet.h" // snippetOrder
39 #include "BPatch_Set.h"
40
41 class InstrucIter;
42 class process;
43 class instPoint;
44 class miniTramp;
45 class BPatch_thread;
46 class BPatch_image;
47 class BPatch_function;
48 class BPatch_memoryAccess;
49 class BPatchSnippetHandle;
50 class BPatch_basicBlockLoop;
51 class BPatch_process;
52 class BPatch_frame;
53 class BPatch_edge;
54
55 #include "Instruction.h"
56
57
58
59 /*
60  * Used to specify whether a snippet is to be called before the instructions
61  * at the point where it is inserted, or after.
62  */
63 typedef enum {
64     BPatch_callBefore,
65     BPatch_callAfter,
66     BPatch_callUnset
67 } BPatch_callWhen;
68
69 /*
70  * Provide these definitions for backwards compatability.
71  *
72  */
73 #define BPatch_entry BPatch_locEntry
74 #define BPatch_exit BPatch_locExit
75 #define BPatch_subroutine BPatch_locSubroutine
76 #define BPatch_longJump BPatch_locLongJump
77 #define BPatch_allLocations BPatch_locAllLocations
78 /* #define BPatch_instruction BPatch_locInstruction */
79 #define BPatch_arbitrary BPatch_locInstruction
80
81 #if defined (IBM_BPATCH_COMPAT)
82 #define BPatch_locBasicBlockLoopEntry BPatch_locLoopEntry
83 #define BPatch_locBasicBlockLoopExit BPatch_locLoopExit
84 #endif
85 /*
86  * Used with BPatch_function::findPoint to specify which of the possible
87  * instrumentation points within a procedure should be returned.
88  */
89 typedef enum eBPatch_procedureLocation {
90     BPatch_locEntry,
91     BPatch_locExit,
92     BPatch_locSubroutine,
93     BPatch_locLongJump,
94     BPatch_locAllLocations,
95     BPatch_locInstruction,
96     BPatch_locUnknownLocation,
97     BPatch_locSourceBlockEntry,         // not yet used
98     BPatch_locSourceBlockExit,          // not yet used
99     BPatch_locSourceLoopEntry,          // not yet used
100     BPatch_locSourceLoopExit,           // not yet used
101     BPatch_locBasicBlockEntry,          // not yet used
102     BPatch_locBasicBlockExit,           // not yet used
103     BPatch_locSourceLoop,               // not yet used
104     BPatch_locLoopEntry,        
105     BPatch_locLoopExit,
106     BPatch_locLoopStartIter,
107     BPatch_locLoopEndIter,
108     BPatch_locVarInitStart,             // not yet used
109     BPatch_locVarInitEnd,               // not yet used
110     BPatch_locStatement         // not yet used
111 } BPatch_procedureLocation;
112
113
114 /* VG (09/07/01) Created */
115
116 typedef enum BPatch_opCode {
117   BPatch_opLoad,
118   BPatch_opStore,
119   BPatch_opPrefetch
120 } BPatch_opCode;
121
122 /* VG(09/17/01) Added memory access pointer */
123
124 /* VG(11/06/01) Moved constructor to implementation file because it
125    needs to link instPoint back pointer (and we don't want to include
126    that here) */
127
128 #ifdef DYNINST_CLASS_NAME
129 #undef DYNINST_CLASS_NAME
130 #endif
131 #define DYNINST_CLASS_NAME BPatch_point
132
133 class BPATCH_DLL_EXPORT BPatch_point : public BPatch_eventLock {
134     friend class BPatch_process;
135     friend class BPatch_binaryEdit;
136     friend class BPatch_addressSpace;
137     friend class BPatch_image;
138     friend class BPatch_function;
139     friend class BPatch_basicBlock;
140     friend class BPatch_basicBlockLoop;
141     friend class BPatch_flowGraph; // Access to setLoop
142     friend class BPatch_asyncEventHandler;
143     friend class process;
144     friend class BPatch_edge;
145     friend class BPatch_snippet;
146     
147     static BPatch_point* createInstructionInstPoint(//BPatch_process *proc,
148                                                     BPatch_addressSpace *addSpace,
149                                                     void*address,
150                                                     BPatch_function* bpf = NULL);
151     // Create a set of points, all that match a given op in the given instruciter.
152
153     static BPatch_Vector<BPatch_point *> *getPoints(const BPatch_Set<BPatch_opCode> &ops,
154                                                     InstrucIter &ii,
155                                                     BPatch_function *bpf);
156
157     BPatch_addressSpace *addSpace;
158     AddressSpace *lladdSpace;
159     BPatch_function     *func;
160     BPatch_basicBlockLoop *loop;
161     instPoint   *point;
162
163     BPatch_procedureLocation pointType;
164     BPatch_memoryAccess *memacc;
165     // Instruction constructor...
166     BPatch_point(BPatch_addressSpace *_addSpace, BPatch_function *_func, 
167                  instPoint *_point, BPatch_procedureLocation _pointType,
168                  AddressSpace *as);
169
170     // Edge constructor...
171     BPatch_point(BPatch_addressSpace *_addSpace, BPatch_function *_func,
172                  BPatch_edge *_edge, instPoint *_point, AddressSpace *as);
173
174
175     void setLoop(BPatch_basicBlockLoop *l);
176
177     // We often create a point with the arbitrary point type,
178     // and later need to override it to a specific type (e.g., loop entry)
179     void overrideType(BPatch_procedureLocation loc) { pointType = loc; }
180
181     //  dynamic_call_site_flag:
182     //    0:  is not dynamic call site
183     //    1:  is dynamic call site
184     //    2:  dynamic status unknown (initial value)
185     int dynamic_call_site_flag;
186
187     //  a snippet used in monitoring of dynamic calls
188     //  maybe we want BPatchSnippetHandle here
189     miniTramp *dynamic_point_monitor_func;
190
191     instPoint * getPoint() {return point;}
192
193     BPatch_Vector<BPatchSnippetHandle *> preSnippets;
194     BPatch_Vector<BPatchSnippetHandle *> postSnippets;
195     BPatch_Vector<BPatchSnippetHandle *> allSnippets;
196
197     // If we're edge inst
198     BPatch_edge *edge_;
199
200     void recordSnippet(BPatch_callWhen, BPatch_snippetOrder,
201                        BPatchSnippetHandle*);
202
203     void attachMemAcc(BPatch_memoryAccess *memacc);
204
205     AddressSpace *getAS();
206
207 public:
208     //~BPatch_point() { delete memacc; };
209
210     // Hack to get edge information. DO NOT USE.
211     const BPatch_edge *edge() const { return edge_; }
212
213     // Get the loop ID
214     API_EXPORT(Int, (),
215                
216     BPatch_basicBlockLoop *, getLoop, ());
217
218     //  BPatch_point::getPointType
219     //  
220     API_EXPORT(Int, (),
221     BPatch_procedureLocation,getPointType,());
222
223     //  BPatch_point::getFunction
224     //  Returns function to which this point belongs
225
226     API_EXPORT(Int, (),
227
228     BPatch_function *,getFunction,());
229
230     //  BPatch_point::getCalledFunction
231     //  Returns a BPatch_function representing the function being called at this point.
232     //  If this point is not a call site, returns NULL. 
233
234     API_EXPORT(Int, (),
235
236     BPatch_function *,getCalledFunction,());
237
238     //  BPatch_point::getAddress
239     //  Returns the address of this point in the mutatee
240
241     API_EXPORT(Int, (),
242
243     void *,getAddress,());
244
245     //  BPatch_point::getMemoryAccess
246     //  
247
248     API_EXPORT(Int, (),
249
250     const BPatch_memoryAccess *,getMemoryAccess,());
251
252     API_EXPORT(Int, (),
253                Dyninst::InstructionAPI::Instruction::Ptr, getInsnAtPoint, ());
254
255
256     //  BPatch_point::getCurrentSnippets
257     //  
258     // to get all current snippets at this point
259
260     API_EXPORT(Int, (),
261
262     const BPatch_Vector<BPatchSnippetHandle *>,getCurrentSnippets,());
263
264     //  BPatch_point::getCurrentSnippets
265     //  
266     // to get all current snippets as defined by when at this point
267
268     API_EXPORT(ByWhen, (when),
269
270     const BPatch_Vector<BPatchSnippetHandle *>,getCurrentSnippets,(BPatch_callWhen when));
271
272
273     //  BPatch_point::getLiveRegisters
274     //  
275     //  Get Live registers at this point
276
277     API_EXPORT(Int, (liveRegs),
278
279     bool, getLiveRegisters, (std::vector<BPatch_register> &liveRegs));
280
281   
282     //  BPatch_point::isDynamic
283     //  
284     //  isDynamic() returns true if this is a dynamic call site
285     //  (eg a call site where a func call is made via func ptr)
286
287     API_EXPORT(Int, (),
288
289     bool,isDynamic,());
290
291     //  BPatch_point::monitorCalls
292     //  
293     //  monitorCalls(BPatch_function *cbFuncInUserLibrary)
294     //  Applies only to dynamic call sites (returns false if this BPatch_point
295     //  is not a dynamic call site).  Inserts a call to the user-written function
296     //  cbFuncInUserLibrary(), which must exist in a user defined library,
297     //  at this call site.  cbFuncInUserLibrary must adhere to the prototype:
298     //  void cbFuncInUserLibrary(void *callee_address, void *callSite_address).
299     //
300     // Returns handle on success, NULL on failure
301
302     API_EXPORT(Int, (f),
303
304     void *,monitorCalls,(BPatch_function *f = NULL));
305
306     //  BPatch_point::stopMonitoring
307     //  If this point, as a dynamic call site, was being monitored, turns off monitoring
308     //  <handle> is the handle returned my monitorCalls()
309
310     API_EXPORT(Int, (),
311
312     bool,stopMonitoring,());
313
314     //  BPatch_point::getDisplacedInstructions
315     //  Returns the instructions to be relocated when instrumentation is inserted
316     //  at this point.  Returns the number of bytes taken up by these instructions.
317
318     API_EXPORT(Int, (maxSize, insns),
319
320     int,getDisplacedInstructions,(int maxSize, void *insns));
321
322     //  BPatch_point::usesTrap_NP
323     //  Returns true if this point is or would be instrumented with a trap, rather
324     //  than a jump to the base tramp, false otherwise.  On platforms that do not
325     //   use traps (everything other than x86), it always returns false;
326
327     API_EXPORT(Int, (),
328
329     bool,usesTrap_NP,());
330
331     //  BPatch_point::getCFTarget
332     //  Returns true if the point corresponds to a control flow
333     //  instruction whose target can be statically determined, in
334     //  which case "target" is set to the target of the control flow
335     //  instruction
336     API_EXPORT(Int, (targets),
337     bool, getCFTarget, (BPatch_Vector<Dyninst::Address> *targets));
338
339 #ifdef IBM_BPATCH_COMPAT
340     void *getPointAddress() { return getAddress(); }
341     int getPointLine() { return -1; }
342     BPatch_function *getContainingFunction() { return const_cast<BPatch_function*>(getFunction()); };
343 #endif
344
345 };
346
347 #endif /* _BPatch_point_h_ */