Interface PcodeUseropLibraryFactory

All Superinterfaces:

ExtensionPoint

All Known Implementing Classes:

DiagnosticsPcodeUseropLibraryFactory, TrigPcodeUseropLibraryFactory

public interface PcodeUseropLibraryFactory
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 int	DEFAULT_ORDER
	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 PcodeUseropLibraryFactory.UseropLibrary	getAnnotation()
	default String	getId()	Get the id of this factory
	default int	getOrder()	Get the override order of this library.
	default boolean	isIncludeAlways()	Check if this factory's library should always be included.

Field Details

DEFAULT_ORDER NEW

static final int DEFAULT_ORDER

See Also:

• Constant Field Values

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. The composition also includes libraries marked as PcodeUseropLibraryFactory.UseropLibrary.includeAlways(). Once all included libraries are identified, they are sorted by PcodeUseropLibraryFactory.UseropLibrary.order() and composed, overriding duplicate userops.

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

getAnnotation NEW

default PcodeUseropLibraryFactory.UseropLibrary getAnnotation()

getId

default String getId()

Get the id of this factory

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

Returns:

the id

isIncludeAlways NEW

default boolean isIncludeAlways()

Check if this factory's library should always be included.

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

Returns:

true if always included

getOrder NEW

default int getOrder()

Get the override order of this library.

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

Returns:

the order

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