Package ghidra.pcode.emu.auxiliary

Interface AuxEmulatorPartsFactory<U>

Type Parameters:
U - the type of auxiliary values
public interface AuxEmulatorPartsFactory<U>
An auxiliary emulator parts factory for stand-alone emulation

This can manufacture all the parts needed for a stand-alone emulator with concrete and some implementation-defined auxiliary state. More capable emulators may also use many of these parts. Usually, the additional capabilities deal with how state is loaded and stored or otherwise made available to the user. The pattern of use for a stand-alone emulator is usually in a script: Create an emulator, initialize its state, write instructions to its memory, create and initialize a thread, point its counter at the instructions, instrument, step/run, inspect, and finally terminate.

This "parts factory" pattern aims to flatten the extension points of the AbstractPcodeMachine and its components into a single class. Its use is not required, but may make things easier. It also encapsulates some "special knowledge," that might not otherwise be obvious to a developer, e.g., it creates the concrete state pieces, so the developer need not guess (or keep up to date) the concrete state piece classes to instantiate.

The factory itself should be a singleton object. See the Taint Analyzer for a complete example solution using this interface.

  • Method Details

    • getArithmetic

      PcodeArithmetic<U> getArithmetic(Language language)
      Get the arithmetic for the emulator given a target langauge
      Parameters:
      language - the language
      Returns:
      the arithmetic

    • createSharedUseropLibrary

      PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],U>> createSharedUseropLibrary(AuxPcodeEmulator<U> emulator)
      Create the userop library for the emulator (used by all threads)
      Parameters:
      emulator - the emulator
      Returns:
      the userop library

    • createLocalUseropStub

      PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],U>> createLocalUseropStub(AuxPcodeEmulator<U> emulator)
      Create a stub userop library for the emulator's threads
      Parameters:
      emulator - the emulator
      Returns:
      the library of stubs

    • createLocalUseropLibrary

      PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],U>> createLocalUseropLibrary(AuxPcodeEmulator<U> emulator, PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],U>> thread)
      Create a userop library for a given thread
      Parameters:
      emulator - the emulator
      thread - the thread
      Returns:
      the userop library

    • createExecutor

      default DefaultPcodeThread.PcodeThreadExecutor<org.apache.commons.lang3.tuple.Pair<byte[],U>> createExecutor(AuxPcodeEmulator<U> emulator, DefaultPcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],U>> thread)
      Create an executor for the given thread

      This allows the implementor to override or intercept the logic for individual p-code operations that would not otherwise be possible in the arithmetic, e.g., to print diagnostics on a conditional branch.

      Parameters:
      emulator - the emulator
      thread - the thread
      Returns:
      the executor

    • createThread

      default PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],U>> createThread(AuxPcodeEmulator<U> emulator, String name)
      Create a thread with the given name
      Parameters:
      emulator - the emulator
      name - the thread's name
      Returns:
      the thread

    • createSharedState

      PcodeExecutorState<org.apache.commons.lang3.tuple.Pair<byte[],U>> createSharedState(AuxPcodeEmulator<U> emulator, BytesPcodeExecutorStatePiece concrete)
      Create the shared (memory) state of a new stand-alone emulator

      This is usually composed of pieces using PairedPcodeExecutorStatePiece, but it does not have to be. It must incorporate the concrete piece provided. It should be self contained and relatively fast.

      Parameters:
      emulator - the emulator
      concrete - the concrete piece
      Returns:
      the composed state

    • createLocalState

      PcodeExecutorState<org.apache.commons.lang3.tuple.Pair<byte[],U>> createLocalState(AuxPcodeEmulator<U> emulator, PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],U>> thread, BytesPcodeExecutorStatePiece concrete)
      Create the local (register) state of a new stand-alone emulator

      This is usually composed of pieces using PairedPcodeExecutorStatePiece, but it does not have to be. It must incorporate the concrete piece provided. It should be self contained and relatively fast.

      Parameters:
      emulator - the emulator
      thread - the thread
      concrete - the concrete piece
      Returns:
      the composed state