Package ghidra.app.emulator

Class EmulatorHelper

    • Constructor Detail

      • EmulatorHelper

        public EmulatorHelper​(Program program)

    • Method Detail

      • dispose

        public void dispose()

      • getProgram

        public Program getProgram()

      • getPCRegister

        public Register getPCRegister()
        Get Program Counter (PC) register defined by applicable processor specification
        Returns:
        Program Counter register

      • getStackPointerRegister

        public Register getStackPointerRegister()
        Get Stack Pointer register defined by applicable compiler specification
        Returns:
        Stack Pointer register

      • setMemoryFaultHandler

        public void setMemoryFaultHandler​(MemoryFaultHandler handler)
        Provides ability to install a low-level memory fault handler. The handler methods should generally return 'false' to allow the default handler to generate the appropriate target error. Within the fault handler, the EmulateExecutionState can be used to distinguish the pcode-emit state and the actual execution state since an attempt to execute an instruction at an uninitialized memory location will cause an uninitializedRead during the PCODE_EMIT state.
        Parameters:
        handler - memory fault handler.

      • getEmulateExecutionState

        public EmulateExecutionState getEmulateExecutionState()
        Returns:
        the low-level emulator execution state

      • readRegister

        public java.math.BigInteger readRegister​(Register reg)

      • readRegister

        public java.math.BigInteger readRegister​(java.lang.String regName)

      • writeRegister

        public void writeRegister​(Register reg,
                          long value)

      • writeRegister

        public void writeRegister​(java.lang.String regName,
                          long value)

      • writeRegister

        public void writeRegister​(Register reg,
                          java.math.BigInteger value)

      • writeRegister

        public void writeRegister​(java.lang.String regName,
                          java.math.BigInteger value)

      • readNullTerminatedString

        public java.lang.String readNullTerminatedString​(Address addr,
                                                 int maxLength)
        Read string from memory state.
        Parameters:
        addr - memory address
        maxLength - limit string read to this length. If return string is truncated, "..." will be appended.
        Returns:
        string read from memory state

      • readMemoryByte

        public byte readMemoryByte​(Address addr)

      • readMemory

        public byte[] readMemory​(Address addr,
                         int length)

      • writeMemory

        public void writeMemory​(Address addr,
                        byte[] bytes)

      • writeMemoryValue

        public void writeMemoryValue​(Address addr,
                             int size,
                             long value)

      • readStackValue

        public java.math.BigInteger readStackValue​(int relativeOffset,
                                           int size,
                                           boolean signed)
                                    throws java.lang.Exception
        Read a stack value from the memory state.
        Parameters:
        relativeOffset - offset relative to current stack pointer
        size - data size in bytes
        signed - true if value read is signed, false if unsigned
        Returns:
        value
        Throws:
        java.lang.Exception - error occurs reading stack pointer

      • writeStackValue

        public void writeStackValue​(int relativeOffset,
                            int size,
                            long value)
                     throws java.lang.Exception
        Write a value onto the stack
        Parameters:
        relativeOffset - offset relative to current stack pointer
        size - data size in bytes
        value -
        Throws:
        java.lang.Exception - error occurs reading stack pointer

      • writeStackValue

        public void writeStackValue​(int relativeOffset,
                            int size,
                            java.math.BigInteger value)
                     throws java.lang.Exception
        Write a value onto the stack
        Parameters:
        relativeOffset - offset relative to current stack pointer
        size - data size in bytes
        value -
        Throws:
        java.lang.Exception - error occurs reading stack pointer

      • setBreakpoint

        public void setBreakpoint​(Address addr)
        Establish breakpoint
        Parameters:
        addr - memory address for new breakpoint

      • clearBreakpoint

        public void clearBreakpoint​(Address addr)
        Clear breakpoint
        Parameters:
        addr - memory address for breakpoint to be cleared

      • setContextRegister

        public void setContextRegister​(RegisterValue ctxRegValue)
        Set current context register value. Keep in mind that any non-flowing context values will be stripped.
        Parameters:
        ctxRegValue -

      • setContextRegister

        public void setContextRegister​(Register ctxReg,
                               java.math.BigInteger value)
        Set current context register value. Keep in mind that any non-flowing context values will be stripped.
        Parameters:
        ctxReg - context register
        value - context value

      • getContextRegister

        public RegisterValue getContextRegister()
        Get the current context register value
        Returns:
        context register value or null if not set or unknown

      • registerCallOtherCallback

        public void registerCallOtherCallback​(java.lang.String pcodeOpName,
                                      BreakCallBack callback)
        Register callback for language defined pcodeop (call other). WARNING! Using this method may circumvent the default CALLOTHER emulation support when supplied by the Processor module.
        Parameters:
        pcodeOpName - the name of the pcode op
        callback - the callback to register

      • registerDefaultCallOtherCallback

        public void registerDefaultCallOtherCallback​(BreakCallBack callback)
        Register default callback for language defined pcodeops (call other). WARNING! Using this method may circumvent the default CALLOTHER emulation support when supplied by the Processor module.
        Parameters:
        callback - the default callback to register

      • unregisterCallOtherCallback

        public void unregisterCallOtherCallback​(java.lang.String pcodeOpName)
        Unregister callback for language defined pcodeop (call other).
        Parameters:
        pcodeOpName - the name of the pcode op

      • unregisterDefaultCallOtherCallback

        public void unregisterDefaultCallOtherCallback()
        Unregister default callback for language defined pcodeops (call other). WARNING! Using this method may circumvent the default CALLOTHER emulation support when supplied by the Processor module.

      • getExecutionAddress

        public Address getExecutionAddress()
        Get current execution address
        Returns:
        current execution address

      • run

        public boolean run​(Address addr,
                   ProcessorContext context,
                   TaskMonitor monitor)
            throws CancelledException
        Start execution at the specified address using the initial context specified. Method will block until execution stops. This method will initialize context register based upon the program stored context if not already done. In addition, both general register value and the context register may be further modified via the context parameter if specified.
        Parameters:
        addr - initial program address
        context - optional context settings which override current program context
        monitor -
        Returns:
        true if execution completes without error (i.e., is at breakpoint)
        Throws:
        CancelledException - if execution cancelled via monitor

      • run

        public boolean run​(TaskMonitor monitor)
            throws CancelledException
        Continue execution from the current execution address. No adjustment will be made to the context beyond the normal context flow behavior defined by the language. Method will block until execution stops.
        Parameters:
        monitor -
        Returns:
        true if execution completes without error (i.e., is at breakpoint)
        Throws:
        CancelledException - if execution cancelled via monitor

      • getLastError

        public java.lang.String getLastError()
        Returns:
        last error message associated with execution failure

      • step

        public boolean step​(TaskMonitor monitor)
             throws CancelledException
        Step execution one instruction which may consist of multiple pcode operations. No adjustment will be made to the context beyond the normal context flow behavior defined by the language. Method will block until execution stops.
        Returns:
        true if execution completes without error
        Throws:
        CancelledException - if execution cancelled via monitor

      • enableMemoryWriteTracking

        public void enableMemoryWriteTracking​(boolean enable)
        Enable/Disable tracking of memory writes in the form of an address set.
        Parameters:
        enable -

      • getTrackedMemoryWriteSet

        public AddressSetView getTrackedMemoryWriteSet()
        Returns:
        address set of memory locations written by the emulator if memory write tracking is enabled, otherwise null is returned. The address set returned will continue to be updated unless memory write tracking becomes disabled.

      • unknownAddress

        public boolean unknownAddress​(Address address,
                              boolean write)
        Description copied from interface: MemoryFaultHandler
        Unable to translate the specified address
        Specified by:
        unknownAddress in interface MemoryFaultHandler
        Parameters:
        address - address which failed to be translated
        write - true if memory operation was a write vs. read
        Returns:
        true if fault was handled

      • uninitializedRead

        public boolean uninitializedRead​(Address address,
                                 int size,
                                 byte[] buf,
                                 int bufOffset)
        Description copied from interface: MemoryFaultHandler
        An attempt has been made to read uninitialized memory at the specified address.
        Specified by:
        uninitializedRead in interface MemoryFaultHandler
        Parameters:
        address - uninitialized storage address (memory, register or unique)
        size - number of uninitialized bytes
        buf - storage buffer
        bufOffset - read offset within buffer
        Returns:
        true if data should be treated as initialized

      • getEmulator

        public Emulator getEmulator()