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 Summary

  Modifier and Type
  Method
  Description
  `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
  `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
  `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
  `PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],U>>`
  `createLocalUseropStub(AuxPcodeEmulator<U> emulator)`
  Create a stub userop library for the emulator's threads
  `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
  `PcodeUseropLibrary<org.apache.commons.lang3.tuple.Pair<byte[],U>>`
  `createSharedUseropLibrary(AuxPcodeEmulator<U> emulator)`
  Create the userop library for the emulator (used by all threads)
  `default PcodeThread<org.apache.commons.lang3.tuple.Pair<byte[],U>>`
  `createThread(AuxPcodeEmulator<U> emulator, String name)`
  Create a thread with the given name
  `PcodeArithmetic<U>`
  `getArithmetic(Language language)`
  Get the arithmetic for the emulator given a target langauge

- ## 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