Update copyright to LGPL on all files
[dyninst.git] / dyninstAPI / h / BPatch_image.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_image_h_
33 #define _BPatch_image_h_
34
35 #include "BPatch_dll.h"
36 #include "BPatch_sourceObj.h"
37 #include "BPatch_Vector.h"
38 //#include "BPatch_addressSpace.h"
39 #include "BPatch_point.h"
40 #include "BPatch_snippet.h"
41 #include "BPatch_module.h"
42 #include "BPatch_type.h"
43 #include "BPatch_eventLock.h"
44 #include "BPatch_process.h"
45 #include "BPatch_binaryEdit.h"
46 #include "BPatch_parRegion.h"
47 #include "dyntypes.h"
48
49 #include <vector>
50 #include <map>
51
52 typedef bool (*BPatchFunctionNameSieve)(const char *test,void *data);
53 class process;
54 class image;
55 class int_variable;
56
57 #ifdef IBM_BPATCH_COMPAT
58
59 typedef enum BPatch_LpModel {
60     LP32,      /* 32 bit image */
61     LP64,      /* 64 bit image */
62     UNKNOWN_LP /* cannot be determined */
63 };
64
65 #endif
66
67 class BPatch_statement;
68
69 #ifdef DYNINST_CLASS_NAME
70 #undef DYNINST_CLASS_NAME
71 #endif
72 #define DYNINST_CLASS_NAME BPatch_image
73
74 class BPATCH_DLL_EXPORT BPatch_image: public BPatch_sourceObj, public BPatch_eventLock {
75     friend class BPatch; // registerLoaded... callbacks
76     friend class BPatch_module; // access to findOrCreate...
77     friend class process; // Which also needs findOrCreate because we upcall when a library is loaded.
78     friend class BPatch_process;
79     friend class BPatch_addressSpace;
80     friend class BPatch_binaryEdit;
81
82     BPatch_variableExpr *findOrCreateVariable(int_variable *);
83  public:
84
85     // The following functions are for internal use by  the library only:
86     // As such, these functions are not locked.
87     //BPatch_image(BPatch_process *_proc);
88     BPatch_image(BPatch_addressSpace *addSpace);
89     BPatch_image();
90     virtual ~BPatch_image();
91
92     // End functions for internal use only
93
94     //  BPatch_image::getThr
95     //  
96     //  return the BPatch_thread associated with this image
97     API_EXPORT(Int, (),
98     BPatch_thread *,getThr,());
99
100
101     // BPatch_image::getAddressSpace()
102     //
103     //  return the BPatch_addressSpace associated with this image
104     API_EXPORT(Int, (),
105     BPatch_addressSpace *,getAddressSpace,());
106     
107
108     //  BPatch_image::getProcess
109     //  
110     //  return the BPatch_process associated with this image
111     API_EXPORT(Int, (),
112     BPatch_process *,getProcess,());
113
114
115     //  BPatch_image::getSourceObj
116     //  
117     //  fill a vector with children source objects (modules)
118     API_EXPORT(Int, (sources),
119
120     bool,getSourceObj,(BPatch_Vector<BPatch_sourceObj *> &sources));
121
122     //  BPatch_image::getObjParent
123     //  
124     //  Return the parent of this image (always NULL since this is the top level)
125     API_EXPORT(Int, (),
126
127     BPatch_sourceObj *,getObjParent,());
128
129     //  BPatch_image::getVariables
130     //  
131     //  Returns the global variables defined in this image
132     API_EXPORT(Int, (vars),
133
134     bool,getVariables,(BPatch_Vector<BPatch_variableExpr *> &vars));
135
136     //  BPatch_image::getProcedures
137     //  
138     //  Returns a list of all procedures in the image upon success,
139     //  NULL upon failure
140     API_EXPORT(Int, (incUninstrumentable),
141     BPatch_Vector<BPatch_function *> *,getProcedures,(bool incUninstrumentable = false));
142     
143     API_EXPORT(Int, (procs, incUninstrumentable),
144     bool,getProcedures,(BPatch_Vector<BPatch_function*> &procs, bool incUninstrumentable = false));
145
146     //  BPatch_image::getParRegions
147     //  
148     //  Returns a list of all procedures in the image upon success,
149     //  NULL upon failure
150     API_EXPORT(Int, (incUninstrumentable),
151
152     BPatch_Vector<BPatch_parRegion *> *,
153     getParRegions,(bool incUninstrumentable = false));
154
155     //  BPatch_image::getModules
156     //  
157     //  Returns a vector of all modules in this image
158     API_EXPORT(Int, (),
159     BPatch_Vector<BPatch_module *> *,getModules,());
160
161     API_EXPORT(Int, (mods),
162     bool,getModules,(BPatch_Vector<BPatch_module*> &mods));
163
164     //  BPatch_image::findModule
165     //  
166     //  Returns a module matching <name> if present in image, NULL if not found
167     //  if <substring_match> is set, the first module that has <name> as a substring
168     //  of its name is returned (eg, to find "libpthread.so.1", search for "libpthread" 
169     //  with substring_match set to true)
170     API_EXPORT(Int, (name, substring_match),
171
172     BPatch_module *,findModule,(const char *name, bool substring_match = false));
173
174     //  BPatch_image::getGlobalVariables
175     //  
176     //  Returns the global variables defined in this image
177     API_EXPORT(Int, (),
178
179     BPatch_Vector<BPatch_variableExpr *> *,getGlobalVariables,());
180
181     //  BPatch_image::createInstPointAtAddr
182     //  
183     //  Returns a pointer to a BPatch_point object representing an
184     //  instrumentation point at the given address.
185     //  Returns NULL on failure.
186     API_EXPORT(Int, (address),
187
188     BPatch_point *,createInstPointAtAddr,(void *address));
189
190     //  BPatch_image::createInstPointAtAddr
191     //  
192     //  Returns a pointer to a BPatch_point object representing an
193     //  instrumentation point at the given address. If the BPatch_function
194     //  argument is given it has to be the function that address belongs to or NULL.
195     //  The function is used to bypass the function that the address belongs to
196     //  The alternative argument is used to retrieve the point if the new point
197     //  intersects with another already existing one.
198     //  Returns NULL on failure.
199     API_EXPORT(WithAlt, (address, alternative, bpf),
200
201     BPatch_point *,createInstPointAtAddr,(void *address,
202                                           BPatch_point** alternative, 
203                                           BPatch_function* bpf = NULL)); 
204
205     //  BPatch_image::findFunction
206     //  
207     //  Returns a vector of functions matching <name>, if <name> is a regular
208     //  expression, a (slower) regex search will be performed.  
209     //  Returns NULL on failure.
210     API_EXPORT(Int, (name, funcs, showError, regex_case_sensitive, incUninstrumentable),
211
212     BPatch_Vector<BPatch_function*> *,findFunction,(const char *name,
213                                                     BPatch_Vector<BPatch_function*> &funcs, 
214                                                     bool showError=true,
215                                                     bool regex_case_sensitive=true,
216                                                     bool incUninstrumentable = false));
217                                                     
218     //  BPatch_image::findFunction
219     //  
220     //  Returns a vector of functions matching criterion specified by user defined
221     //  callback function bpsieve.
222     API_EXPORT(WithSieve, (funcs, bpsieve, user_data, showError, incUninstrumentable),
223
224     BPatch_Vector<BPatch_function *> *,
225        findFunction,(BPatch_Vector<BPatch_function *> &funcs,
226                      BPatchFunctionNameSieve bpsieve,
227                      void *user_data=NULL,
228                      int showError=0,
229                      bool incUninstrumentable = false));
230
231     //  BPatch_image::findFunction(Address)
232     //
233     //  Returns a function at a specified address
234     API_EXPORT(Int, (addr),
235                BPatch_function *, findFunction,(unsigned long addr));
236
237     API_EXPORT(Int, (addr, funcs),
238                bool, findFunction,(Dyninst::Address addr, 
239                                    BPatch_Vector<BPatch_function *> &funcs));
240
241     //  BPatch_image::findVariable
242     //  
243     //  Returns global variable matching <name> in the image.  NULL if not found.
244     API_EXPORT(Int, (name, showError),
245
246     BPatch_variableExpr *,findVariable,(const char *name, bool showError=true));
247
248     //  BPatch_image::findVariable
249     //  
250     //  Returns local variable matching name <nm> in function scope of 
251     //  provided BPatch_point.
252     API_EXPORT(InScope, (scp,nm),
253
254     BPatch_variableExpr *,findVariable,(BPatch_point &scp, const char *nm));
255
256     //  BPatch_image::findType
257     //  
258     //  Returns a BPatch_type corresponding to <name>, if exists, NULL if not found
259     API_EXPORT(Int, (name),
260
261     BPatch_type *,findType,(const char *name));
262
263     //  BPatch_image::getAddressRanges
264     //  
265     //  method to retrieve addresses corresponding to a line in a file
266     API_EXPORT(Int, (fileName, lineNo, ranges),
267
268     bool,getAddressRanges,( const char * fileName, unsigned int lineNo, 
269                             std::vector<std::pair<unsigned long, unsigned long> > & ranges ));
270     
271     API_EXPORT(Int, (addr, lines),
272     bool,getSourceLines,( unsigned long addr, BPatch_Vector<BPatch_statement> & lines ));
273
274     //  BPatch_image::getProgramName
275     //  
276     //  fills provided buffer <name> with the program's name, up to <len> chars
277     API_EXPORT(Int, (name, len),
278
279     char *,getProgramName,(char *name, unsigned int len));
280
281     //  BPatch_image::getProgramFileName
282     //  
283     //  fills provided buffer <name> with the program's file name, 
284     //  which may include path information.
285     API_EXPORT(Int, (name, len),
286
287     char *,getProgramFileName,(char *name, unsigned int len));
288
289     /* BPatch_image::parseNewFunctions
290      *
291      * This function uses function entry addresses to find and parse
292      * new functions using our control-flow traversal parsing. 
293      *
294      * funcEntryAddrs: this is a vector of function start addresses
295      * that seed the control-flow-traversal parsing.  If they lie in
296      * an existing module they are parsed in that module, otherwise a
297      * new module is created.  In both cases the modules are added to
298      * affectedModules
299      *
300      * affectedModules: BPatch_modules will be added to this vector if no
301      * existing modules bounded the specified function entry points.
302      * Unfortunately, new modules will also sometimes have to be created
303      * for dynamically created code in memory that does not map to the
304      * file version of the binary.  
305      *
306      * Return value: This value is true if a new module was created or if
307      * new code was parsed in an existing module
308      */
309     API_EXPORT(Int, (affectedModules, funcEntryAddrs),
310     bool ,parseNewFunctions, 
311     (BPatch_Vector<BPatch_module*> &affectedModules, 
312      const BPatch_Vector<Dyninst::Address> &funcEntryAddrs));
313
314     //  BPatch_image::GetUnresolvedControlFlow
315     //
316     //  Every call instruction that calls into a region of memory that
317     //  is not recognized by Dyninst as pertaining to a code region in
318     //  an existing program module is tracked. This function returns
319     //  a list of all such call targets
320     API_EXPORT(Int, (), 
321     BPatch_Vector<BPatch_point *> *,getUnresolvedControlFlow, ());
322
323
324     //
325     //  Reads a string from the target process
326     API_EXPORT(Int, (addr, str, size_limit),
327                bool, readString,(Dyninst::Address addr, std::string &str, 
328                                  unsigned size_limit = 0));
329
330     API_EXPORT(Int, (expr, str, size_limit),
331                bool, readString,(BPatch_variableExpr *expr, std::string &str, 
332                                  unsigned size_limit = 0));
333
334 #ifdef IBM_BPATCH_COMPAT
335     API_EXPORT(Ptr, (name, funcs, showError, regex_case_sensitive, incUninstrumentable),
336
337     BPatch_Vector<BPatch_function*> *,
338       findFunction,(const char *name,
339                     BPatch_Vector<BPatch_function*> *funcs,
340                     bool showError=true,
341                     bool regex_case_sensitive=true,
342                     bool incUninstrumentable = false));
343
344     API_EXPORT(Int, (name, len),
345
346     char *,programName,(char *name, unsigned int len));
347
348     API_EXPORT(Int, (),
349     int,lpType,());
350 #endif
351
352 private:
353     BPatch_addressSpace *addSpace;
354     BPatch_Vector<BPatch_module *> modlist;
355     BPatch_Vector<BPatch_module *> removed_list;
356     BPatch_module *defaultModule;
357
358     BPatch_module *findModule(mapped_module *base);
359     BPatch_module *findOrCreateModule(mapped_module *base);
360     void removeModule(BPatch_module *mod);
361     void removeAllModules();
362
363     BPatch_Vector<BPatch_point *> unresolvedCF;
364
365     // These private "find" functions convert from internal int_function
366     // representation to the exported BPatch_Function type
367     void findFunctionInImage(const char *name, image *img,
368                              BPatch_Vector<BPatch_function*> *funcs,
369                              bool incUninstrumentable = false);
370     void sieveFunctionsInImage(image *img, 
371                                BPatch_Vector<BPatch_function *> *funcs,
372                                BPatchFunctionNameSieve bpsieve, 
373                                void *user_data,
374                                bool incUninstrumentable = false);
375
376     static bool setFuncModulesCallback(BPatch_function *bpf, void *data);
377 };
378
379 #endif /* _BPatch_image_h_ */