Module openj9.dtfj
Package com.ibm.j9ddr.corereaders.tdump.zebedee.le

Class FunctionEmulator

java.lang.Object
com.ibm.j9ddr.corereaders.tdump.zebedee.le.FunctionEmulator
public class FunctionEmulator extends Object
This class acts as a more convenient way of using the Emulator class. Because it is in the LE package it adds the following benefits:
  • it knows the XPLINK calling conventions
  • sets up the stack automatically
  • can obtain a function address and environment from a function name
  • provides tracing including function entry and exit

  • Constructor Details

    • FunctionEmulator

      public FunctionEmulator(AddressSpace space, String functionName) throws IOException, NoSuchMethodException
      Create a new FunctionEmulator.
      Parameters:
      space - the AddressSpace containing the code and data we are to use
      functionName - the name of the function to call
      Throws:
      NoSuchMethodException - if the given function can't be found
      IOException

    • FunctionEmulator

      public FunctionEmulator(AddressSpace space, long functionEntryPoint, long functionEnv) throws IOException, NoSuchMethodException
      Create a new FunctionEmulator. This is a raw form where the address of the function entry point and env are supplied. Note that the so-called "environment" pointer is not required by all functions. It is the value that is stored in R5. If you do need to know it you can sometimes find it by looking in the DSA of the function to find the saved value (assuming the dump has the function in one of the stacks!).
      Parameters:
      space - the AddressSpace containing the code and data we are to use
      functionEntryPoint - the address of the function entry point
      functionEnv - the address of the "environment" for the function (not all functions require this to be set)
      Throws:
      NoSuchMethodException - if the given function can't be found
      IOException

  • Method Details

    • getStackFloor

      public long getStackFloor()
      Return the xplink stack floor. Be careful with this.

    • createDummyReturnAddress

      public long createDummyReturnAddress() throws IOException
      Register a dummy return address. When this is branched to we simply stop the emulator
      Throws:
      IOException

    • setPrintOffsets

      public void setPrintOffsets(boolean printOffsets)
      Include instruction offsets from the start of the function when tracing. XXX doesn't yet work for called functions

    • setInstructionTracing

      public void setInstructionTracing(boolean instructionTrace)
      Turn instruction tracing on or off. A trace of all instructions executed will be sent to System.out.

    • setInstructionRecording

      public void setInstructionRecording(boolean instructionRecord)
      Turn instruction recording on or off. A trace of all instructions executed will be saved.

    • getTraceEntries

      public List getTraceEntries()
      Return a list of the instruction trace entries

    • setBranchInstructionTracing

      public void setBranchInstructionTracing(boolean branchInstructionTrace)
      Turn branch instruction tracing on or off. A trace of all branch instructions executed will be sent to System.out.

    • setCallTreeCapture

      public void setCallTreeCapture()
      Turn call tree capturing on. The call tree may be retrieved with getCallTreeRoot().

    • getCallTreeRoot

      public FunctionEmulator.Function getCallTreeRoot()
      Returns the root of the call tree. setCallTreeCapture() must have been called prior to the emulator having run. These routines can be used to obtain the actual call tree during a run of the emulator. Note that the root function is a dummy one.

    • getCurrentFunction

      public FunctionEmulator.Function getCurrentFunction()
      Returns the current function. User callbacks can make use of this.

    • getEmulator

      public Emulator getEmulator()
      Returns the Emulator object we use.

    • setArgument

      public void setArgument(int argNumber, int value)
      Sets the given function argument.
      Parameters:
      argNumber - the number of the argument to be set, starting at one (XXX currently limited to a max of 3)
      value - the value of the argument

    • setArgument

      public void setArgument(int argNumber, long value)
      Sets the given function argument.
      Parameters:
      argNumber - the number of the argument to be set, starting at one (XXX currently limited to a max of 3)
      value - the value of the argument

    • getArgument

      public long getArgument(int argNumber)
      Gets the given function argument. To be used from callback functions.
      Parameters:
      argNumber - the number of the argument to be got, starting at one

    • getMutableAddressSpace

      public MutableAddressSpace getMutableAddressSpace()
      Returns the MutableAddressSpace used by the emulator. This can be used by users wishing to allocate space for input arguments for instance.

    • registerCallbackFunction

      public long registerCallbackFunction(FunctionEmulator.CallbackFunction callback)
      Registers a callback function.
      Returns:
      the address of the linkage pointer. This is what you put in place of a C function pointer.

    • overrideFunction

      public void overrideFunction(String functionName, FunctionEmulator.CallbackFunction callback) throws IOException, NoSuchMethodException
      Allows the given function to be "overridden". The supplied callback function will be called rather than the real one.
      Parameters:
      functionName - the name of the function to override
      callback - the user function that will be called rather than the real one
      Throws:
      IOException
      NoSuchMethodException

    • overrideFunction

      public void overrideFunction(long functionEntryPoint, FunctionEmulator.CallbackFunction callback) throws IOException, NoSuchMethodException
      Allows the given function to be "overridden". The supplied callback function will be called rather than the real one. This is the raw version of overrideFunction that takes the address of the function.
      Parameters:
      functionEntryPoint - the address of the function entry point
      callback - the user function that will be called rather than the real one
      Throws:
      IOException
      NoSuchMethodException

    • overrideFunction

      public void overrideFunction(String functionName, long retVal, boolean protect)

    • overrideFunction

      public void overrideFunction(String functionName, long returnValue)

    • run

      public long run() throws IOException
      Now run the emulator. This method returns when the emulated function returns.
      Returns:
      the return value from the function (if any)
      Throws:
      IOException

    • run

      public long run(long functionPointer) throws IOException
      Run the emulator using the supplied xplink C function pointer. This method returns when the emulated function returns.
      Returns:
      the return value from the function (if any)
      Throws:
      IOException

    • run

      public long run(String functionName) throws IOException, NoSuchMethodException
      Run the emulator using the supplied xplink C function. This method returns when the emulated function returns.
      Returns:
      the return value from the function (if any)
      Throws:
      IOException
      NoSuchMethodException

    • recordCalledFunctions

      public void recordCalledFunctions() throws IOException
      Run the emulator and record any called functions as new DllFunctions. The purpose of this method is to obtain the entry points for functions which are not in the export list for a DLL. The emulator is run and any functions called are saved as fake DllFunction entries which may then be obtained using Dll.getFunction(java.lang.String).
      Throws:
      IOException

    • recordAllCalledFunctions

      public void recordAllCalledFunctions() throws IOException
      Throws:
      IOException

    • runAllPaths

      public void runAllPaths() throws IOException
      Run all paths of the function. This is used for disassembly.
      Throws:
      IOException