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

Class 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 Detail

      • 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 Detail

      • 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​(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

      • 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

      • runAllPaths

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