Home

Dyninst User Manual - Home Page - University of Wisconsin–Madison

1. 6 create a procedure call using function found at 1 and parameters from step 5 BPatch_funcCallExpr openCall openFuncs 0 openArgs 7 The oneTimeCode returns whatever the return result from the BPatch_snippet is In this case the return result of open gt the file descriptor void openFD app gt oneTimeCode openCall return int openFD We have used a oneTimeCode to open the file descriptor However this returns the file descriptor to the mutator the mutatee has no idea what the descriptor is We need to allocate a variable in the mutatee to hold this value for future use and copy the mutator side value into the mutatee variable Note there are alternatives to this technique We could have allocated the variable before the oneTimeCode and augmented the snippet to do the assignment We could also write the file descriptor as a constant into any inserted instrumentation BPatch_variableExpr writeFileDescIntoMutatee BPatch_process app BPatch_image applImage int fileDescriptor 1 Allocate a variable in the mutatee of size and type int BPatch_variableExpr fdVar app gt malloc appImage gt findType int if fdVar NULL return NULL 2 Write the value into the variable Like memcpy writeValue takes a pointer The third parameter is for functionalit
2. bool getLineAndFile unsigned long addr unsigned short amp z lineNo char fileName int length 7 2 bool stopExecution gt bool continueExecution bool terminateExecution So bool isStopped int stopSignal bool isTerminated O E int dumpCore const char file const bool terminate Y int dumpImage const char file 2 bool dumpPatchedImage const char file void enableDumpPatchedImage S BPatch_variableExpr malloc int n BPatch_variableExpr malloc const BPatch_type amp type void free const BPatch_variableExpr amp ptr a BPatch_variableExpr getInheritedVariable y const BPatch_variableExpr amp parentVar z BPatchSnippetHandle getInheritedSnippet gt BPatchSnippetHandle amp parentSnippet bool getSourceLines unsigned long addr std vector lt S std pair lt const char unsigned int gt gt amp lines dyninstAPI HL VOHAdHA CAL VIHAdHA HL VOHAdHA Page 25 BPatchSnippetHandle insertSnippet const BPatch_snippet Sexpr BPatch_point point BPatch_callWhen when BPatch_callBefore BPatch_callAfter BPatch_snippetOrder order BPatch_firstSnippet BPatchSnippetHandle insertSnippet const BPatch_snippet amp eXpr const BPatch_Vector lt BPatch_point gt amp points BPatch_callWhen when BPatch_callBefore BPatch_callAfter BPatch_snippetOrder order BPatch_firstSnippet bool deleteSnippet BPatchSnippetHandle handle b
3. bool isInstrumentable Returns true if the function can be instrumented and false if it cannot Various condi tions can cause a function to be uninstrumentable For example on some platforms func tions smaller than some specific number of bytes cannot be instrumented bool isSharedLib This function returns true if the function is defined in a shared library const char libraryName Returns the name of the library that contains this function If the function is not defined in a library a NULL will be returned dyninstA PI Page 28 Bpatch_module getModule Returns the module that contains this function Depending on whether the program was compiled for debugging or the symbol table stripped this information may not be avail able This function returns NULL if module information was not found char getModuleName char name int maxLen Copies the name of the module that contains this function into the buffer pointed to by name Copies at most maxLen characters and returns a pointer to name enum BPatch_procedureLocation BPatch_entry BPatch_exit BPatch_subroutine BPatch_allLocations const BPatch_Vector lt BPatch_point gt findPoint const BPatch_procedureLocation loc Returns the BPatch_point or list of BPatch_points associated with the procedure It is used to select which type of points associated with the procedure will be returned BPatch_entry and BPatch_exit request respectively
4. DYNINST_ROOT lib PLATFORM bubba pd OBJECTS cc g xs S OBJECTS lm lcurses ltermcap 0o bubba Linking an application to run with Dyninst Items in Bold face show the changes for Solaris Figure 2 Sample Makefile for Solaris 6 EXAMPLES This section provides a set of example code to show how the various parts of the API are used together 6 1 Complete Example retee In this section we show a complete program to demonstrate the use of the API The example is a program called re tee It takes three arguments the pathname of an executable program the process id of a running instance of the same program and a file name It adds code to the run ning program that copies to the named file all output that the program writes to its standard out put file descriptor In this way it works like tee which passes output along to its own standard out while also saving it in a file The motivation for the example program is that you run a pro gram and it starts to print copious lines of output to your screen and you wish to save that output in a file without having to re run the program Using the API to directly create programs is possible but somewhat tedious We anticipate that most users of the API will be tool builders who will create higher level languages for specifying instrumentation e g the MDL language 4 include lt stdio h gt include lt fcntl h gt include BPatch h i
5. 23 24 dumplmage 23 dumpPatchedImage 23 E enableDumpPatchedImage 23 F findFunction 30 31 33 50 findPoint 26 findType 32 findVariable 31 free 16 23 funcJumpExpr 38 G getAddress 28 getAllBasicBlocks 43 getAllDominates 46 getBaseAddr 27 42 getBlockNumber 46 getByteCount_NP 53 getCalledFunction 28 getCallStack 21 22 getCblocks 40 getCFG 27 getComponents 40 42 49 getConstituentType 41 getContainedLoops 48 getCost 36 getCurrentSnippets 29 getDataClass 41 getEntryBasicBlock 43 getExitBasicBlock 43 getFP 50 getFrameType 50 getFunctions 50 getHigh 41 getImage 15 23 32 33 34 getImm 53 getImmediateDominates 46 getImmediateDominator 46 getInherited Variable 16 23 getLanguage 24 getLineAndFile 22 28 getLineToAddr 28 32 35 getLoopBasicBlocks 48 getLoopHead 48 getLoops 43 getLow 41 getMangledName 25 getMemoryAccess 29 getModule 26 getModuleName 26 getModules 30 getName 25 34 41 getObjParent 24 getParams 25 getPC 50 getPointType 28 getProcedures 30 34 getReg 53 getReturnType 25 getSourceBlock 46 getSourceFile 49 getSourceLines 49 getSourceObj 24 getSources 44 45 46 getSrcType 24 getStartAddr_NP 53 getTargets 46 getThreads 7 11 getType 35 getUniqueString 32 35 I insertSnippet 17 23 isALoad_NP 53 isAPrefetch_NP 53 isAStore
6. eral purpose and floating point registers can be saved It is difficult to analyze func tion calls that may be nested arbitrarly deep Dyninst will not analyze any deeper than two levels of function calls before assuming that the instrumentation clobbers all reg isters and it needs to save everything In addition not making function calls from instrumentation allows Dyninst to eli mante its tramp guard and thread index calculation Instrumentation that does not make a function call cannot recursively execute more instrumentation Call BPatch setTrampRecursive true if instrumentation cannot exe cute recursively If instrumentation must make a function call but will not execute recursively then enable trampoline recursion This will cause Dyninst to stop gener ating a trampoline guard and thread index calculation on all future pieces of instru mentation An example of instrumentation recursion would be instrumenting a call to write with instrumentation that calls print f write will start calling printf printf will re call write Call BPatch setSaveFPR false if instrumentation will not clobber float ing point registers This will cause Dyninst to stop saving floating point registers which can be a significant win on some platforms Use simple BPatch_snippet objects when possible Dyninst will attempt to recognize and peep hole optimize simple frequently used code snippets when it finds them For example on x86 based platforms Dy
7. gate the graph A BPatch_flowGraph object can be obtained by calling the get CFG method ofa BPatch_function object dyninstA PI bool void void void void void Page 46 containsDynamicCallsites Returns true if the control flow graph contains any dynamic callsites e g calls through a function pointer getAllBasicBlocks BPatch_Set lt BPatch_basicBlock gt 4 Fills the given set with pointers to all basic blocks in the control flow graph BPatch_basicBlock is described in section 4 15 getEntryBasicBlock BPatch_Vector lt BPatch_basicBlock gt amp Fills the given vector with pointers to all basic blocks that are entry points to the function BPatch_basicBlock is described in section 4 15 getExitBasicBlock BPatch_Vector lt BPatch_basicBlock gt 4 Fills the given vector with pointers to all basic blocks that are exit points of the function BPatch_basicBlock is described in section 4 15 getLoops BPatch_Vector lt BPatch_basicBlockLoop gt amp Fills the given vector with a list of all natural single entry loops in the control flow graph getOuterLoops BPatch_Vector lt BPatch_basicBlockLoop gt 4 Fills the given vector with a list of all natural single entry outer loops in the control flow graph BPatch_loopTreeNode getLoopTree enum Returns the root node of the tree of loops in this flow graph BPatch_procedureLocation BPatch_locLoopEntry BPatch_locLoopExit BPa
8. tory and execute the command make DyninstAPI This will build Dyninst s mutator li brary the Dyninst runtime library and Dyninst s test suite Successfully built binaries will be stored in a directory named after your platform at the same level as the core directory BUILDING ON WINDOWS Dyninst for Windows is built with Microsoft Visual Studio 2003 project and solution files Building Dyninst for Windows is similar to UNIX in that it is a four step process Unpack the DyninstAPI source code install Dyninst s package dependencies configure Visual Studio to use the dependencies and run the build system Dyninst source code is distributed as part of a tar gz package Most popular unzipping programs are capable of handling this format Extracting the Dyninst tarball results in two directories core and scripts Dyninst for Windows depends on Microsoft s Debugging Tools for Windows which could be found at http www microsoft com whdc devtools debugging default mspx at the time of this writing Download these tools and install them at an appropriate location Make sure to do a custom install and install the SDK which is not always installed by default For the rest of this section we will assume that the Debugging Tools are installed at c program files Debugging Tools for Windows If this is not the case then adjust the follow ing instruction appropriately Once the Debugging Tools are installed Visual Studio must be con
9. Returns the children source objects of the current source object For example when called on a BPatch_sourceProgram object this will return objects of type BPatch_sourceFunction When called on a BPatch_sourceFunction object it may return BPatch_sourceOuterLoop and BPatch_sourceStatement objects BPatch_sourceObj getObjParent Returns the parent source object of the current source object The parent of a BPatch_ image is NULL BPatch_language getLanguage Return the source language of the current BPatch_sourceObject For programs that are written in more than one language BPatch_mixed will be returned If there is insufficient information to determine the language BPatch_unknownLanguage will be returned 4 5 Class BPatch_function An object of this class represents a function in the application A BPatch_image object see de scription below can be used to retrieve a BPatch_function object representing a given function char getName char buffer int len Places the name of the function in buffer up to len characters It returns the value of the buffer parameter char getMangledName char buffer int len Places the mangled internal symbol name of the function in buffer up to 1en charac ters It returns the value of the buffer parameter char getTypedName char buffer int len Places the full function prototype from debug information of the function in buffer up to len characters It returns the value
10. 10perand rOperand BPatch_seq Define a sequence of two expressions similar to comma in C BPatch_arithExpr BPatch_unO0p const BPatch_snippet amp operand Defines a snippet consisting of a unary operator The unary operators are Operator Description BPatch_negate Returns the negation of an integer BPatch_addr Returns a pointer to a BPatch_variableExpr BPatch_deref Dereferences a pointer BPatch_boolExpr BPatch_relOp op const BPatch_snippet amp lOperand const BPatch_snippet amp rOperand Defines a relational snippet The available operators are Operator Function BPatch_lt Return lOperand lt rOperand BPatch_eq Return lOperand rOperand BPatch_gt Return lOperand gt rOperand BPatch_le Return lOperand lt rOperand BPatch_ne Return lOperand rOperand BPatch_ge Return lOperand gt rOperand BPatch_and Return lOperand amp amp rOperand Boolean and BPatch_or Return lOperand Il rOperand Boolean or The type of the returned snippet is boolean and the operands are type checked BPatch_breakPointExpr Defines a snippet that stops a process when executed by it The stop can be detected us ing the isStopped member function of BPatch_process and the program s execution can be resumed by calling the continueExecution member function of BPatch_process dyninstAPI Page 40 BPatch_bytesAccessedExpr This expression returns the nu
11. AA D D AERE EE A E E EE E EE E EE aaa 58 5 sing the A Plo ics EAEE EE E E E A S 60 5 1 OVERVIEW OE MAJOR STEPS decias 60 5 2 CREATING A MUTATOR PROGRAM scssccccccecssssaececececsensnaececececseseaaecesececeeseseaeceeeeeesensaeceeeceeseneaaeas 60 5 3 SETTING UP THE APPLICATION PROGRAM MUTATEE 0 cssssccesseseeceesnececeesaeeeceeseeeessaeeecseaeeecsenaees 61 5 4 RUNNING THE MUTATOR i cssccocscecvedsnseitcocea sve Saccuetecs ce dida 62 5 5 ARCHITECTURALISSUES ii de Ease ceed 62 5 5 1 D OLGIIS sas 5 25 Seas dk ec vet eia eda dia Ta 63 6 EXAMPLES coito tds 63 6 1 COMPLETE EXAMPLE RETRE comi eden 63 6 2 INSTRUMENTING MEMORY ACCESS sccccccecssssseceeececsessaececececeeseaeceseesesesessaaeceeeceesesssaseeeeeeeeensaaeas 68 Appendix A Running the Test Cases cescsssecsssecesecesscecsccesncecseceeneecssccesaeecsssceeneecsseeeeneecssececsaeecsaeeeeeeesaeeeseeues 70 Appendix B Common pitfalls t E dr aiii 72 dyninstAPI Appendix C Building Dyninst oooonnccnncnnnnconnnonnnonnnnnnnnncnnncn nono ne cono nono rn nono nono eran nena nnnn RR Ren Ron Ren neon neon nero nono conan rin rnnn nano 74 Appendix D Dyninst Performance A iia 77 References cousatoniiis opio 84 1 INTRODUCTION The normal cycle of developing a program is to edit source code compile it and then execute the resulting binary However sometimes this cycle can be too restrictive We may wish to change the program while it is executing and no
12. and proc is the thread s containing process registerThreadEventCallback BPatch_asyncEventType type BPatchAsyncThreadEventCallback cb This function registers a callback to occur whenever the process triggers a new thread event The type parameter can be either one of BPatch_threadCreateEvent or dyninstAPI Page 14 BPatch_threadDestroyEvent Different callbacks can be registered for different values of type typedef void BPatchExecCallback BPatch_thread thr This is the prototype for the exec callback The thr parameter is a thread in the process that called exec You can use the BPatch_thread getProcess function to get the BPatch_process that performed the exec operation BPatchThreadEventCallback registerExecCallback BPatchExecCallback func Not implemented on Windows Registers a function to be called when a thread executes an exec system call When the function is called the thread performing the exec will be paused typedef void BPatchForkCallback BPatch_thread parent BPatch_thread child This is the prototype for the pre fork and post fork callbacks The parent parameter is the parent thread and the child parameter is a BPatch_thread in the newly created process When invoked as a pre fork callback the child is NULL BPatchForkCallback registerPreForkCallback BPatchForkCallback func not implemented on Windows Registers a function to be called when a BPatch_thread forks a new
13. can be passed to BPatch_process insertSnippet to instrument the edge enum BPatch_edgeType CondJumpTaken CondJumpNottaken UncondJump NonJump BPatch_edgeType getType Returns a type describing this edge A CondJumpTaken edge is found after a conditional branch along the edge that is taken when the condition is true A CondJumpNot taken edge follows the path when the condition is not taken UncondJump is used along an edge that flows out of an uncondition branch that is always taken NonJump is an edge that flows out of a basic block that does not end in a jump but falls through into the next basic block BPatch_basicBlock getSource Returns the source BPat ch_basicBlock that this edge flows from BPatch_basicBlock getTarget Returns the target BPat ch_basicBlock that this edge flows to dyninstAPI Page 48 4 14 Class BPatch_loopTreeNode The BPatch_loopTreeNode class provides a tree interface to a collection of instances of class BPatch_basicBlockLoop contained ina BPatch_flowGraph The structure of the tree follows the nesting relationship of the loops in a function s flow graph Each BPatch_loopTreeNode contains a pointer to a loop represented by BPatch_basicBlockLoop and a set of sub loops represented by other BPatch_loopTreeNode objects The root BPatch_loopTreeNode instance has a null loop member since a function may contain multiple outer loops the outer loops are contained in the root instance
14. contain points where code can be modified Each process is associated with exactly one image Each process contains at least one thread which represents a thread of execution running in that process The API includes a simple type system based on structural equivalence If mutatee programs have been compiled with debugging symbols and the symbols are in a format that Dyninst under stands type checking is performed on code to be inserted into the mutatee See Section 4 25 for a complete description of the type system We include abstraction for a function in the binary Due to language constructs or compiler op timizations it may be possible for multiple functions to overlap that is share part of the same function body or for a single function to have multiple entry points In practice it is impossible to determine the difference between multiple overlapping functions and a single function with multiple entry points The DyninstAPI uses a model where each function BPatch_function ob ject has a single entry point and multiple functions may overlap share code We guarantee that instrumentation inserted in a particular function is only executed in the context of that function even if instrumentation is inserted into a location that exists in multiple functions 3 SIMPLE EXAMPLE To illustrate the ideas of the API we present several short examples that demonstrate how the API can be used The full details of the interface are presented in
15. contained in the BPatch_memoryAccess_NP h header 4 24 1 Class BPatch_memoryAccess This class encapsulates a memory access abstraction It contains information that describes the memory access type read write read write or prefetch It also contains information that allows the effective address and the number of bytes transferred to be determined bool isALoad_NP Returns true if the memory access is a load memory is read into a register bool isAStore_NP Returns true if the memory access is write Some machine instructions may both load and store e g CAS compare and swap on SPARC bool isAPrefetch_NP Returns true if memory access is a prefetch 1 e it has no observable effect on user regis ters It this returns true the instruction is considered neither load nor store Prefetches are detected only on SPARC short prefetchType_NP If the memory access is a prefetch this method returns a platform specific prefetch type On SPARC this returns the prefetch type as encoded in the instruction See the SPARC Architecture Man ual version 9 for details dyninstA PI Page 58 BPatch_addrSpec_NP getStartAddr_NP Returns an address specification that allows the effective address of a memory reference to be computed For example on the x86 platform a memory access instruction operand may contain a base register an index register a scaling value and a constant base The BPatch_addrSpec_NP describes each o
16. does not bpsieve should return false The function bpsieve should be defined in accordance with the typedef bool BPatchFunctionNameSieve const char name void sieve_data If the incUninstrumentable flag is set the returned table of procedures will in clude uninstrumentable functions The default behavior is to omit these functions dyninstA PI Page 34 const BPatch_variableExpr findVariable const char name const BPatch_variableExpr findVariable const BPatch_point scope const char name second form of this method is not implemented on NT Performs a lookup and returns a handle to the named variable The first form of the func tion looks up only variables of global scope and the second form uses the passed BPatch_point as the scope of the variable The returned BPatch_variableExpr can be used to create references uses of the variable in subsequent snippets The scoping rules used will be those of the source language If the image was not compiled with debugging sym bols this function will fail even if the variable is defined in the passed scope const BPatch_type findType const char name Performs a lookup and returns a handle to the named type The handle can be used as an argument to malloc to create new variables of the corresponding type BPatch_module findModule const char name bool substring_match false Returns a module matching name if present in the image If the match fails
17. dyninstA PI Page 37 dress ranges This information is only available 1f the mutatee was compiled with debug information This function may be more efficient than the BPatch_process version of this func tion Calling BPatch_process getAddressRange will cause Dyninst to parse line information for all modules in a process If BPatch_module getAddressRange is called then only the debug information in this module will be parsed This function returns t rue if it was able to find any line information false otherwise const BPatch_Vector lt BPatch_function gt getProcedures Returns a vector of the functions in the module char getName char buffer int len This function copies the name of the module into a buffer up to len characters It returns the value of the buffer parameter char getFullName char buffer int length Fills buf fer with the full path name of a module up to Length characters when this information is available unsigned long getSize Returns the size of the module The size is defined as the end of the last function minus the start of the first function bool getVariables BPatch_Vector lt BPatch_variableExpr gt amp vars Fills the vector vars with the global variables that are specified in this module Re turns false if no results are found and true otherwise void wgetBaseAdar Returns the base address of the module This address is defined as the start of the first function
18. example files containing instrumentation functions that were too complex to write directly using the API must be linked with your application Simply add these files to the line lt insert any ad ditional modules here gt in Figure 1 On SPARC Solaris AIX Linux and Compaq Tru64 UNIX you may put such code into a dynamically loaded shared library which your mutator pro gram can load into the mutatee at runtime using the loadLibrary member function of BPatch_process Additionally on most platforms we need to use the flags g to generate debugging when com piling The command line switches used to specify these options are different for Visual C on Windows NT see section Error Reference source not found for information about compiling on Windows NT dyninstA PI Page 62 To locate the runtime library that Dyninst needs to load into your program an additional envi ronment variable must be set The variable DYNINSTAPL RT_LIB should be set to the full pathname of the run time instrumentation library which should be DYNINST_ROOT PLATFORM lib libdyninstAPI_RT so 1 UNIX ZDYNINST_ROOT 1386 unknown nt4 0 11b libdyninstAPI_RT dll Windows Figure 1 is an example of how you would modify the link command in your Makefile on one of the UNIX based platforms to handle the extra link step required by the current version of the API If your Makefile contained the link step shown in Figure 1 a You would change it to the version sh
19. in the module bool isSharedLib This function returns true if the module is part of a shared library const char getUniqueString Performs a lookup and returns a unique string for this image Returns a string the can be compared via strcmp to indicate if two images refer to the same underlying object file dyninstAPI Page 38 1 e executable or library The contents of the string is implementation specific and de fined to have no semantic meaning These functions are deprecated Consider using getSourceLines instead bool getLineToAddr const char fileName unsigned short lineNo BPatch_Vector lt unsigned long gt amp buffer bool exactMatch true bool getLineToAddr unsigned short lineNo BPatch_Vector lt unsigned long gt amp buffer bool exactMatch true HAL VIHAdHA 4 9 Class BPatch_snippet A snippet is an abstract representation of code to insert into a program Snippets are defined by creating a new instance of the correct subclass of a snippet For example to create a snippet to call a function create a new instance of the class BPatch_funcCallExpr Creating a snip pet does not result in code being inserted into an application Code is generated when a request is made to insert a snippet at a specific point in a program Sub snippets may be shared by different snippets i e a handle to a snippet may be passed as an argument to create two different snip pets but whether the generated code is sha
20. process must be stopped to call this function The behavior is synchronous oneTimeCode will not return until after the snippet has been run in the application dyninstAPI bool Page 22 oneTimeCodeAsync const BPatch_snippet amp expr void userData NULL This function sets up a snippet to be evaluated by the process at the next available oppor tunity When the snippet finishes running Dyninst will callback any function registered through BPatch registerOneTimeCodeCallback with userData passed as a parameter This function return true on success and false if it could not post the one TimeCode If the process is multithreaded the snippet is run on a thread chosen by Dyninst If the user requires the snippet to be run on a particular thread use the BPat ch_thread ver sion of this function instead The behavior is asynchronous oneTimeCodeAsync returns before the snippet is executed If the process is running when oneTimeCodeAsync is called expr will be run imme diately If the process is stopped then expr will be run when the process is continued 4 3 Class BPatch_thread The BPatch_thread class operates a thread of execution that is running in a process void long long getCallStack BPatch_Vector lt BPatch_frame gt amp stack This function fills the given vector with current information about the call stack of the thread Each stack frame is represented by a BPatch_frame see section 4 20 for info
21. protection code described in more detail below that do things such as sav ing restoring registers around instrumentation checking for instrumentation recursion or per forming thread safety checks The factor by which Dyninst overhead influences mutatee run time is dependant on the type of instrumentation being inserted When inserting instrumentation that runs a memory cache simu lator the Dyninst overhead may be negligible On the other hand when inserting instrumenta tion that increments a counter the Dyninst overhead will dominate the time spent in instrumenta tion Remember optimizing the instrumentation being inserted may sometimes be more impor tant than optimizing the Dyninst overhead Many users have had success writing tools that make use of Dyninst s ability to dynamically remove instrumentation as a performance improvement The instrumentation overhead results from safety and correctness checks inserted by Dyninst around instrumentation Dyninst will automatically attempt to remove as much of this overhead as possible however it sometimes must make a conservative decision to leave the overhead in Given additional user provided information Dyninst can make better choices about what safety checks to leave in An unoptimized post Dyninst 5 0 instrumentation snippet looks like the fol lowing In order to ensure that instrumentation doesn t Save General Purpose Registers corrupt the program Dyninst saves all general pu
22. s vector of children Each instance of BPatch_loopTreeNode is given a name which indicates its position in the hierarchy of loops The name of each root loop takes the form of Loop_x where x is an inte ger from 1 to n where n is the number of outer loops in the function Each sub loop has the name of its parent prepended by a _y where y is 1 to m where m is the number of sub loops under the outer loop For example consider the following C function void foo inbe Ex pA IZ i for x 0 x lt 10 x for y 0 y lt 10 YA for z O z lt 10 z for i 0 ixl0 i The foo function will have a root BPatch_loopTreeNode containing a NULL loop entry and two BPatch_loopTreeNode children representing the functions outer loops These children would have names loop_1 and loop_2 respecively representing the x and i loops loop_2 has no children Loop_1 has two child BPat ch_loopTreeNode objects named loop_1_1 and loop_1_ 2 respectively representing the y and z loops BPatch_basicBlockLoop loop A node in the tree that represents a single BPat ch_basicBlockLoop instance BPatch_Vector lt BPatch_loopTreeNode gt children The tree nodes for the loops nested under this loop const char name Return a name for this loop that indicates its position in the hierarchy of loops dyninstAPI Page 49 bool getCallees BPatch_Vector lt BPatch_function gt amp v BPatch_proce
23. stan dard rules of type compatibility described in Section 4 25 are used with arrays created us ing this function BPa tch_type createEnum const char name BPatch_Vector lt char gt elementNames BPatch_Vector lt int gt elementlds BPat ch_type createEnum const char name BPatch_Vector lt char gt elementNames Create a new enumerated type There are two variations of this function The first one is used to create an enumerated type where the user specifies the identifier int for each element In the second form the system specifies the identifiers for each element In both cases a vector of character arrays is passed to supply the names of the elements of the enumerated type In the first form of the function the number of element in the ele mentNames and element Ids vectors must be the same or the type will not be cre ated and this function will return NULL The standard rules of type compatibility de scribed in Section 4 25 are used with enums created using this function dyninstA PI Page 11 BPatch_type createScalar const char name int size Create a new scalar type The name field is used to specify the name of the type and the size parameter is used to specify the size in bytes of each instance of the type No addi tional information about this type is supplied The type is compatible with other scalars with the same name and size BPatch_type createStruct co
24. the next section To prevent confusion we refer to the process we are modifying as the application and the program that uses the API to modify the application as the mutator A mutator is a separate process that modifies an application process A mutator program must create a single instance of the class BPatch This object is used to ac cess functions and information that are global to the library It must not be destroyed until the mutator has completely finished using the library For this example we will assume that the mu tator program has declared a global variable called bpatch of class BPatch The first thing a mutator needs to do is identify the application process to be modified If the process is already in execution this can be done by specifying the executable file name and proc ess id of the application as arguments to create an instance of a process object appProc bpatch processAttach name proccesld dyninstA PI Page 5 This creates a new instance of the BPatch_process class that refers to the existing process It had no effect on the state of the process 1 e running or stopped If the process has not been started the mutator specifies the pathname and argument list of a program to execute appProc bpatch processCreate pathname argv Once the application thread has been created the mutator defines the snippet of code to be in serted and the points where they should be inserted For example if we
25. the system the greatest flexibility in allowing users to write mutators that work with applications compiled both with and without debugging symbols enabled Using the create methods of the BPatch class a mutator can construct type definitions for existing mutatee dyninstAPI Page 59 structures This information allows a mutator to read and write complex types even if the appli cation program has been compiled without debugging information However if the application has been compiled with debugging information Dyninst will verify the type compatibility of the operations performed by the mutator The rules for type computability are that two types must be of the same storage class i e arrays are only compatible with other arrays to be type compatible For each storage class the follow ing additional requirements must be met for two types to be compatbible Bpatch_dataScalar Scalars are compatible if their names are the same as defined by strcmp and their sizes are the same BPatch_dataPointer Pointers are compatible if the types they point to are compatible BPatch_dataFunc Functions are compatible if their return types are compatible they have same number of parameters and position by position each element of the parameter list is type compati ble BPatch_dataArray Arrays are compatible if they have the same number of elements regardless of their lower and upper bounds and the base element types are type compatibl
26. the type of their left operand Turning type checking off creating a snippet and then turning type checking back on is similar to the type cast operation in the C programming language isTypeChecked Returns true if type checking of snippets is enabled and false otherwise waitForStatusChange This function waits until there is a status change to some thread that has not yet been re ported by either isStopped or isTerminated and then returns true It is more effi cient to call this function than to call pollForStatusChange in a loop because waitForStatusChange blocks the mutator process while waiting setDelayedParsing bool Turn on or off delayed parsing When on Dyninst will initially parse only the symbol ta ble information in any new modules loaded by the program and will postpone more thor ough analysis instrumentation point analysis variable analysis and discovery of new dyninstAPI bool void bool Page 9 functions in stripped binaries This analysis will automatically occur when the informa tion is necessary Users which require small run time perturbation of a program should not delay parsing the overhead for analysis may occur at unexpected times if it is triggered by internal Dyn inst behavior Users who desire instrumentation of a small number of functions will bene fit from delayed parsing delayedParsingon Returns true if delayed parsing is enabled and false otherwise setMer
27. to add instrumentation When instrumentation is inserted into a function Dyninst may need to rewrite some or all of the dyninstAPI Page 78 function to fit the instrumentation in If multiple pieces of instrumentation are being inserted into a function Dyninst may need to re write that function multiple times If the user knows that they will be inserting multiple pieces of instrumentation into one function they can batch the instrumentation into one bundle so that the function will only be re written once using the BPatch_process beginInsertionSet and BPatch_process endInsertionSet functions see section 4 2 Using these functions can result in a significant performance win when inserting instrumentation in many locations To use the insertion set functions add a call to beginInsertionSet before inserting instru mentation Dyninst will start buffering up all instrumentation insertions After the last piece of instrumentation is inserted call endInsertionSet and all instrumentation will be atomically inserted into the mutate with each function being rewritten at most once APPENDIX D 2 Optimizing Mutatee Performance As instrumentation is inserted into a mutate it will start to run slower The slowdown is heavily influcenced by three factors the number of points being instrumentated the instrumentation it self and the Dyninst overhead around each piece of instrumentation The Dyninst overhead comes from pieces of
28. to decide which clause should be executed The second argument t Clause is the snippet to execute if the conditional evaluates to true The third argument fClause is the snippet to execute if the conditional evaluates to false This third argument is optional Else if statements can be constructed by making the Clause of an if statement another if statement BPatch_insnExpr BPatch_instruction insn implemented on x86 64 This constructor creates a snippet that allows the user to mimic the effect of an existing instruction In effect the snippet wraps the instruction and provides a handle to particu lar components of instruction behavior This is currently implemented for memory opera tions and provides two override methods overrideLoadAddress and overrideStoreAd dress Both methods take a BPatch_snippet as an argument Unlike other snippets this snippet should be installed via a call to BPatch_process replaceCode to replace the origi nal instruction For example Assume that access is of type BPatch_memoryAccess as provided by a call to BPatch_point gt getMemoryAccess A BPatch_memoryAccess is a child of BPatch_instruction and is a valid source of a BPatch_insnExpr BPatch_insnExpr insn access This example will modify a store by increasing the target address by 16 BPatch_arithExpr newStoreAddr BPatch_plus BPatch_effectiveAddressExpr BPatch_constExpr 16 And no
29. vector containing the individual variables of the common block BPatch_Vector lt BPatch_function gt getFunctions Returns a vector of the functions that can see this common block with the set of fields de scribed in getComponents However other functions that define this common block with a different set of variables or sizes of any variable will not be returned 4 20 Class BPatch_frame A BPatch_frame object represents a stack frame The BPatch_thread getCallStack member function of BPatch_thread returns a vector of BPatch_frame objects representing the frames currently on the stack BPatch_frameType getFrameType Returns the type of the stack frame Possible types are Frame Type Meaning BPatch_frameNormal A normal stack frame BPatch_frameSignal A frame that represents a signal invocation BPatch_frameTrampoline A frame the represents a call into instrumentation code void getFP Returns the frame pointer for the stack frame void getPC Returns the program counter associated with the stack frame BPatch_function findFunction Returns the function associated with the stack frame dyninstAPI Page 54 4 21 Class BPatch_dependenceGraphNode A BPatch_dependenceGraphNode object represents a node in any of data control or program dependence graphs as well as the graph that represents the slice of a function One can navigate through these graphs by get Out goingEdges and get Incomi
30. wanted to count the num ber of times a procedure called InterestingProcedure executes the mutator might look like this dyninstA PI Page 6 BPatch_image appImage BPatch_Vector lt BPatch_point gt points BPatch_Vector lt BPatch_function gt functions Open the program image associated with the thread and return a handle to it appImage appProc gt getImage find and return the function that we wish to instrument appImage gt findFunction InterestingProcedure functions find and return the entry point to the InterestingProcedure points functions 0 gt findPoint BPatch_entry Create a counter variable but first get a handle to the correct type by allocating in the application s address space BPatch_variableExpr intCounter appProc gt malloc appImage gt findType int Create a code block to increment the integer by one intCounter intCounter 1 BPatch_arithExpr addOne BPatch_assign intCounter BPatch_arithExpr BPatch_plus intCounter BPatch_constExpr 1 insert the snippet of code into the application appProc gt insertSnippet addOne points continue execution appProc gt continueExecution wait for mutatee to finish while allowing Dyninst to handle events while appProc gt isTerminated bpatch waitForStatusChange 4 INTERFACE This section describes functions in the API The A
31. Compiler Group missing debug symbols The Portland Group compiler pgcc on Linux produces debug symbols that are not read correctly by Dyninst The binaries produced by the compiler do not contain the source file information necessary for Dyninst to assign the debug symbols to the correct module When Building Dyninst from Source Commonly required external libraries and headers such as libdwarf or libelf are not found correctly by the compiler Often such packages are installed but outside of the compiler s default search path Because of this we have provided the following extention to our make system If the file make config local exists inside the DYNINST_ROOT core directory it will automati cally be included during the build process dyninstA PI Page 73 You can then set the makefile variables FIRST_INCLUDE and FIRST_LIBDIR inside make config local These variables represent the compiler flags used during the compila tion and linking phase respectively These paths will be searched before any others in suring that the correct package is used For example FIRST_INCLUDE FIRST_LIBDIR dyninstA PI I usr ocal L usr ocal packages ibel packages 1 ibel f 0 8 5 include f 0 8 5 lib Page 74 APPENDIX C BUILDING DYNINST This appendix describes how to build Dyninst from source code which can be downloaded from http www paradyn org or http www dyni
32. NP Returns true if inserting instrumentation at this point requires using a trap On the x86 architecture because instructions are of variable size the instruction at a point may be too small for the API library to replace it with the normal code sequence used to call instru mentation Also when instrumentation is placed at points other than subroutine entry exit or call points traps may be used to ensure the instrumentation fits In this case the API replaces the instruction with a single byte instruction that generates a trap A trap handler then calls the appropriate instrumentation code Since this technique is used only on some platforms on other platforms this function always returns false BPatch_memoryAccess getMemoryAccess Returns the memory access object associated with this point MemoryAccess points are described in section 4 24 1 const BPatch_Vector lt BPatchSnippetHandle gt getCurrentSnippets const const bool BPatch_Vector lt BPatchSnippetHandle gt getCurrentSnippets BPatch_callWhen when Returns the BPatchSnippetHandles for the BPatch_snippets that are associated with the point If argument when is BPatch_callBefore then BPatchSnippetHandles for snippets installed immediately before this point will be returned Alternatively if when is BPatch_callAfter then BPatchSnippetHandles for snippets installed immediately after this point will be returned int getLi
33. NULL is re turned If substring_match is set the first moduled that has name as a substring of its name is returned e g to find libpthread so 1 search for libpthread with sub string_match set to true const char getUniqueString not yet implemented bool bool Performs a lookup and returns a unique string for this image Returns a string the can be compared via strcmp to indicate if two images refer to the same underlying object file 1 e executable or library The contents of the string is implementation specific and de fined to have no semantic meaning getSourceLines unsigned long addr std vector lt std pair lt const char unsigned int gt gt amp lines Given an address addr this function returns a vector of pairs of filenames and line numbers at that address This function 1s an alias for BPatch_process getSourceLines see section 4 2 getAddressRanges char fileName unsigned int lineNo std vector lt std pair lt unsigned long unsigned long gt gt amp ranges Given a file name and line number fileName and linenNo this function returns a list of address ranges that this source line was compiled into This function is an alias for BPatch_process getAddressRanges see section 4 2 dyninstAPI SS GALVIAAAA O H Page 35 bool getLineToAddr const char fileName unsigned short lineNo BPatch_Vector lt unsigned long gt amp buffer bool exactMatch true Th
34. PI is organized as a collection of C classes The primary classes are BPatch BPatch_process BPatch_thread BPatch_image BPatch_point and BPatch_snippet The API also uses a template class called BPatch_Vector This class is based on the Standard Template Library STL vec tor class 4 1 Class BPatch The BPatch class represents the entire Dyninst library There can only be one instance of this class at a time This class is used to perform functions and obtain information not specific to a particular thread or image dyninstAPI Page 7 BPatch_Vector lt BPatch_process gt getProcesses Returns the list of processes that are currently defined This list includes threads that were directly created by calling processCreate processAttach and indirectly by the UNIX fork or Window s CreateProcess system call It is up to the user to delete this vector when they are done with it BPatch_process processAttach const char path int pid BPatch_process processCreate const char path char argv bool void bool char envp NULL int stdin_fd 0 int stdout_fd 1 int stderr _fd 2 Each of these functions returns a pointer to a new instance of the BPatch_process class The path parameter needed by these functions should be the pathname of the executable file containing the process s code The processAttach function returns a BPatch_process associated with an existing process On Linux platforms the path paramete
35. Paradyn Parallel Performance Tools Dyninst Programmer s Guide Release 5 2 March 2008 Computer Science Department University of Wisconsin Madison Madison WI 53711 Computer Science Department University of Maryland College Park MD 20742 Email bugs dyninst org Web www dyninst org dyninstAPI 5 27 2008 Page 1 TICO 11 61 6 TOI a Ree pee ee ee E EEN ENEN ENEE ENTE E EEES N Aia 3 De VANO D 101510 REEE a i e de ld Lo 3 3 Sample Ex arm p le assess sissies E Be we SS edi 4 4 Interact a a at meee 6 4 1 CELASSBRATC E E e e dle o o e da nt AT 6 4 1 1 GOLD GR S ose dir errata alienta dde todito ains 12 4 2 CASS PATCH PROCES Sas ia 16 4 3 CLASS BPATCH THREAD At 22 4 4 CLASS BPATCH_SOURCEOB cccscsessscecececsesssaececececeessaaececececeeseaesesececsesessaaeeeeeeeesessaeeeeeeeeceensaeas 25 4 5 CLASS B PATO FUNCTION coco iio ii aid ains ct eii 26 4 6 CLASS BPATCH PONT A A A E AA a 30 4 7 CLASS BPATCH IMAGE vada 31 4 8 CLASS BPATCH_MODULBE ccccccccccecsesssececececsessaeceeececsensaececececeeneaeeecececeeseaaeceeeceeesessaseeeeeeceesaaes 35 4 9 CLASS BPATCH SNIPPET o 2 cevecssosvestedtvededsesecstesevedecbcssteotecacetevasebecs date vedovsesSlvodesesdetededneetiesdeeeveestents 38 4 10 CEASS B PATCH TYPE isc 43 4 11 CLASS BPATCH VARIABLEEXPR 3 ceseevecdevessesdecseniadeves vesetes teadeodeevaceteatcedesasbeeceeceevede et veecescuveosenserves 44 4 12 CLASS BPATCH_FLOWGRAPH cccsessscccececsess
36. _NP 53 isCompatible 41 isInstrumentable 26 isSharedLib 26 35 isStopped 16 22 isTerminated 16 22 L libraryName 26 dyninstA PI Page 82 M malloc 16 23 Memory Access Classes 52 Memory Access Snippets 65 O oneTimeCode 16 20 22 23 P pollForStatusChange 7 8 prefetchType_NP 53 R readValue 42 registerDynamicLinkCallback 14 registerErrorCallback 12 13 registerExecCallback 13 registerExitCallback 14 registerPostForkCallback 13 registerPreForkCallback 13 removeFunctionCall 18 23 replaceFunction 18 23 replaceFunctionCall 19 23 S setDebugParsing 7 setInheritSnippets 18 23 setMutationsActive 19 23 setTrampRecursive 8 setTypeChecking 8 stopExecution 15 22 stopSignal 16 22 T terminateExecution 15 22 Type Checking 54 U usesTrap_NP 29 W write Value 42 dyninstA PI Page 84 REFERENCES l B Buck and J K Hollingsworth An API for Runtime Code Patching Journal of Supercomputing Appli cations to appear 2000 2 J K Hollingsworth and B P Miller Using Cost to Control Instrumentation Overhead Theoretical Com puter Science 196 1 2 1998 pp 241 258 35 J K Hollingsworth B P Miller and J Cargille Dynamic Program Instrumentation for Scalable Perform ance Tools 1994 Scalable High Performance Computing Conf Knoxville Tenn pp 841 850 4 J K Hollingsworth B P Miller M J R Gon
37. _point gt amp points BPatch_callWhen when BPatch_callBefore BPatch_callAfter BPatch_snippetOrder order BPatch_firstSnippet Inserts a snippet of code at the specified point If a list of points is supplied insert the code snippet at each point in the list The when argument specifies when the snippet is to be called a value of BPatch_callBefore indicates that the snippet should be in serted just before the specified point or points in the code and a value of BPatch_callAfter indicates that it should be inserted just after The order argu ment specifies where the snippet is to be inserted relative to any other snippets previously inserted at the same point The values BPatch_firstSnippet and BPatch_lastSnippet indicate that the snippet should be inserted before or after all snippets respectively It is illegal to use BPatch_callAfter with a BPatch_entry point Use BPatch_callBefore when instrumenting entry points which inserts instrumentation before the first instruction in a subroutine Likewise it is illegal to use BPatch_callBefore with a BPatch_exit point Use BPatch_callAfter with exit points which inserts instrumentation at the last instruction in sub routine in sertSnippet will return NULL when used with an illegal pair of points deleteSnippet BPatchSnippetHandle handle Remove the snippet associated with the passed handle If the handle is not defined for the process then deleteSnippet will retu
38. all and easy to understand At the same time it needs to be sufficiently expressive to be useful for a variety of applications The way we have done this is by providing a simple set of abstractions and a simple way to specify the code to in sert into the application 2 ABSTRACTIONS The API is based on abstractions of a program and its state while in execution The two primary abstractions are points and snippets A point is a location in a program where instrumentation can be inserted A snippet is a representation of a bit of executable code to be inserted into a program at a point For example if we wished to record the number of times a procedure was invoked the To generate more complex code extra initially un called subroutines can be linked into the application program and calls to these subroutines can be inserted at runtime via this interface dyninstAPI Page 4 point would be the first instruction in the procedure and the snippets would be a statement to increment a counter Snippets can include conditionals function calls and loops The API is designed so that a single instrumentation process can insert snippets into multiple processes executing on a single machine To support multiple processes two additional abstrac tions processes and images are included in the API A process refers to one or more threads of execution and an address space Images refer to the static representation of a program on disk Images
39. areas APPENDIX D 1 Optimizing mutator performance Time in the Dyninst mutator is usually taken up by either parsing or instrumenting binaries When a new binary is loaded Dyninst will analyze the code looking for instrumentation points global variables and attempting to identify functions in areas of code that may not have symbols Upon user request Dyninst will also parse debug information from the binary which includes local variable line and type information All of these items are parsed lazily that is Dyninst won t try to generate this information until it is asked for Information is parsed on a per library basis so a request for information about a specific libary function will cause Dyninst to parse information about all functions in that library Much of the Dyninst parsing performance problems can be removed or mitigated by structuring the mutator application so that it only requests information from Dyninst if and when it needs it Not all operations require Dyninst to trigger parsing Some common operations that lead to pars ing are e Requesting a BPatch_instPoint object e Any operation on a BPatch_function other than getting its name Debugging information is lazily parsed separately from the rest of the binary parsing Accessing line type or local variable information will cause Dyninst to parse the debug information for all three of these Another common source of mutator time is spent re writing the mutatee
40. ateDominator Returns the basic block that immediately pre dominates this block in the control flow graph void getImmediateDominates BPatch_Vector lt BPatch_basicBlock gt amp Fills the given vector with a list of pointers to the basic blocks that are immediately domi nated by this basic block in the control flow graph dyninstAPI Page 50 void getAllDominates BPatch_Set lt BPatch_basicBlock gt 4 Fills the given vector with a list of pointers to all basic blocks that are dominated by this basic block in the control flow graph void getSourceBlocks BPatch_Vector lt BPatch_sourceBlock gt amp Fills the given vector with a list of source blocks contributing to this basic block s in struction sequence int getBlockNumber Returns the ID number of this basic block The ID numbers are consecutive from 0 to n where n is the number of basic blocks in the flow graph to which this basic block belongs BPatch_Vector lt BPatch_instruction gt getInstructions Returns a vector of the instructions that are contained within this basic block void getIncomingEdges BPatch_Vector lt BPatch_edge gt amp inc Fills the list inc with all of the control flow edges that point to this basic block BPatch_Vector lt BPatch_point gt findPoint const BPatch_Set lt BPatch_opCode gt amp ops Finds all points in the basic block that match the given operation void getOutgoingEdges BPatch_Vecto
41. ated and may not be present in future versions of Dyninst Consider using BPatch_process getSourceLines and BPatch_process getAddressRanges instead CAL VIHAdHA bool getLineAndFile int amp start int send char filename int max bool getLineToAddr unsigned short lineNo BPatch_Vector lt unsigned long gt amp buffer bool exactMatch true 4 6 Class BPatch_point An object of this class represents a location in an application s code at which the library can in sert instrumentation A BPatch_image object see section 4 7 is used to retrieve a BPatch_point representing a desired point in the application enum BPatch_procedurelocation BPatch_entry BPatch_exit BPatch_subroutine BPatch_address BPatch_procedureLocation getPointType Returns the type of the point BPatch_function getCalledFunction Returns a BPatch_function representing the function that is called at the point If the point is not a function call site or the target of the call cannot be determined then this function returns NULL BPatch_function getFunction Returns a BPatch_function representing the function in which this point is contained dyninstAPI BPatc void bool const Page 31 h_basicBlockLoop getLoop Returns the containing BPatch_basicBlockLoop if this point is part of loop instru mentation Returns NULL otherwise getAddress Returns the address of the first instruction at this point usesTrap_
42. ations between instructions Currently data dependence graph does not take aliases into consideration BPatch_dependenceGraphNode getControlDependenceGraph BPatch_instruction inst implemented on SPARC and x86 Returns a handle to the BPatch_dependenceGraphNode object used to navigate through the partial control dependence graph that includes the instruction inst and its predecessors or NULL if this information is not available A control dependence graph reflects the control dependence relations between instructions BPatch_dependenceGraphNode getProgramDependenceGraph BPatch_instruction inst implemented on SPARC and x86 Returns a handle to the BPatch_dependenceGraphNode object used to navigate through the partial program dependence graph that includes the instruction inst and its predecessors or NULL if this information is not available A program dependence graph is merely a union of data and control dependence graphs Currently program dependence graph does not take aliases into consideration dyninstAPI Page 30 BPatch_dependenceGraphNode getSlice BPatch_instruction inst implemented on SPARC and x86 Returns a handle to the BPatch_dependenceGraphNode object used to navigate through the intraprocedural slice of the function backwards from instruction inst Returns NULL if this information is not available Currently slice of a function does not take ali ases into consideration These functions are deprec
43. c ess n We need to use a callback and so the things that callback requires are made global this includes the file descriptor snippet see below BPatch_variableExpr fdVar NULL Before we add instrumentation we need to open the file for writing We can do this with a oneTimeCode a piece of code run at a particular time rather than at a particular location int openFileForWrite BPatch_process app BPatch_image appImage char fileName The code to be generated is fd open argv 2 O_WRONLY O_CREAT 0666 T 1 Find the open function BPatch_Vector lt BPatch_function gt openFuncs appImage gt findFunction open openFuncs if openFuncs size 0 fprintf stderr ERROR Unable to find function for open n return 1 2 Allocate a vector of snippets for the parameters to open BPatch_Vector lt BPatch_snippet gt openArgs dyninstAPI Page 65 3 Create a string constant expression from argv 3 BPatch_constExpr fileNameExpr fileName 4 Create two more constant expressions _WRONLY O_CREAT and 0666 BPatch_constExpr fileFlagsExpr O_WRONLY O_CREAT BPatch_constExpr fileModeExpr 0666 5 Push 3 4 onto the list from step 2 push first to last parameter openArgs push_back amp fileNameExpr openArgs push_back amp fileFlagsExpr openArgs push_back amp fileModeExpr
44. calves O Naim Z Xu and L Zheng MDL A Language and Compiler for Dynamic Program Instrumentation International Conference on Parallel Architectures and Compilation Techniques PACT Nov 1997 San Francisco pp 201 212 5 J R Larus and E Schnarr EEL Machine Independent Executable Editing PLDI June 18 21 1995 La Jolla CA ACM pp 291 300 dyninstAPI
45. d of the Dyninst mutator in this case ExitedNormally will be returned in both normal and signal exit cases int getExitCode If the process exited in a normal way getExitCode will return the associated exit code On AIX Solaris this code will not be available if the process was not a child of the Dyn inst mutator int getExitSignal bool If the process exited because of a received signal getExitSignal will return the associated signal number On AIX Solaris this code will not be available if the process was not a child of the Dyninst mutator loadLibrary const char libname bool reload false void Loads a dynamically linked library into the process s address space The libname pa rameter identifies the file name of the library to be loaded in the standard way that dy namically linked libraries are specified on the operating system on which the API is run ning This function returns true if the library was loaded successfully otherwise it returns false If reload is true then the library will be reloaded at startup by any rewritten bina ries produced with a call to BPatch_process dumpPatchedImage oneTimeCode const BPatch_snippet amp expr Causes snippet to be executed by the mutatee immediately If the process is multi threaded the snippet is run on a thread chosen by Dyninst If the user requires the snippet to be run on a particular thread use the BPat ch_thread version of this function in stead The
46. e BPatch_dataEnumerated Enumerated types are compatible if they have the same number of elements and the iden tifiers of the elements are the same BPatch_dataStructure BPatch_dataUnion Structures and unions are compatible if they have the same number of constituent parts fields and item by item each field is type compatible with the corresponds field of the other type In addition if either of the types is the type BPatch_unkownType then the two types are com patible Variables in mutatee programs that have not been compiled with debugging symbols or in the symbols are in a format that the Dyninst library does not recognize will be of type BPatch_unkownType dyninstAPI Page 60 5 USING THE API In this section we describe the steps needed to compile your mutator and mutatee programs and to run them First we give you an overview of the major steps and then we explain each one in detail 5 1 Overview of Major Steps To use Dyninst you have to 1 Create a mutator program Section 5 1 You need to create a program that will modify some other program For an example see the mutator shown in Section 6 2 Set up the mutatee Section 5 3 On some platforms you need to link your application with Dyninst s run time instrumentation library NOTE this step is only needed in the current release of the API Future releases will eliminate this restriction 3 Run the mutator Section 5 4 The mutator wil
47. e directory you need to create the directories i386 unknown nt4 0 bin and i386 unknown nt4 0 lib Next open the solution file core DyninstAPI sin with Visual Studio You can then build Dyninst by select Build Solution from the build menu This will build the Dyninst mutator library the runtime library and the test suite dyninstAPI Page 77 APPENDIX D DYNINST PERFORMANCE This appendix describes how to tune Dyninst for optimium performance During the course of a run Dyninst will perform several types of analysis on the binary make safety assumptions about instrumentation that is inserted and rewrite the binary perhaps several times Given some guidance from the user Dyninst can make assumptions about what work it needs to do and can deliver significant performance improvements There are two areas of Dyninst performance users typically care about First the time it takes Dyninst to parse and instrument a program This is typically the time it takes Dyninst to startup and analyze a program and the time it takes to modify the program when putting in instrumenta tion Second many users care about the time instrumentation takes in the modified mutatee This time is highly dependent on both the amount and type of instrumentation put it but it is still possible to eliminate some of the Dyninst overhead around the insturmentation The following subsections describe techniques for improving the performance of these two
48. e function will fail and return NULL The The size of the union is the size of the largest element in the fieldTypes vector The following functions are deprecated as of Dyninst 5 0 Please consider using processCreate processAttach and getProcesses instead dyninstA PI Page 12 BPatch_thread attachProcess const char path int pid BPatch_thread createProcess const char path char argv char envp NULL int stdin_fd 0 int stdout_fd 1 int stderr_fd 2 CAL VIHAdHA BPatch_Vector lt BPatch_thread gt getThreads 4 1 1 Callbacks The following functions are intended as a way for API users to be informed when an error or sig nificant event occurs Each function allows a user to register a handler for an event The return code for all callback registration functions is the address of the handler that was previously regis tered which may be NULL if no handler was previously registered For backwards compatibil ity reasons some callbacks may pass a BPatch_thread object when a BPatch_process may be more appropriate A BPatch_thread may be converted into a BPatch_process using BPatch_thread getProcess enum BPatchErrorLevel BPatchFatal BPatchSerious BPatchWarning BPatchInfo typedef void BPatchErrorCallback BPatchErrorlevel severity int number char params This is the prototype for the error callback function The severity field indicates how im portant the error is from fatal to informati
49. eaececececcensaaececececeeseaecesecscseseauaaesececeesesssaeeeeeceeceensaeas 45 4 13 CLASS B PATCH EDGE isi svscecocac eee Sbuse deca eedetes ik 47 4 14 CEASS BPATCH TOOPTREENODE ci ica 48 4 15 CLASS BPATCH BASICBLOGE ces 49 4 16 CLASS BPATCH_BASICBLOCKLOOP ccccccssssscecececeessaececececeeneaeaecececeeseseaececccsesesssaeeeeeeeesensaaes 51 4 17 EEASS BPATCH INSTRUCTION src dt aid caes ARS 52 4 18 CELASS BPATCH SOURCEBLOCK nba 52 4 19 CLASS BPATCH CBLOCR inte 53 4 20 CLASS BPATCH_FRAME ssssccssccscssssenccccccececsenseuceseceseensnaueesecscesnsnncesscescecesneenceesecsceessnncesecescessensee 53 4 21 CLASS BPATCH_DEPENDENCEGRAPHNODE sssssececeessssececececeesennecececcceeseaaeceecceceessaseeeeeeeseneaees 54 4 22 CLASS BPATCH_DEPENDENCEGRAPHEDGE cssccssccecsesessscecececeesenesececccsesesseaeceeseeesesssaseeeeeeeeessaaees 55 4 23 CONTAINER CLASSES cti a ie iaa 55 4 23 1 Class BPatch_VectOT oooconococonononononananonananananananananono nono nono no nono no nono na nano nana NOTESIE nano SEDENS SENE 55 4 232 Class BPateh Set dani inest 55 4 24 MEMORY ACCESS CLASSES a E ves van eines Uaseesesuneeeecpdcasevuveuveubeevesoes 57 4 24 1 Class BPatch_MemoryACceS scccsscccesecesssesessceessecuseceescecusecesacecaeeeeaeecaeeeeaeeceaeeeeaeecuaeeesaee 57 4 24 2 Class BPatch_addrSpec_NP rrr ornamata anisi eni EETA E REE E E RE S 58 49453 Class BP atCh COURTS pec NP neni a e E E O E ii e SaS 58 4 25 A Da SD
50. eates an empty set with the default comparison function BPatch_Set const BPatch_Set lt T Compare gt amp newBPatch_Set Copy constructor int size Returns the number of elements in the set bool empty Returns true if the set is empty or false if it is not dyninstAPI Page 56 void insert const T amp Inserts the given element into the set void remove const T amp Removes the given element from the set bool contains const T Returns true if the argument is a member of the set otherwise returns false T elements T Fills an array with a list of the elements in the set that are sorted in ascending order ac cording to the comparison function The input argument should point to an array large enough to hold the elements This function returns its input argument unless the set is empty in which case it returns NULL T minimum Returns the minimum element in the set as determined by the comparison function For an empty set the result is undefined T maximum Returns the maximum element in the set as determined by the comparison function For an empty set the result is undefined BPatch_Set lt T Compare gt amp operator const BPatch_Set lt T Compare gt The assignment operator bool operator const BPatch_Set lt T Compare gt 4 The equality operator Returns true if both sets consist entirely of elements that are each equal to an element in the other set or if bot
51. ecuted the oneTimeCode if thread specific or an undefined thread in the process if process wide The userData field contains the value passed to the one TimeCode call The returnValue field contains the return result of the oneTimeCode snippet dyninstAPI Page 16 BPatchOneTimeCodeCallback registerOneTimeCodeCallback BPatchOneTimeCodeCallback func Registers a function to be called when an application has completed a oneTimeCode 4 2 Class BPatch_process The BPatch_process class represents a running process which includes a one or more threads of execution and an address space const BPatch_image getlIlmage bool bool Return a handle to the executable file associated with this BPat ch_process object getSourceLines unsigned long addr std vector lt std pair lt const char unsigned int gt gt amp lines This function returns the line information associated with the mutatee address addr The vector lines contains pairs of filenames and line numbers that are associated with addr In many cases only one filename and line number is associated with an address but certain compiler optimizations may lead to multiple filenames and lines at an address This information is only available 1f the mutatee was compiled with debug information This function returns true if it was able to find any line information at addr and false otherwise getAddressRanges char fileName unsigned int lineNo
52. ecution of snippets for the process This provides a way to tempo rally disable all of the dynamic code patches that have been inserted without having to de lete them one by one All allocated memory will remain unchanged while the patches are disabled When the mutations are not active the process control functions i e stopExecution and continueExecution can still be used Requests to insert snippets including oneTimeCode cannot be made while mutations are disabled detach bool cont Detaches from the process The process must be stopped to call this function Instrumen tation and other changes to the process will remain active in the detached copy The cont parameter is used to indicate if the process should be continued as a result of detaching Linux does not support detaching from a process while leaving it stopped All processes are continued after detach on Linux dyninstA PI Page 21 int getPid Return the system id for the mutatee process On UNIX based systems this is a PID On Windows this is HANDLE object for a process typedef enum BPatch_exitType NoExit ExitedNormally ExitedViaSignal BPatch_exitType terminationStatus If the process has exited terminationStatus will indicate whether the process exited nor mally or because of a signal If the process has not exited NoExit will be returned On AIX Solaris the reason why a process exited will not be available if the process was not a chil
53. erwise dyninstAPI void bool void bool bool void Page 8 setTrampRecursive bool state Turn on or off trampoline recursion By default any snippets invoked while another snip pet is active will not be executed This is the safest behavior since recursively calling snippets can cause a program to take up all available system resources and die For exam ple adding instrumentation code to the start of printf and then calling printf from that snippet will result in infinite recursion This protection operates at the granularity of an instrumentation point When snippets are first inserted at a point code will be created with recursion protection or not depending on the current state of flag Changing the flag is not retroactive and inserting more snip pets will not change recursion protection at the point The recursion protection increases the overhead of instrumentation points so 1f there is no way for the snippets to call them selves then calling this method with the parameter true will result in a performance gain The default value of this flag is false isTrampRecursive Returns whether trampoline recursion is enabled or disabled True means that it is en abled setTypeChecking bool state Turn on or off type checking of snippets By default type checking is turned on and an attempt to create a snippet that contains type conflicts will fail Any snippet expressions created with type checking off have
54. f these values BPatch_countSpec_NP getByteCount_NP Returns a specification that describes the number of bytes transferred by the memory ac cess 4 24 2 Class BPatch_addrSpec_NP This class encapsulates the information required to determine an effective address at runtime The general representation for an address is a sum of two registers and a constant this may change in future releases Some architectures use only certain bits of a register e g bits 25 31 of XER register on the Power chip family these are represented as pseudo registers The number ing scheme for registers and pseudo registers is implementation dependent and should not be re lied upon it may change in future releases int getImm Returns the constant offset This may be positive or negative int getReg unsigned i Return the register number for the i th register in the sum where 0 lt 1 lt 2 Register numbers are positive a value of 1 means no register int getScale Returns any scaling factor used in the memory address computation 4 24 3 Class BPatch_countSpec_NP This class encapsulates the information required to determine the number of bytes transferred by a memory access In this release it is an alias for BPat ch_addrSpec_NP Do not rely on this implementation it may change in future releases 4 25 Type System The Dyninst type system is based on the notion of structural equivalence Structural equivalence was selected to allow
55. figured to use them We need to add the Debugging Tools include and library directories to Visual Studios search paths In Visual Studio 2003 select Options from the tools menu Next select Projects and VC Directories from the pane on the left You should see a list of directories that are dyninstAPI Page 76 sorted into categories such as Executable files Include files etc The current category can be changed with a drop down box in the upper right hand side of the Dialog First change to the Library files category and add an entry that points to C Program Files Debugging Tools for Windows sdk lib i386 Make sure that this entry 1s above Visual Studio s default search paths Next Change to the Include files category and make a new entry in the list that points to C Program Files Debugging Tools for Windows sdk inc Also make sure that this entry is above Visual Studio s default search paths Some users have had a problem where Visual Studio cannot find the cvconst h file You may need to add the directory contain ing this file to the include search path We have seen it installed at VCInstall Dir Visual Studio SDKs DIA SDK include although you may need to search for it Once you have installed and configured the Debugging Tools for Windows you are ready to build Dyninst First you need to create the directories where Dyninst will install its completed build From the cor
56. fined with different members in different functions a given common block may have multiple definitions The vector returned by this function contains one instance of BPatch_cblock for each unique definition of the common block If this method is invoked on a type whose BPatch_dataClass is not BPatch_common a NULL will be returned BPatch_type getConstituentType Returns the type of the base type For a BPatch_array this is the type of each ele ment fora BPatch_pointer this is the type of the object the pointer points to For BPatch_typedef types this is the original type For all other types NULL is re turned enum BPatch_dataClass BPatch_dataScalar BPatch_dataEnumerated BPatch_dataTypeClass BPatch_dataStructure BPatch_dataUnion BPatch_dataArray BPatch_dataPointer BPatch_dataReference BPatch_dataFunction BPatch_dataTypeAttrib BPatch_dataUnknownType BPatch_dataMethod BPatch_dataCommon BPatch_dataPrimitive BPatch_dataTypeNumber BPatch_dataTypeDefine BPatch_dataNullType BPatch_dataClass getDataClass Returns one of the above data classes for this type const char getLow const char getHigh Returns the string representation of the upper and lower bound of an array Calling these two methods on a non array types produces an undefined result const char getName Return the name of the type bool isCompatible const BPatch_type amp otype Returns true if the pas
57. geTramp bool Turn on or off inlined tramps Setting this value to true will make each base trampoline have all of its mini trampolines be inlined within it Using inlined mini tramps may al low instrumentation to execute faster but inserting and removing instrumentation may take more time The default setting for this is true isMergeTramp void bool void bool void This returns the current status of inlined trampolines A value of true indicates that tram polines are inlined setSaveFPR bool Turn on or off floating point saves Setting this value to false means that floating point registers will never be saved which can lead to large performance improvments The de fault value is true Setting this flag may cause incorrect program behavior if the instru mentation does clobber floating point registers so it should only be used when the user is positive this will never happen isSaveFPROn This returns the current status of the floating point saves True means we are saving float ing points based on the analysis for the given platform setBaseTrampDeletion bool If true we delete the base tramp when the last corresponding minitramp is deleted If false we leave the base tramp in The default value is false baseTrampDeletion Returns true if base trampolines are set to be deleted false otherwise setLivenessAnalysis bool If true we perform register liveness analysis around an instPo
58. h sets are empty bool operator const BPatch_Set lt T Compare gt amp The inequality operator Returns true if either set contains an element not in the other set BPatch_Set lt T Compare gt amp operatort const T amp Adds the given object to the set BPatch_Set lt T Compare gt amp operator const BPatch_Set lt T Compare gt 4 Set union operator Assigns the result of the union to the set on the left hand side BPatch_Set lt T Compare gt amp operator const BPatch_Set lt T Compare gt 4 Set intersection operator Assigns the result of the intersection to the set on the left hand side dyninstA PI Page 57 BPatch_Set lt T Compare gt amp operator const BPatch_Set lt T Compare gt 4 Set difference operator Assigns the difference of the sets to the set on the left hand side BPatch_Set lt T Compare gt operator const BPatch_Set lt T Compare gt 4 Set union operator BPatch_Set lt T Compare gt operator const BPatch_Set lt T Compare gt 4 Set intersection operator BPatch_Set lt T Compare gt operator const BPatch_Set lt T Compare gt 4 Set difference operator 4 24 Memory Access Classes Instrumentation points created through findPoint const BPatch_Set lt BPatch_opCode gt amp ops get memory access information attached to them This information is used by the memory access snippets but is also available to the API user The classes that encapsulate memory access infor mation are
59. his natural loop void getContainedLoops BPatch_Vector lt BPatch_basicBlockLoop gt 4 Fills the given vector with a list of the loops nested within this loop BPatch_flowGraph getFlowGraph Returns a pointer to the control flow graph that contains this loop BPatch_basicBlock getLoopHead Returns a pointer to the basic block that is at the head of this loop void getOuterLoops BPatch_Vector lt BPatch_basicBlockLoop gt 4 Fills the given vector with a list of the outer loops nested within this loop void getLoopBasicBlocks BPatch_Vector lt BPatch_basicBlock gt 4 Fills the given vector with a list of all basic blocks that are part of this loop void getLoopBasicBlocksExclusive BPatch_Vector lt BPatch_basicBlock gt amp Fills the given vector with a list of all basic blocks that are part of this loop but not its sub loops dyninstAPI Page 52 BPatch_basicBlock getLoopHead Returns the basic block at the head of this loop bool hasAncestor BPatch_basicBlockLoop Returns true 1f this loop is nested within the given loop the given loop is one of its ances tors in the tree of loops bool hasBlock BPatch_basicBlock b Returns true 1f this loop or any of its sub loops contain the basic block b false otherwise bool hasBlockExclusive BPatch_basicBlock b Returns true if this loop excluding its sub loops contain the basic block b false other wise 4 17 Class BPatch_instructio
60. int before inserting instru mentation and we only save registers that are live at that point This can lead to faster dyninstAPI bool bool void int BPat Page 10 run time speeds but at the expense of slower instrumentation time The default value is true livenessAnalysisOn Returns true if liveness analysis is currently enabled baseTrampDeletion getBPatchVersion int amp major int amp minor int amp subminor Returns Dyninst s version number The major version number will be stored in major the minor version number in minor and the subminor version in subminor For ex ample under Dyninst 5 1 0 this function will return 5 in major 1 in minor and 0 in subminor getNotificationFD Returns a file descriptor that is suitable for inclusion in a call to select Dyninst will write data to this file descriptor when it to signal a state change in the process BPatch pollForStatusChange should then be called so that Dyninst can handle the state change This is useful for applications where the user does not want to block in Bpatch waitForStatusChange The file descriptor will reset when the user calls BPatch pollForStatusChange ch_type createArray const char name BPatch_type ptr unsigned int low unsigned int hi Create a new array type The name of the type is name and the type of each element is ptr The index of the first element of the array is 1ow and the last is high The
61. ion the maximum number of arguments varies by platform and is summarized below If type checking is enabled the types of the passed arguments are checked against the function to be called Availability of type checking depends on the source language of the application and program being compiled for debugging Platform Maximum number of arguments Alpha 5 arguments AMD64 EMT 6 arguments 64 IA 32 No limit IA 64 No limit POWER 8 arguments SPARC 5 arguments dyninstAPI Page 41 BPatch_funcJumpExpr const BPatch_function amp func Defines a snippet that represents a non returning jump to function func Func must take the same number and type of arguments as the function in which this snippet is in serted these arguments will be passed to func Func must also have the same return type This snippet can be used to change the implementation of a function or condition ally change it if the snippet is part of an if statement When func returns control flows as a return from the function in which this snippet is inserted class BPatch_ifExpr const BPatch_boolExpr amp conditional const BPatch_snippet amp tClause const BPatch_snippet amp fClause class BPatch_ifExpr const BPatch_boolExpr amp conditional const BPatch_snippet amp tClause This constructor creates an if statement The first argument conditional should be a Boolean expression that will be evaluated
62. is function is deprecated Consider using getAddressRanges instead parseNewFunctions BPatch_Vector lt BPatch_module gt amp newModules const BPatch_Vector lt Dyninst Address gt amp funcEntryAddrs This function takes as input a list of function entry points indicated by the funcEntry Addrs vector which are used to seed parsing in whatever modules they are found All af fected modules are placed in the newModules vector which includes any existing mod ules in which new functions are found as well as modules corresponding to new regions of the binary for which new BPatch_modules are created The return value is true in the event that at least one previously unknown function was identified and false other wise 4 8 Class BPatch_module An object of this class represents a program module which is part of a program s executable im age A BPatch_module represents a source file in an executable or a shared library Dyninst automatically creates a module called DEFAULT_MODULE in each exectuable to hold any ob jects that it cannot match to a source file BPatch_module objects are obtained by calling the BPatch_image member function getModules BPatch_Vector lt BPatch_function gt findFunction const char name BPatch_Vector lt BPatch_function gt amp funcs bool notify_on_failure true bool regex_case_sensitive true bool incUninstrumentable false Returns a vector of BPatch_function s fo
63. l either create a new process or attach to an existing one depending on the whether createProcess or attachProcess is used Sections 5 2 through 5 4 explain these steps in more detail In addition Section 5 5 describes is sues related to specific hardware and operating systems In this section we assume that you have already installed the API distribution and setup the PLATFORM and DYNINST_ROOT environ ment variables The installation of the APT is described in the README file in the distribution tar file 5 2 Creating a Mutator Program The first step in using Dyninst is to create a mutator program The mutator program specifies the mutatee either by naming an executable to start or by supplying a process ID for an existing process In addition your mutator will include the calls to the API library to modify the mu tatee For the rest of this section we assume that the mutatee is the sample program given in Section 6 The following fragment of a Makefile shows how to link your mutator program with the Dyninst library on most platforms retee o retee c CC c CFLAGS IS DYNINST_ROOT core dyinstAPI h retee c ret ret 0 CC retee o LS DYNINST_ROOT lib S PLATEFORM A ldyninstAPI liberty o ret dyninstAPI Page 61 On Solaris and Linux the option lelf must also be added to the link step On Linux the option Idwarf must also be added to the link step On Solaris
64. ll be read For the first version of this method if the size of the variable is unknown e no type information no data is copied and the method re turns false bool writeValue void src void writeValue void src int size Changes the value of the variable in an application s address space that is represented by this BPatch_variableExpr The src parameter should point to a value of the vari able s type If the size parameter is supplied then the number of bytes it specifies will be written For the first version of this method if the size of the variable is unknown i e no type information no data is copied and the method returns false void getBaseAdar Returns the base address of the variable This is designed to let users who wish to access elements of arrays or fields in structures do so It can also be used to obtain the address of a variable to pass a point to that variable as a parameter to a procedure call It is similar to the ampersand 4 operator in C BPatch_Vector lt BPatch_variableExpr gt getComponents Returns a vector of the components of a struct or union Each element of the vector is one field of the composite type and contains a variable expression for accessing it 4 12 Class BPatch_flowGraph The BPatch_flowGraph class represents the control flow graph of a function It provides meth ods for discovering the basic blocks and loops within the function using which a caller can navi
65. mber of bytes accessed by a memory operation For most load store architecture machines it is a constant expression returning the number of bytes for the particular style of load or store This snippet is only valid at a memory operation instrumentation point BPatch_constExpr int value BPatch_constExpr long value BPatch_constExpr const char value BPatch_constExpr const void value Defines a constant snippet of the appropriate type The char form of the constructor creates a constant string the null terminated string beginning at the location pointed to by the parameter is copied into the application s address space and the BPatch_constExpr that is created refers to the location to which the string was copied BPatch_dynamicTargetExpr This snippet calculates the target of a control flow instruction with a dynamically deter mined target It can handle dynamic calls jumps and return statements BPatch_effectiveAddressesExpr Defines an expression that contains the effective address of a memory operation For a multi word memory operation i e more than the natural operation size of the ma chine the effective address is the base address of the operation BPatch_funcCallExpr const BPatch_function func const BPatch_Vector lt BPatch_snippet gt args Defines a call to a function the passed function must be valid for the current code region Args is a list of arguments to pass to the funct
66. mitations in the current implementations or reflect design decisions that may not produce the expected behavior from the system Attach followed by detach If a mutator attaches to a mutatee and immediately exists the current behavior is that the mutatee is left suspended To make sure the application continues call detach with the appropriate flags Attaching to a program that has already been modified by Dyninst If a mutator attaches to a program that has already been modified by a previous mutator a warning message will be issued We are working to fix this problem but the correct se mantics are still being specified Currently a message is printed to indicate that this has been attempted and the attach will fail Dyninst is event driven Dyninst must sometimes handle events that take place in the mutatee for instance when a new shared library is loaded or when the mutatee executes a fork or exec Dyninst han dles events when it checks the status of the mutatee so to allow this the mutator should periodically call one of the functions BPatch pollForStatusChange BPatch waitFor StatusChange BPatch_thread isStopped or BPatch_thread isTerminated 64 bit binaries Solaris Y AIX Dyninst does not support 64 bit binaries on Solaris or AIX Missing or out of date DbgHelp DLL Windows Dyninst requires an up to date DbgHelp library on Windows See the section on Win dows specific architectural issues for details Portland
67. n A BPatch_instruction represents a single machine instruction in the BPatch_flowGraph BPatch_instructions can be retrieved with the BPatch_basicBlock getInstructions call void getAddress This function returns the starting address of this instruction This function returns an address in the mutatee not in the mutator BPatch_point getInstPoint This function returns an BPatch_point at this instruction This point can be passed to BPatch_process insertSnippet to instrument this instruction 4 18 Class BPatch_sourceBlock An object of this class represents a source code level block Each source block objects consists of a source file and a set of source lines in that source file This class is used to fill source line in formation for each basic block in the control flow graph For each basic block in the control flow graph there is one or more source block object s that correspond to the source files and their lines contributing to the instruction sequence of the basic block const char getSourceFile Returns a pointer to the name of the source file in which this source block occurs dyninstAPI Page 53 void getSourceLines BPatch_Vector lt unsigned short gt amp Fills the given vector with a list of the lines contained within this source block 4 19 Class BPatch_cblock This class is used to access information about a common block BPatch_Vector lt BPatch_field gt getComponents Returns a
68. n 0 6 2 Instrumenting Memory Access There are two snippets useful for memory access instrumentation BPatch_effectiveAddressExpr and BPatch_bytesAccessedExpr Both have nullary constructors the result of the snippet de pends on the instrumentation point where the snippet is inserted BPatch_effectiveAddressExpr has type void while BPatch_bytesAccessedExpr has type int dyninstAPI Page 69 These snippets may be used to instrument a given instrumentation point if and only if the point has memory access information attached to it In this release the only way to create instrumenta tion points that have memory access information attached to them is via BPatch_function findPoint const BPatch_Set lt BPatch_opCode gt amp For example to instrument all the loads and stores in a function named foo with a call to another fuction bar that takes one argument the effective address one may write assuming that thr points to some interesting thread BPatch_proc proc BPatch_image img proc gt getImage build the set that describes the type of accesses we re looking for BPatch_Set lt BPatch_opCode gt axs axs insert BPatch_opLoad axs insert BPatch_opStore scan the function foo and create instrumentation points BPatch_Vector lt BPatch_function gt fooFunctions img gt findFunction foo fooFunctions BPatch_Vector lt BPatch_point gt r fooFunctions 0 gt findPoint axs create the p
69. n call at the specified location The point specified must be a valid call point in the image of the requesting process The purpose of this routine is to permit tools to alter the semantics of a program by eliminating procedure calls The mechanism to achieve the removal is platform dependent but might include branching over the call or replacing it with NOPs This function only removes a function call any parameters to the function will still be evaluated replaceCode BPatch_point point BPatch_snippet snippet Replaces the instruction identified by point with the provided snippet The provided point may represent either a specific instruction acquired via BPatch_function findPoint function entry function exit or a call site If the point corresponds to a function entry the first instruction in the function will be re placed If the point corresponds to a function exit the return instruction at that exit will be replaced If the point corresponds to a call site the call instruction will be replaced If the point corresponds to a control flow edge replacement will fail and an error will be re turned This call returns true 1f the replacement succeeded or false otherwise The replacement mechanism uses similar techniques as our instrumentation mechanism and can fail in the same circumstances dyninstA PI bool Page 20 WARNING This function is dangerous Unlike instrumentation program state is not saved and restored a
70. nclude BPatch_process h include BPatch_function h include BPatch_Vector h dyninstAPI Page 64 include BPatch_thread h retee C This program mutator provides an example of several facets of Dyninst s behavior and is a good basis for many Dyninst mutators We want to intercept all output from a target application the mutatee duplicating output to a file as well as the original destination e g stdout This mutator operates in several phases In brief 1 Attach to the running process and get a handle BPatch_process object 2 Get a handle for the parsed image of the mutatee for function lookup BPatch_image object 3 Open a file for output 3a Look up the open function 3b Build a code snippet to call open with the file name 3c Run that code snippet via a oneTimeCode saving the returned file descriptor 4 Write the returned file descriptor into a memory variable for mutatee side use 5 Build a snippet that copies output to the file 5a Locate the write library call 5b Access its parameters 5c Build a snippet calling write fd parameters 5d Insert the snippet at write 6 Add a hook to exit to ensure that we close the file using a callback at exit and another oneTimeCode Se a r a E A A E E QR SE RR A OE void usage fprintf stderr Usage retee lt process pid gt lt filename gt n fprintf stderr note lt filename gt is relative to the application pro
71. nding on parameters passed and each test may execute multiple times with different parameters and on different mutatees Dyninst s test space can be very large Each mutatee can be run under different tests compiled by different compilers and run with different parameters For example one point in this space would be the test mutatee being run under under test1_13 when compiled with the g com piler and in attach mode When run without any options the test_driver will run all test combinations that are valid on the current platform Many of the options that are passed to test_driver can be used to limit the test space that it runs in In order to prevent a crashing test from stopping the test_driver from running subsequent tests test_driver can be run under a wrapper application runTests The runTests wrapper invokes the test_driver with the any arguments that were passed to runTests It will watch the test_driver process and if test_driver exits with a fault it will print an appropriate error message and restart the test_driver on the next test It is generally recommended that runTests be used when running a large sequence of tests and test_driver be used when debugging issues with a single test The test_driver and runTests applications can be invoked with the following list of ar guments Most arguments are used to limit the space of tests that the testsuite will run For ex ample to run the above test1_13 example you could use
72. ngEdges methods which will return a list of other BPat ch_dependenceGrapNode objects Currently successor list of a node may not be exhaustive BPatch_dependenceGraphNode BPatch_instruction bpinst Constructor It takes a pointer to a BPatch_instruction object which represents the instruction this node holds BPatch_dependenceGraphNode BPatch_instruction bpinst BPatch_Vector lt BPatch_dependenceGraphNode gt predecessorlist BPatch_Vector lt BPatch_dependenceGraphNode gt successorlist Constructor It takes a BPat ch_instruction parameter which represents the instruc tion this node holds a list of pointers to other BPat ch_dependenceGraphNode ob jects which are immediate predecessors of this node and a list of pointers to other BPatch_dependenceGraphNode objects which are immediate successors of this node BPatch_instruction getBPInstruction void void bool bool Returns a pointer to the BPatch_instruction that this node represents getOutgoingEdges BPatch_Vector lt BPatch_ dependenceGraphkEdge gt amp out Fills the given vector with the outgoing edges successors get IncomingEdges BPatch_Vector lt BPatch_ dependenceGraphEdge gt amp inc Fills the given vector with the incoming edges predecessors isImmSuccessor BPatch_dependenceGraphNode other_node Returns true if other_node is an immediate successor of this instruction if there exists an edge between this
73. ninst will recognize snippets that Page 80 do operations like var constant or var and turn these into optimized assembly instructions that take advantage of CISC machine instructions dyninstA PI BPatch_thread 23 A attachProcess 7 11 B BPatch_addrSpec_NP 53 BPatch_arithExpr 36 BPatch_basicBlockLoop 47 BPatch_boolExpr 36 BPatch_breakPointExpr 37 BPatch_bytesAccessedExpr 37 65 BPatch_cblock 49 BPatch_constExpr 37 BPatch_countSpec_NP 54 BPatch_effectiveAddressesExpr 37 BPatch_flowGraph 42 BPatch_funcCallExpr 37 BPatch_function 24 BPatch_ifExpr 38 BPatch_image 29 BPatch_memoryAccess 52 BPatch_module 32 Bpatch_nullExpr 40 BPatch_opCode 26 Bpatch_paramExpr 38 39 BPatch_point 28 BPatch_retExpr 36 39 BPatch_sequence 39 BPatch_Set 50 BPatch_snippet 35 BPatch_sourceBlock 49 BPatch_sourceObj 24 BPatch_tidExpr 40 BPatch_type 40 BPatch_variableExpr 41 BPatch_Vector 50 BPatchErrorCallback 12 14 BPatchErrorLevel 12 14 19 24 BPatchPostForkCallback 13 BPatchThreadEventCallback 12 14 C Class BPatch_basicBlock 44 46 continueExecution 15 22 createArray 10 dyninstA PI Page 81 createEnum 10 createInstPointAtAddr 29 createPointer 11 createProcess 7 11 createScalar 10 createStruct 11 createTypedef 11 createUnion 11 D deleteSnippet 17 23 detach 19 20 23 dominates 46 dumpCore
74. node and other_node among outgoing edges isImmPredecessor BPatch_dependenceGraphNode other_node Returns true if other_node is an immediate predecessor of this instruction if there exists an edge between this node and other_node among incoming edges dyninstAPI Page 55 4 22 Class BPatch_dependenceGraphEdge A BPatch_dependenceGraphEdge represents an edge between two BPatch_dependenceGraphNode objects BPatch_dependenceGraphEdge BPatch_dependenceGraphNode source BPatch_dependenceGraphNode target Constructor source is the source of this edge while target is the target BPatch_dependenceGraphNode getSource Returns the dependence graph node which is the source of this edge BPatch_dependenceGraphNode getTarget Returns the dependence graph node which is the target of this edge 4 23 Container Classes 4 23 1 Class BPatch_Vector The BPatch_Vector class is a container used to hold other objects used by the API As of Dyn inst 5 0 BPatch_Vector is an alias for the C STL std vector 4 23 2 Class BPatch_Set BPatch_Set is another container class similar to the set class in the Standard Template Library STL It maintains a collection of objects and provides fast lookup Elements are ordered by a comparison function which can be user supplied This allows for efficiently returning a sorted list of elements or returning the value of the minimum or maximum element BPatch_Set A constructor that cr
75. nst char name BPatch_Vector lt char gt fieldNames BPatch_Vector lt BPatch_type gt fieldTypes Create a new structure type The name of the structure is specified in the name parame ter The fieldNames and fieldTypes vectors specify fields of the type These two vectors must have the same number of elements or the function will fail and return NULL The standard rules of type compatibility described in Section 4 25 are used with structures created using this function The size of the structure is the sum of the size of the elements in the fieldTypes vector BPatch_type createTypedef const char name BPatch_type ptr Create a new type called name and having the type ptr BPatch_type createPointer const char name BPatch_type ptr BPatch_type createPointer const char name BPatch_type ptr int size Create a new type named name which points to objects of type pt r The first form cre ates a pointer whose size is equal to sizeof void on the target platform where the mutatee is running In the second form the size of the pointer is the value passed in the size parameter BPatch_type createUnion const char name BPatch_Vector lt char gt fieldNames BPatch_Vector lt BPatch_type gt fieldTypes Create a new union type The name of the union is specified in the name parameter The fieldNames and fieldTypes vectors specify fields of the type These two vectors must have the same number of elements or th
76. nst org BUILDING ON UNIX Building Dyninst on UNIX platforms is a four step process that involves unpacking the Dyninst source installing any Dyninst dependencies configuring paths in make config local and running the build Dyninst s source code is packaged in a tar gz format If your Dyninst source tarball is called srcDist_v5 0 tar gz then you could extract it with the command gunzip srcDist_v5 0 tar gz tar xvf srcDist_v5 0 tar This will create two di rectories core and scripts Dyninst has several dependencies depending on what platform you are using which must be in stalled before Dyninst can be built Note that for most of these packages Dyninst needs to be able to access the package s include files which means that development versions are required If a version number is listed for a packaged then there are known bugs that may affect Dyninst with earlier versions of the package Linux x86 libdwarf 20060327 libelf Linux IA 64 libdwarf 20060327 libunwind 0 98 5 libelf Linux x 86 64 libdwarf 20060327 libelf Solaris Sparc No external dependencies AIX Power No external dependencies At the time of this writing the Linux packages could be found at e libdwarf http reality sgiweb org davea dwarf html e libelf http www mr511 de software english html e libunwind http www hpl hp com research linux libunwind download php4 Once the dependencies for Dyninst have been installed Dyninst must be c
77. o be called when a process terminates For a normal process exit the callback will actually be called just before the process exit when the process is at the en try to the exit function except for Windows This allows final actions to be taken on the process before it actually exits The function BPatch_thread isTerminated will re turn true in this context even though the process hasn t yet actually exited In the case of an exit due to a signal the process will have already exited On AIX Solaris OSF the rea son why a process exited may not be available if the process was not a child of the Dyn inst mutator the mutator will be notified of the process exiting typedef void BPatchDynLibraryCallback Bpatch_thread thr Bpatch_module mod bool load This is the prototype for the dynamic linker callback function The thr field contains the thread that loaded or un loaded a shared library The mod field contains the module that was loaded or unloaded The load Boolean is true if the library was loaded and false if it was unloaded BPatchThreadEventCallback registerDynLinkCallback BPatchThreadEventCallback func Registers a function to be called when an application has loaded or unloaded a dynamic library typedef void BPatchOneTimeCodeCallback Bpatch_thread thr void userData void returnValue This is the prototype for the oneTimeCode callback function The thr field contains the thread that ex
78. of the buffer parameter dyninstA PI Page 27 bool getNames BPatch_vector lt const char gt names Adds all known names of the function to the vector names including names generated by weak symbols It returns true if one or more names were added and false otherwise The names reside in memory managed by Dyninst bool getMangledNames BPatch_vector lt const char gt names As above but returns all known mangled internal symbol names bool getTypedNames BPatch_vector lt const char gt names As above but returns all known function prototypes BPatch_Vector lt BPatch_localVar gt getParanms Returns a vector of BPatch_localVar snippets that refer the parameters of this func tion The position in the vector corresponds to the position in the parameter list starting from zero The returned local variables can be used to check the types of functions and be used in snippet expressions BPatch_type getReturnType Returns the type of the return value for this function BPatch_Vector lt BPatch_localVar gt getVars Returns a vector of BPatch_localVar that contain the local variables in this function These BPatch_localVars can be used as parts of snippets in instrumentation This function requires debug information to be present in the mutatee If Dyninst was unable to find any local variables this function will return an empty vector It is up to the user to free the vector returned by this function
79. on status The number is a unique number that identifies this error message Params are the parameters that describe the detail about an error e g the process id where the error occurred The number and meaning of params depends on the error However for a given error number the number of parame ters returned will always be the same BPatchErrorCallback registerErrorCallback BPatchErrorCallback func This function registers the error callback function with the BPatch class The return value is the address of the previous error callback function Dyninst users can change the error callback during program execution e g one error callback before a GUI is initialized and a different one after dyninstA PI Page 13 typedef void BPatchSignalHandlerCallback BPatch_point at_point long signum BPatch_Vector lt Dyninst Address gt handlers This is the prototype for the signal handler callback function The at_point parameter in dicates the point at which the signal exception was raised signum is the number of the signal exception that was raised and the handlers vector contains any registered han dler s for the signal exception In Windows this corresponds to the stack of Structured Exception Handlers while for Unix systems there will be at most one registered excep tion handler As of April 15 2008 this functionality is only fully implemented for the Windows platform BPatchSignalHandlerCallback registe
80. onfigured to know where to find these packages This is done through Dyninst s core make config local file This file must be written in GNU Makefile syntax and must specify directory locations for each dependency Specifically LIBDWARFDIR LIBELFDIR and TCLTK_DIR variables must be set LIBDWARFDIR should be set to the absolute path of libdwarf library where dwarf h and libdwarf h files reside LIBELFDIR should be set to the absolute path where 1i dyninstAPI Page 75 belf a and libelf so files are located Finally TCLTK_DIR variable should be set to the base directory where Tcl is installed The next thing is to set DYNINST_ROOT PLATFORM and LD_LIBRARY_PATH environ ment variables DYNINST_ROOT should be set to path of the directory that contains core and scripts subdirectories PLATFORM should be set to one of the following values depending upon what operating system you are running on alpha dec osf5 1 Tru64 UNIX on the Alpha processor 1386 unknown linux2 4 Linux 2 4 2 6 on an Intel x86 processor 1a64 unknown linux2 4 Linux 2 4 2 6 on an IA 64 processor rs6000 ibm aix5 1 AIX Version 5 1 sparc sun solaris2 9 Solaris 2 9 on a SPARC processor x86_64 unknown linux2 4 Linux 2 4 2 6 on an AMD 64 processor LD_LIBRARY_PATH variable should be set in a way that it includes libdwarf home directo ry lib and DYNINST_ROOT PLATFORM lib directories Once make config local is set you are ready to build Dyninst Change to the core direc
81. ool removeFunctionCall BPatch_point point bool replaceFunction BPatch_function old BPatch_function amp new bool replaceFunctionCall BPatch_point point BPatch_function amp newFunc void setInheritSnippets bool inherit void setMutationsActive bool BPatch_image getImage void detach bool cont int getPid BPatch_exitType terminationStatus int getExitCode int getExitSignal bool loadLibrary const char libname bool reload false BPatch_thread 4 4 Class BPatch_sourceObj The BPatch_sourceObj class is the C super class for the BPatch_function BPatch_module and BPatch_image classes It provides a set of common methods for all three classes In addi tion it can be used to build a generic source navigator using the getObjParent and getSour ceObj methods to get parents and children of a given level i e the parent of a module is an im age and the children will be the functions enum BPatchErrorLevel BPatchFatal BPatchSerious BPatchWarning BPatchInfo dyninstAPI Page 26 enum BPatch_sourceType BPatch_sourceUnknown BPatch_sourceProgram BPatch_sourceModule BPatch_sourceFunction BPatch_sourceOuterLoop BPatch_sourceLoop BPatch_sourceStatement BPatch_sourceType getSrcType Returns the type of the current source object void getSourceObj BPatch_Vector lt BPatch_sourceObj gt amp objs
82. own in Figure 1 b Note that the additions in Figure 1 are shown in bold OBJECTS main o this o that o LIBDIR SDYNINST_ROOT 1ib SPLATFORM bubba pd OBJECTS CC OBJECTS lt insert any additional modules here gt lm lcurses ltermcap o bubba pd b The Link Command Modified to Run Application Items in Bold face show the changes additions Figure 1 Changing Your Makefile to Link an Application as a Dyninst mutatee Note some platforms require a few additional options see Section 5 5 5 4 Running the Mutator At this point you should be ready to run your application program with your mutator For exam ple to start the sample program shown in Section 6 o retee foo lt pid gt 5 5 Architectural Issues Certain platforms require slight modifications to the procedures discussed above In this subsec tion we describe each of them in turn dyninstAPI Page 63 5 5 1 Solaris When using the Sun C or Fortran compilers specify the xs option together with g The g op tion alone will direct the compiler to place debugging information in the object files o files but it will not place the debugging information on the executable a out file Use the xs option so that the compiler will add the debugging information to the a out file The xs option is not needed when using gcc The following is an example of linking on Solaris OBJECTS main o this o that o LIBDIR
83. p gt getImage The code to be generated is close fd 2 Find close BPatch_Vector lt BPatch_function gt closeFuncs appImage gt findFunction close closeFuncs if closeFuncs size 0 fprintf stderr ERROR Unable to find function for close n return 3 Allocate a vector of snippets for the parameters to open BPatch_Vector lt BPatch_snippet gt closeArgs 4 Add the fd snippet fdVar is global since we can t get it via the callback closeArgs push_back fdVar 5 create a procedure call using function found at 1 and parameters from step 3 BPatch_funcCallExpr closeCall closeFuncs 0 closeArgs 6 The oneTimeCode returns whatever the return result from the BPatch_snippet is In this case the return result of open gt the file descriptor void ret app gt oneTimeCode closeCall 7 Tell the app to continue to finish it off app gt continueExecution return BPatch bpatch In main we perform the following operations 1 Attach to the process and get BPatch_process and BPatch_image handles 2 Open a file descriptor 3 Instrument write 4 Continue the process and wait for it to terminate int main int argc char argv int pid if argc 3 usage exit 1 pid atoi argv 1 Attach to the program we can attach with just a pid the program name i
84. process This call back is invoked just before the fork is performed When the callback is invoked the thread performing the fork will be stopped BPatchPostForkCallback registerPostForkCallback BPatchPostForkCallback func not implemented on Windows Registers a function to be called just after the fork is performed Both the thread perform ing the fork and the newly created thread will be paused when the callback is invoked Unless a post fork callback is registered the mutator will not be attached to any child processes Since there is overhead associated with each tracked process not setting the callback allows the Dyninst library to ignore any child processes This is particularly use ful for instrumenting shell processes that create many potentially uninteresting children dyninstAPI Page 15 typedef enum BPatch_exitType NoExit ExitedNormally ExitedViaSignal typedef void BPatchExitCallback BPatch_thread proc BPatch_exitType exit_type This is the prototype for the callback function called when a process exit occurs The proc parameter is the process which exited The exit_type parameter indicates how the process exited either normally or because of a signal The functions BPatch_thread getExitCode and BPatch_thread getExitSignal can be used to get fur ther information about the process exit BPatchThreadEventCallback registerExitCallback BPatchExitCallback func Registers a function t
85. program s file name up to Len characters The file name may include path information getSourceObj BPatch_Vector lt BPatch_sourceObj gt amp sources Fills the parameter vector sources with the source objects see section 4 4 that be long to this image If there are no source objects the function returns false Otherwise it returns true const BPatch_Vector lt BPatch_function gt getProcedures bool incUninstrumentable false Returns a table of the functions in the image If the incUninstrumentable flag is set the returned table of procedures will in clude uninstrumentable functions The default behavior is to omit these functions const BPatch_Vector lt BPatch_module gt getModules Returns a vector of the modules in the image bool getVariables BPatch_Vector lt BPatch_variableExpr gt amp vars Fills the parameter vector vars with the global variables defined in this image If there are no variable the function returns false Otherwise it returns true dyninstAPI Page 33 BPatch_Vector lt BPatch_function gt findFunction const char name BPatch_Vector lt BPatch_function gt amp funcs bool showError true bool regex_case_sensitive true bool incUninstrumentable false bool dont_use_regex false Returns a vector of BPatch_function s for the function name defined or NULL if the function does not exist If name contains a POSIX extended regular expression and don
86. r can be NULL since the executable image can be derived from the process pid A process attached to using one of these functions is put into the stopped state The proc essCreate function creates a new process and returns a new BPatch_process associ ated with it The new process is put into a stopped state before executing any code The stdin_fd stdout_fd and stderr_fd parameters are used to set the stan dard input output and error of the child process The default values of these parameters leave the input output and error to be the same as the mutator process To change these values an open UNIX file descriptor see open 1 can be passed pollForStatusChange This is useful for a mutator that needs to periodically check on the status of its managed threads and does not want to have to check each process individually It returns t rue if there has been a change in the status of one or more threads that has not yet been reported by either isStopped or isTerminated setDebugParsing bool state Turn on or off the parsing of debugger information By default the debugger information produced by the g compiler option is parsed on those platforms that support it How ever for some applications this information can be quite large To disable parsing this in formation call this method with a value of false prior to creating a process parseDebugIinfo Returns t rue if debugger information parsing is enabled false oth
87. r lt BPatch_edge gt out Fills the list out with all of the control flow edges that leave this basic block unsigned long getStartAddress This function returns the starting address of the basic block The address returned is an absolute address unsigned long getEndAddress This function returns the end address of the basic block The address returned is an abso lute address unsigned long getLastInsnAddress Returns the address of the last instruction in a basic block bool isEntryBlock This function returns true if this basic block is an entry block into a function bool isExitBlock This function returns true if this basic block is an exit block of a function dyninstAPI Page 51 unsigned size Returns the size of a basic block The size is defined as the difference between the end address and the start address of the basic block 4 16 Class BPatch_basicBlockLoop An object of this class represents a loop in the code of the application being instrumented bool containsAddress unsigned long addr Returns true if addr is contained within any of the basic blocks that compose this loop excluding the block of any of its sub loops bool containsAddressInclusive unsigned long addr Returns true if addr is contained within any of the basic blocks that compose this loop or in the blocks of any of its sub loops BPatch_edge getBackEdge Returns a pointer to the back edge that defines t
88. r the function name defined or NULL if the function does not exist If name contains a POSIX extended regular expression a re gex search will be performed on function names and matching BPatch_functions re turned NOTE the BPatch_Vector argument funcs must be declared fully by the user before calling this function passing in an uninitialized reference will result in undefined behavior If the incUninstrumentable flag is set the returned table of procedures will in clude uninstrumentable functions The default behavior 1s to omit these functions dyninstA PI Page 36 NOTE if name is not found to match any demangled function names in the module the search is repeated as 1f name is a mangled function name If this second search suc ceeds functions with mangled names matching name are returned instead BPatch_function findFunctionByMangled const char mangled_name bool incUninstrumentable false Return a BPatch_funct ion for the C mangled function name defined in the mod ule corresponding to the invoking BPatch_module or NULL if it does not define the function If the incUninstrumentable flag is set the returned table of procedures will in clude uninstrumentable functions The default behavior 1s to omit these functions size_t getAddressWidth bool bool Returns the size in bytes of a pointer in this module On 32 bit systems this function will return 4 and on 64 bit systems this function
89. rSignalHandlerCallback BPatchSignalHandlerCallback func BPatch_Set lt long gt signal_numbers This function registers the signal handler callback function with the BPatch class The re turn value indicates success or failure The signal_numbers set contains those signal num bers for which which the callback will be invoked As of April 15 2008 this functional ity is only fully implemented for the Windows platform typedef void BPatchStopThreadCallback BPatch_point at_point void returnValue This is the prototype for the callback that is associated with the stopThreadExpr snippet class see Section 4 9 Unlike the other callbacks in this section stopThreadExpr call backs are registered during the creation of the stopThreadExpr snippet type Whenever a stopThreadExpr snippet executes in a given thread he snippet evaluates the calcula tion snippet that stopThreadExpr takes as a parameter stops the thread s execution and invokes this callback The at_point parameter is the BPatch_point at which the stop ThreadExpr snippet was inserted and returnValue contains the computation made by the calculation snippet typedef void BPatchAsyncThreadEventCallback bool BPatch_process proc BPatch_thread thread This is the prototype for most callback functions associated with events that occur in a thread such as thread creation and destruction events The thread parameter is the thread that triggered the event
90. readCallback amp callback const BPatch_snippet amp calculation This snippet evaluates the calculation snippet and stops the thread that executes 1t The result of the calculation snippet is passed up to the mutator which triggers the callback in the user program This constructor registers the callback to the stopThreadExpr instance The same callback may be used for different stopThreadExpr instances See the definition of BPatchStopThreadCallback in Section 4 1 1 BPatch_threadIndex This snippet returns an integer expression that contains the thread index of the thread that 1s executing this snippet The thread index is the same value that is returned on the muta tor side by BPatch_thread getBPatchID dyninstA PI Page 43 BPatch_tidExpr const BPatch_process proc This snippet results in an integer expression that contains the tid of the thread that is exe cuting this snippet This can be used to record the threadId or to filter instrumentation so that it only executes for a specific thread BPatch_nullExpr Defines a null snippet This snippet contains no executable statements however it is a useful place holder for the destination of a goto For example using goto and a nullExpr a while loop can be constructed For example to construct the while loop while i lt 3 i The following snippets should be created BPatch_nullExpr loopDone if i gt 3 goto loopDone First definition is
91. red or replicated between two snippets is implemen tation dependent const BPatch_type getType Returns the type of the snippet The BPatch_type system is described in section 4 10 float getCost Returns an estimate of the number of seconds it would take to execute the snippet The problems with accurately estimating the cost of executing code are numerous and out of the scope of this document 2 It is important to realize that the returned cost value is at best an estimate The rest of the classes are derived classes of the class BPatch_snippet BPatch_actualAddressExpr This snippet results in an expression that evaluates to the actual address of the instrumen tation To access the original address where instrumentation was inserted use BPatch_originalAddressExpr Note that this actual address is highly dependent on a number of internal variables and has no relation to the original address dyninstAPI Page 39 BPatch_arithExpr BPatch_binOp op const BPatch_snippet lOperand const BPatch_snippet amp rOperand Performs the required binary operation The available binary operators are Operator Description BPatch_assign assign the value of rOperand to 10perand BPatch_plus add 1Operand and rOperand BPatch_minus subtract rOperand from 1Operand BPatch_divide divide rOperand by lOperand BPatch_times multiply rOperand by 1Operand BPatch_ref Array reference of the form
92. rintf function call snippet Patch_Vector lt BPatch_snippet gt printfArgs Patch_constExpr fmt Access at d n rintfArgs push_back amp fmt Patch_effectiveAddressExpr eae rintfArgs push_back amp eae Patch_Vector lt BPatch_function gt funcs mg gt findFunction printf funcs Patch_function printfFunc funcs 0 Patch_funcCallExpr printfCall printfFunc printfArgs w wrew WO wwx insert the snippet at the instrumentation points thr gt insertSnippet printfCall r dyninstA PI Page 70 APPENDIX A RUNNING THE TEST CASES This section describes how to run the Dyninst test cases The primary purpose of the test cases 1s to verify that the API has been installed correctly and for use in regression testing by the devel opers of the Dyninst library The code may also be of use to others since it provides a fairly complete example of how to call most of the API methods The test suite consists of mutator programs and their associated mutatee programs To compile the testsuite type make in the appropriate platform specific directory under core testsuite To run execute the runTests Each test will be executed and the result PASSED FAILED CRASHED printed Test mutators are run by the test_driver executable test_driver exe on Windows The test_driver loads a mutator test from a shared object and runs it on a test mutatee A single run of the test_driver may execute multiple tests depe
93. riteFuncs 0 writeArgs 3 Identify the BPatch_point for the entry of write We re instrumenting the function with itself normally the findPoint call would operate off a different function than the snippet BPatch_Vector lt BPatch_point gt points points writeFuncs 0 gt findPoint BPatch_entry if points size 0 return false 4 Insert the snippet at the start of write return app gt insertSnippet writeCall points Note we have just instrumented write with a call to write This would ordinarily be a _bad thing_ as there is nothing to stop infinite recursion write gt instrumentation gt write gt instrumentation However Dyninst uses a feature called a tramp guard to prevent this and it s on by default This function is called as an exit callback that is called immediately before the process exits when we can still affect it and thus must match the exit callback signature typedef void BPatchExitCallback BPatch_thread BPatch_exitType Note that the callback gives us a thread and we want a process but each thread has an up pointer dyninstA PI Page 67 void closeFile BPatch_thread thread BPatch_exitType fprintf stderr Exit callback called for process n 1 Get the BPatch_process and BPatch_images BPatch_process app thread gt getProcess BPatch_image appImage ap
94. rma tion about this class getTid This function returns a platform specific identifier for this thread This is the identifier that is used by the threading library For example on pthread applications this function will return the thread s pthread_t value get LWP This function returns a platform specific identifier that the operating system uses to iden tify this thread For example on UNIX platforms this returns the LWP id On Windows this returns a HANDLE obect for the thread dyninstAPI long Page 23 getBPatchID This function returns a Dyninst specific identifier for this thread These ID s apply only to running threads the BPatch ID of an already terminated thread my be repeated in a new thread BPatch_function getInitialFunction Returns the function that was used by the application to start this thread For example on pthread applications this will return the initial function that was passed to pthread_create unsigned long getStackTopAddr bool Returns the base address for this thread s stack isDeadOnArrival This function returns true if this thread terminated execution before Dyninst was able to attach to it Since Dyninst performs new thread detection asynchronously it is possible for a thread to be created and destroyed before Dyninst can attach to it When this hap pens a new BPatch_thread is created but isDeadOnArrival always returns true for this thread Is i
95. rn false dyninstAPI bool Page 19 bool beginInsertionSet Normally a call to insertSnippet immediately injects instrumentation into the mutatee However users may wish to insert a set of snippets as a single batch operation This pro vides two benefits First instrumentation may be inserted in a more efficient manner by Dyninst Second multiple snippets may be inserted at multiple points as a single opera tion with either all snippets being inserted successfully or none This batch insertion mode is begun with a call to beginInsertionSet after this call no snippets are ac tually inserted until a corresponding call to finalizeInsertionSet All calls to insertSnippet during batch mode are accumulated internally by Dyninst and the re turned BPatchSnippetHandles are filled in when finalizeInsertionSet is called finalizelnsertionSet bool atomic bool bool Inserts all snippets accumulated since a call to beginInsertionSet If the atomic pa rameter is true then a failure to insert any snippet results in all snippets being removed effectively the insertion is all or nothing If the atomic parameter is not set then snippets are inserted individually This function also fills in the BPatchSnippetHandle struc tures returned by insertSnippet It returns true on success and false if there was an error inserting any snippets removeFunctionCall BPatch_point point Disables the user functio
96. round the new code The provided snippet may modify registers and memory This call may have unexpected effects on program execution resulting in incor rect results or program crashes replaceFunction BPatch_function amp old BPatch_function amp new Replaces all calls to user function old with calls to new This is done by inserting in strumentation specifically a BPatch_funcJumpExpr into the beginning of function old such that a non returning jump is made to function new Returns true upon success false otherwise bool replaceFunctionCall BPatch_point amp point BPatch_function amp newFunc void void Changes the function call at the specified point to the function indicated by newFunc The purpose of this routine is to permit runtime steering tools to change the behavior of pro grams by replacing a call to one procedure by a call to another Point must be a function call point If the change was successful the return value is true otherwise false will be re turned WARNING Care must be used when replacing functions In particular if the compiler has performed inter procedural register allocation between the original caller callee pair the replacement may not be safe since the replaced function may clobber registers the compiler thought the callee left untouched Also the signatures of the both the func tion being replaced and the new function must be compatible setMutationsActive bool Enable or disable the ex
97. rpose registers Dyninst may decide to seperatly save any float Save Floating Point Registers ing point registers that may be corrupted by instrumentation Generate A Stack Frame Dyninst builds a stack frame for instrumenta dyninstAPI Page 79 tion to run under this provides the illusion to instrumentation that it is running as its own function Calculate an index value that identifies the cur Calculate Thread Index rent thread This is primarly used as input to the Trampoline Guard Test to see if we are already recursively execut Test and Set Trampoline Guard ing under instrumentation and skip the user instrumentation if we are Execute User Instrumentation Execute any BPatch_snippet code Unset Trampoline Guard Marks the this thread as no longer being in in strumentation Clean the stack frame that was generated for Clean Stack Frame instrumentation Restore Floating Point Registers Restore the floating point registers to their original state Restore General Purpose Registers Restore the general purpose registers to their original state Dyninst will attempt to eliminate as much of its overhead as is possible The Dyninst user can assist Dyninst by doing the following dyninstAPI Write BPatch_snippet code that avoids making function calls Dyninst will at tempt to perform analysis on the user written instrumentation to determine which gen
98. s illegal to perform any thread level operations on a DeadOnArrival thread BPatch_process getProcess Returns the BPatch_process that contains this thread void oneTimeCode const BPatch_snippet amp expr bool Causes the snippet to be evaluated by the process immediately This is similar to the BPatch_process oneTimeCode function except that the snippet is guarenteed to run only on this thread The process must be stopped to call this function The behavior is syn chronous oneTimeCode will not return until after the snippet has been run in the applica tion oneTimeCodeAsync const BPatch_snippet amp expr void userData NULL This function sets up a snippet to be evaluated by this thread at the next available oppor tunity When the snippet finishes running Dyninst will callback any function registered through BPatch registerOneTimeCodeCallback with userData passed as a parameter This function returns true if expr was posted and false otherwise dyninstAPI Page 24 This is similar to the BPatch_process oneTimeCodeAsync function except that the snip pet is guarenteed to run only on this thread The process must be stopped to call this func tion The behavior is asynchronous oneTimeCodeAsync returns before the snippet is executed The following BPatch_thread functions are deprecated as of Dyninst 5 0 Please consider using the equivalent functions in the BPatch_process class
99. s no longer necessary fprintf stderr Attaching to process d n pid BPatch_process app bpatch processAttach NULL pid dyninstAPI Page 68 if app return 1 Read the program s image and get an associated image object BPatch_image appImage app gt get Image BPatch_Vector lt BPatch_function gt writeFuncs fprintf stderr Opening file s for write n argv 2 int fileDescriptor openFileForWrite app applImage argv 2 if fileDescriptor 1 fprintf stderr ERROR opening file s for write failed n argv 2 exit 1 fprintf stderr Writing returned file descriptor d into mutatee n fileDescriptor This was defined globally as the exit callback needs it fdVar writeFileDescIntoMutatee app appImage fileDescriptor if fdVar NULL fprintf stderr ERROR failed to write mutatee side variable n exit 1 fprintf stderr Instrumenting write n bool ret interceptAndCloneWrite app appImage fdVar if ret fprintf stderr ERROR failed to instrument mutatee n exit 1 fprintf stderr Adding exit callback n bpatch registerExitCallback closeFile Continue the execution fprintf stderr Continuing execution and waiting for terminationin app gt continueExecution while app gt isTerminated bpatch waitForStatusChange printf Done n retur
100. sed type is type compatible with this type The rules for type com patibility are given in Section 4 23 2 If the two types are not type compatible the error reporting callback function will be invoked one or more times with additional informa tion about why the types are not compatible 4 11 Class BPatch_variableExpr The BPatch_variableExpr class is another class derived from BPatch_snippet It repre sents a variable or area of memory in a process s address space A BPatch_variableExpr dyninstA PI Page 45 can be obtained from a BPatch_process using the malloc member function or from a BPatch_image using the findVariable member function Some BPatch_variableExpr have an associated BPatch_type which can be accessed by functions inherited from BPatch_snippet BPatch_variableExpr objects will have an associated BPatch_type if they originate from binaries with sufficient debug information that describes types or if they were provided with a BPat ch_t ype when created by Dyninst BPatch_variableExpr provides several member functions not provided by other types of snippets bool readValue void dst void readValue void dst int size Reads the value of the variable in an application s address space that is represented by this BPatch_variableExpr The dst parameter is assumed to point to a buffer large enough to hold a value of the variable s type If the size parameter is supplied then the number of bytes it specifies wi
101. ss p This function fills the vector v with the list of functions that are called by this loop const char getCalleeName unsigned int i This function return the name of the i function called in the loop s body unsigned int numCallees Returns the number of callees contained in this loop s body BPatch_basicBlockLoop findLoop const char name Finds the loop object for the given canonical loop name 4 15 Class BPatch_basicBlock The BPatch_basicBlock class represents a basic block in the application being instrumented Objects of this class representing the blocks within a function can be obtained using the BPatch_flowGraph object for the function BPatch_basicBlock includes methods for navigating through the control flow graph of the containing function void getSources BPatch_Vector lt BPatch_basicBlock gt amp Fills the given vector with the list of predecessors for this basic block i e basic blocks that have an outgoing edge in the control flow graph leading to this block void getTargets BPatch_Vector lt BPatch_basicBlock gt amp Fills the given vector with the list of successors for this basic block i e basic blocks that are the destinations of outgoing edges from this block in the control flow graph bool dominates BPatch_basicBlock This function returns true if the argument is pre dominated in the control flow graph by this block and false if it is not BPatch_basicBlock getImmedi
102. std vector lt std pair lt unsigned long unsigned long gt gt ranges Given a filename and line number fileName and lineNo this function this function returns the ranges of mutatee addresses that implement the code range in the output pa rameter ranges In many cases a source code line will only have one address range im plementing it however compiler optimizations may turn this into multiple disjoint ad dress ranges This information is only available if the mutatee was compiled with debug information This function returns t rue if it was able to find any line information false otherwise dyninstAPI bool bool boo Page 17 stopExecution continueExecution terminateExecution bool int bool BPat BPat void BPat These three functions change the running state of the process stopExecution puts the process into a stopped state Depending on the operating system stopping one process may stop all threads associated with a process cont inueExecution continues execu tion of the process terminateExecution terminates execution of the process and will invoke the exit callback if one is registered Each function returns true on success or false for failure Stopping or continuing a termiated thread will fail and these functions will return false isStopped stopSignal isTerminated These three functions query the status of a process isStopped returns true if the proc ess is c
103. t have to re compile re link or even re execute the pro gram to change the binary At first thought this may seem like a bizarre goal however there are several practical reasons we may wish to have such a system For example if we are measuring the performance of a program and discover a performance problem it might be necessary to in sert additional instrumentation into the program to understand the problem Another application is performance steering for large simulations computational scientists often find it advantageous to be able to make modifications to the code and data while the simulation is executing This document describes an Application Program Interface API to permit the insertion of code into a running program The API also permits changing or removing subroutine calls from the application program Runtime code changes are useful to support a variety of applications includ ing debugging performance monitoring and to support composing applications out of existing packages The goal of this API is to provide a machine independent interface to permit the crea tion of tools and applications that use runtime code patching The API and a simple test applica tion are described in 1 This API is based on the idea of Dynamic Instrumentation described in 3 The key feature of this interface is that it makes it possible to insert and change instrumentation in a running program The goal of this API is to keep the interface sm
104. tVar Retrieves a new handle to an existing variable such as one created by BPatch_process malloc that was created in a parent process and now exists in a forked child process When a process forks all existing BPatch_variableExprs are copied to the child process but the Dyninst handles for these objects are not valid in the dyninstA PI Page 18 child BPatch_process This function is invoked on the child process BPatch_process parentVar is a variable from the parent process and a handle to a vari able in the child process is returned IfparentVar was not allocated in the parent proc ess then NULL is returned BPatchSnippetHandle getInheritedSnippet BPatchSnippetHandle amp parentSnippet This function is similar to getInheritedVariable but operates on BPatchSnippetHandles Given a child process that was created via fork and a BpatchSnippetHandle parentSnippet from the parent process this function will return a handle to parent Snippet that is valid in the child process If it is deter mined that parent Snippet is not associated with the parent process then NULL is re turned BPatchSnippetHandle insertSnippet const BPatch_snippet amp expr BPatch_point amp point BPatch_callWhen when BPatch_callBefore BPatch_callAfter BPatch_snippetOrder order BPatch_firstSnippet BPatchSnippetHandle insertSnippet const BPatch_snippet amp expr bool const BPatch_Vector lt BPatch
105. t_use_regex is false a regex search will be performed on function names and matching Bpatch_functions returned If showError is true then dyninst will report and error via the BPatch registerErrorCallback if no function is found If the incUninstrumentable flag is set the returned table of procedures will in clude uninstrumentable functions The default behavior is to omit these functions NOTE if name is not found to match any demangled function names in the module the search is repeated as if name is a mangled function name If this second search suc ceeds functions with mangled names matching name are returned instead BPatch_Vector lt BPatch_function gt findFunction BPatch_Vector lt BPatch_function gt amp funcs BPatchFunctionNameSieve bpsieve void sieve_data NULL int showError 0 bool incUninstrumentable false Return a vector of BPat ch_functions according to the generalized user specified fil ter function bpsieve This permits users to easily build sets of functions according to their own specific criteria Internally for each BPatch_function fin the image this method makes a call to bpsieve f getName sieve_data The user specified function bpsieve is responsible for taking the name argument and determin ing if it belongs in the output vector possibly by using extra user provided information stored in sieve_data If the name argument matches the desired criteria bpsieve should return true If it
106. tch_locLoopStartIter BPatch_locLoopEndIter BPatch_Vector lt BPatch_point gt findLoopInstPoints const BPatch_procedureLocation loc BPatch_basicBlockLoop loop Finds instrumentation points for the given loop that correspond to the given location loop entry loop exit the start of a loop iteration and the end of a loop iteration BPatch_locLoopEntry and BPatch_locLoopExit instrumentation points re spectively execute once before the first iteration of a loop and after the last iteration BPatch_locLoopStartIter and BPatch_locLoopEndIter respectively exe cute at the beginning and end of each loop iteration dyninstAPI Page 47 NOTE Dyninst is not always able to generate a correct flowgraph in the presence of indirect jumps If a function has a case statement or indirect jump instructions the targets of the jumps are found by searching instruction patterns peep hole The instruction patterns generated are compiler specific and the control flow graph analysis include only the ones we have seen During the control flow graph generation if a pattern that is not handled is used for case statement or multi jump instructions in the function address space the generated control flow graph may not be complete 4 13 Class BPatch_edge The BPatch_edge class represents a control flow edge in a BPatch_flowGraph BPatch_point getPoint Returns an instrumentation point for this edge This point
107. the boolean expression The second generates the goto and the if statement BPatch_boolExpr testFlag BPatch_gt intI BPatch_constExpr 3 BPatch_ifExpr test testFlag BPatch_gotoExpr loopDone 1 itt BPatch_arithExpr addOne BPatch_assign intI BPatch_arithExpr BPatch_plus intI BPatch_constExpr 1 BPatch_Vector lt BPatch_snippet gt statements statements push_back test statements push_back amp addOne statements push_back amp loopDone BPatch_sequence whileLoop statements 4 10 Class BPatch_type The class BPatch_type is used to describe the types of variables parameters return values and functions Instances of the class can represent language predefined types e g int float mutatee defined types e g structures compiled into the mutatee application or mutator defined types created using the create methods of the BPatch class BPatch_Vector lt BPatch_field gt getComponents Returns a vector of the types of the fields in a BPatch_struct or BPatch_union If this method is invoked on a type whose BPatch_dataClass is not BPatch_struct or BPatch_union NULL is returned BPatch_Vector lt BPatch_cblock gt getCblocks Returns the common block classes for the type The methods of the BPatch_cblock can be used to access information about the member of a common block Since the same dyninstA PI Page 44 named or anonymous common block can be de
108. the entry and exit points of the sub routine BPatch_subroutine returns the list of points where the procedure calls other pro cedures If the lookup fails to locate any points of the requested type NULL is returned enum BPatch_opCode BPatch_opLoad BPatch_opStore BPatch_opPrefetch BPatch_Vector lt BPatch_point gt findPoint const BPatch_Set lt BPatch_opCode gt amp ops Returns the vector of BPatch_points corresponding to the set of machine instruction types described by the argument This version is used primarily for memory access instrumenta tion The BPatch_opCode is an enumeration of instruction types that may be requested BPatch_opLoad BPatch_opStore and BPatch_opPrefetch Any combination of these may be requested by passing an appropriate argument set containing the desired types The instrumentation points created by this function have additional memory access in formation attached to them This allows such points to be used for memory access spe cific snippets e g effective address The memory access information attached is de scribed under Memory Access classes in section 4 24 1 BPatch_localVar findLocalVar const char name Searches the function s local variable collection for a given name This returns a pointer to the local variable if a match is found This function returns NULL if it fails to find any variables BPatch_Vector lt BPatch_variableExpr gt findVariable const char name Re
109. the following command line test_driver run test1_13 mutatee testl mutatee_g attach dyninstA PI Page 71 attach Only run tests that attach to the mutates create Only run tests that create mutates mutatee lt mutatee_name gt Only run tests that use the specified mutate name Only certain mutatees can be run with certain tests The primary test number specifies which mutatees it can be run with For example all of the testl_ tests can be run with the testl mutatee_ mutatees and all of the test2_ tests can be run with the test2 mutatee_ mutatees run lt subtest gt lt subtest gt Only runs the specific sub tests listed For example to run sub test case 4 of test2 you would enter test_driver run test2_4 log Print more detailed output including messages generated by the tests Without this op tion the testsuite will capture and hide any messages printed by the test only showing a summary of whether the test passed or failed By default output is sent to stdout logfile lt filename gt Send output from the 1log option to the given filename rather than to stdout verbose Enables testsuite debugging output This is useful when trying to track down issues in the testsuite or tests dyninstAPI Page 72 APPENDIX B COMMON PITFALLS This appendix is designed to point out some common pitfalls that users have reported when using the Dyninst system Many of these are either due to li
110. the option Istdc must be added to the link step On Compaq Tru64 UNIX the option Imld must also be supplied On AIX the option lbsd must also be added to the link step You will also need to make sure that the LD_LIBRARY_PATH or LIBPATH AIX environment variable includes the directory that con tains the Dyninst shared library This is typically SD YNINST_ROOT lib SPLATFORM Some of these libraries such as libdwarf and libelf may not be standard on various platforms Check the README file in core dyninstAPI for more information on where to find these librar ies Under Windows NT the mutator also needs to be linked with the doghelp library which is included in the Microsoft Platform SDK Below is a fragment from a Makefile for Windows NT CC cl retee obj retee c CC c CFLAGS IS DYNINST_ROOT core dyninstAPI h retee exe retee obj link out retee exe retee obj DYNINST_ROOT lib S PLATFORM libdyninstAPI lib A dbghelp lib 5 3 Setting Up the Application Program mutatee On most platforms you can instrument unmodified binary a out files However there is a base shared library that needs to be available to be loaded into your application by the mutator and you may wish to create library of pre compiled instrumentation routines that you mutator will insert calls to On most platforms any additional code that your mutator might need to call in the mutatee for
111. turns a set of variables matching name at the scope of this function If no variables match in the local scope then the global scope will be searched for matches This func tion returns NULL if it fails to find any variables dyninstAPI Page 29 BPatch_localVar findLocalParam const char name Searches the function s parameters for a given name A BPatch_localVar pointer is re turned if a match is found and NULL is returned otherwise void getBaseAdar Returns the starting address of the function in the mutatee s address space BPatch_flowGraph getCFG Returns the control flow graph for the function or NULL if this information is not avail able The BPatch_flowGraph is described in section 4 12 bool findOverlapping BPatch_Vector lt BPatch_function gt funcs Determines which other functions overlap with the current function see Section 2 Re turns true if other functions overlap the current function the overlapping functions are added to the funcs vector Returns false if no other functions overlap the current function BPatch_dependenceGraphNode getDataDependenceGraph BPatch_instruction inst implemented on SPARC and x86 Returns a handle to the BPatch_dependenceGraphNode object used to navigate through the partial data dependence graph that includes the instruction inst and its prede cessors or NULL if this information is not available A data dependence graph reflects the data dependence rel
112. urrently stopped If the process is stopped as indicated by isStopped then stopSignal can be called to find out what signal caused the process to stop isTer minated returns true if the process has exited Any of these functions may be called multiple times and calling them will not affect the state of the process ch_variableExpr malloc int n ch_variableExpr malloc const BPatch_type amp type These two functions allocate memory Memory allocation is from a heap The heap is not necessarily the same heap used by the application The available space in the heap may be limited depending on the implementation The first function malloc int n allo cates n bytes of memory from the heap The second function malloc const BPatch_type t allocates enough memory to hold an object of the specified type Using the second version is strongly encouraged because it provides additional informa tion to permit better type checking of the passed code The returned memory is persistant and will not be released until BPatch_process free is called or the application ter minates free const BPatch_variableExpr amp ptr Frees the memory in the passed ptr The programmer is responsible to verify that all code that could reference this memory will not execute again either by removing all snippets that refer to it or by analysis of the program ch_variableExpr getInheritedVariable const BPatch_variableExpr amp paren
113. veRegisters int amp size implemented for POWER and AMD64 Returns an array of dimension size associated with the live general purpose registers for this point The array slot is a direct map to the register number A value of 1 means the register is live 0 means the register is dead isDynamic This call returns true if this is a dynamic call site e g a call site where the function call is made via a function pointer 4 7 Class BPatch_image This class defines a program image the executable associated with a process The only way to get a handle to a BPatch_image is via the BPatch_process member function getImage dyninstAPI Page 32 const BPatch_point createlnstPointAtAddr caddr_t address Returns an instrumentation point at the specified address This function is designed to permit users who wish to insert instrumentation at an arbitrary place in the code segment Instruction addresses can be found using the BPatch_instruction object see section 4 17 On x86 platforms users should take care to ensure that the requested point is not in the middle of a multi byte instruction BPatch_Vector lt BPatch_variableExpr gt getGlobalVariables Returns a vector of global variables that are defined in this image BPatch_process getProcess char bool Returns the BPatch_process associated with this image getProgramFileName char name unsigned int len Fills provided buffer name with the
114. w override the original store address insn overrideStoreAddress newStoreAddr dyninstA PI Page 42 We now replace the original instruction with the new one Point is a BPatch_point corresponding to the desired location and process is a BPatch_process process replaceCode point insn BPatch_originalAddressExpr This snippet results in an expression that evaluates to the original address of the point where the snippet was inserted To access the actual address where instrumentation is executed use BPatch_actual AddressExpr BPatch_paramExpr int paramNum This constructor creates an expression whose value is a parameter being passed to a func tion ParamNum specifies the number of the parameter to return starting at 0 Since the contents of parameters may change during subroutine execution this snippet type is only valid at points that are entries to subroutines or when inserted at a call point with the when parameter set to BPatch_callBefore BPatch_retExpr This snippet results in an expression that evaluates to the return value of a subroutine This snippet type is only valid at BPatch_exit points or at a call point with the when parameter set to BPatch_callAfter BPatch_sequence const BPatch_Vector lt BPatch_snippet gt amp items Defines a sequence of snippets The passed snippets will be executed in the order in which they appear in the list BPatch_stopThreadExpr const BPatchStopTh
115. will return 8 getSourceLines unsigned long addr std vector lt std pair lt const char unsigned int gt gt amp lines This function returns the line information associated with the mutatee address addr The vector lines contains pairs of filenames and line numbers that are associated with addr In many cases only one filename and line number is associated with an address but certain compiler optimizations may lead to multiple filenames and lines at an address This information is only available if the mutatee was compiled with debug information This function may be more efficient than the BPatch_process version of this func tion Calling BPatch_process getSourceLines will cause Dyninst to parse line information for all modules in a process If BPatch_module getSourceLines is called then only the debug information in this module will be parsed This function returns true if it was able to find any line information at addr and false otherwise getAddressRanges char fileName unsigned int lineNo std vector lt std pair lt unsigned long unsigned long gt gt ranges Given a filename and line number fileName and 1ineNo this function this function returns the ranges of mutatee addresses that implement the code range in the output pa rameter ranges In many cases a source code line will only have one address range im plementing it however compiler optimizations may turn this into multiple disjoint ad
116. y called saveTheWorld which we don t worry about here and so is false bool ret fdVar gt writeValue void amp fileDescriptor sizeof int false if ret false return NULL return fdVar We now have an open file descriptor in the mutatee We want to instrument write to intercept and copy the output That happens here bool interceptAndCloneWrite BPatch_process app BPatch_image applImage BPatch_variableExpr fdVar dyninstAPI Page 66 1 Locate the write call BPatch_Vector lt BPatch_function gt writeFuncs appImage gt findFunction write writeFuncs if writeFuncs size 0 fprintf stderr ERROR Unable to find function for write n return false 2 Build the call to our write Arguments are ours fdVar file descriptor parameter buffer parameter buffer size Declare a vector to hold these BPatch_Vector lt BPatch_snippet gt writeArgs Push on the file descriptor writeArgs push_back fdVar Well we need the buffer but that s a parameter to the function we re implementing That s not a problem we can grab it out with a BPatch_paramExpr BPatch_paramExpr buffer 1 Second 0 1 2 argument BPatch_paramExpr bufferSize 2 writeArgs push_back amp buffer writeArgs push_back amp bufferSize Gl GI And build the write call BPatch_funcCallExpr writeCall w

Dyninst User Manual - Home Page - University of Wisconsin–Madison

Contents

Download Pdf Manuals

Related Search

Related Contents

Dyninst User Manual - Home Page - University of Wisconsin&ndash;Madison

Contents

Download Pdf Manuals

Related Search

Related Contents

Dyninst User Manual - Home Page - University of Wisconsin–Madison