Package ghidra.pcode.exec

Interface PcodeUseropLibraryFactory

All Superinterfaces:

ExtensionPoint

All Known Implementing Classes:

TrigPcodeUseropLibraryFactory

public interface PcodeUseropLibraryFactory NEW
extends ExtensionPoint

A discoverable factory for creating a pluggable userop library, automatically picked up by the default emulator.

The factory must have a public default constructor.

Nested Class Summary

Nested Classes

Change	Modifier and Type	Interface	Description
	static @interface	PcodeUseropLibraryFactory.UseropLibrary	A required annotation for identifying the library in pspec files

Field Summary

Fields

Change	Modifier and Type	Field	Description
	static final String	KEY_USEROP_LIBS	The property key for useropLib ids in pspec files

Method Summary

Change	Modifier and Type	Method	Description
	<T> PcodeUseropLibrary<T>	create(SleighLanguage language, PcodeArithmetic<T> arithmetic)	Create the userop library
	static <T> PcodeUseropLibrary<T>	createUseropLibraryForLanguage(SleighLanguage language, PcodeArithmetic<T> arithmetic)	Create the userop library for the given language
	static <T> PcodeUseropLibrary<T>	createUseropLibraryFromId(String id, SleighLanguage language, PcodeArithmetic<T> arithmetic)	Create the userop library as identified for the given language and arithmetic
	default String	getId()	Get the id of this factory

Field Details

KEY_USEROP_LIBS

static final String KEY_USEROP_LIBS

The property key for useropLib ids in pspec files

See Also:

• Constant Field Values

Method Details

createUseropLibraryFromId

static <T> PcodeUseropLibrary<T> createUseropLibraryFromId(String id,
 SleighLanguage language,
 PcodeArithmetic<T> arithmetic)

Create the userop library as identified for the given language and arithmetic

While not strictly enforced by the framework, some care should be taken to ensure the library is prepared to handle the given language, since it may only expect those whose pspec files identify it. The library (or its factory) may throw an exception, or otherwise exhibit undefined behavior, if it cannot find the resources, e.g., a specific named register, that it expects.

The given arithmetic must also be compatible with both the library and the language. In particular, the language and arithmetic must agree in endianness. (The default emulator should already ensure this is the case.) The library must also understand the type of the arithmetic, i.e., the type of values in the emulator. If either is not the case the emulator may exhibit undefined behavior. (The default emulator does not guarantee type compatibility.) Ideally, such incompatibilities are checked and reported by the userop library as early as possible, e.g., in the library's constructor.

If the given id cannot be found, an empty library (PcodeUseropLibrary.nil()) is returned and a warning logged. If multiple factories have the given id (this is considered a bug), then a warning is logged and a factory is selected non-deterministically.

Type Parameters:

T - the type of values in the emulator's state

Parameters:

id - the id of the userop library

language - the language

arithmetic - the arithmetic

Returns:

the userop library

createUseropLibraryForLanguage

static <T> PcodeUseropLibrary<T> createUseropLibraryForLanguage(SleighLanguage language,
 PcodeArithmetic<T> arithmetic)

Create the userop library for the given language

This composes all of the libraries named in the language's pspec file in the "useropLibs" property. That property is a comma-separated list of the ids to compose.

See the caveats in createUseropLibraryFromId(String, SleighLanguage, PcodeArithmetic) regarding agreement between language and arithmetic.

Type Parameters:

T - the type of values in the emulator's state

Parameters:

language - the language

arithmetic - the arithmetic

Returns:

the userop library

Implementation Notes:

currently, duplicate userops (by name) are not permitted. This may change in future versions. Thus, we compose libraries in the order listed, in case of that change, as it would matter.

getId

default String getId()

Get the id of this factory

This gets the id from the PcodeUseropLibraryFactory.UseropLibrary annotation. You should not override this function without a good reason.

Returns:

the id

create

<T> PcodeUseropLibrary<T> create(SleighLanguage language,
 PcodeArithmetic<T> arithmetic)

Create the userop library

Type Parameters:

T - the type of values in the emulator

Parameters:

language - the language of the emulator

arithmetic - the arithmetic of the emulator

Returns:

the userop library