Package ghidra.pcode.emu.auxiliary

# Interface AuxEmulatorPartsFactory<U>

Type Parameters:
  `U` - the type of auxiliary values

All Known Implementing Classes:
  `TaintPartsFactory`

public interface AuxEmulatorPartsFactory<U>
An auxiliary emulator parts factory

This can manufacture all the parts needed for an 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.

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, PcodeStateCallbacks cb)`
  Create the local (register) state of a new 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, PcodeStateCallbacks cb)`
  Create the shared (memory) state of a new 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 language

- ## Method Details

  - ### getArithmetic

    PcodeArithmetic<U> getArithmetic(Language language)
    Get the arithmetic for the emulator given a target language
    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, PcodeStateCallbacks cb)
    Create the shared (memory) state of a new 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
      `cb` - callbacks to receive emulation events
    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, PcodeStateCallbacks cb)
    Create the local (register) state of a new 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
      `cb` - callbacks to receive emulation events
    Returns:
      the composed state