Interface PcodeUseropLibrary.PcodeUseropDefinition<T>

Type Parameters:

T - the type of parameter accepted (and possibly returned) by the userop.

All Known Subinterfaces:

SleighPcodeUseropDefinition

All Known Implementing Classes:

AbstractSleighPcodeUseropDefinition, AnnotatedPcodeUseropLibrary.AnnotatedPcodeUseropDefinition, AnnotatedPcodeUseropLibrary.FixedArgsAnnotatedPcodeUseropDefinition, AnnotatedPcodeUseropLibrary.VariadicAnnotatedPcodeUseropDefinition, DecoderUseropLibrary.WrappedUseropDefinition, FixedSleighPcodeUseropDefinition, JitDataFlowUseropLibrary.WrappedUseropDefinition, ModifiedPcodeThread.ModifierUseropLibrary.ModifierUseropDefinition, OverloadedSleighPcodeUseropDefinition

Enclosing interface:

PcodeUseropLibrary<T>

public static interface PcodeUseropLibrary.PcodeUseropDefinition<T>

The definition of a p-code userop.

Method Summary

Change	Modifier and Type	Method	Description
	boolean	canInlinePcode()	Indicates whether or not this userop definition produces p-code suitable for inlining in place of its invocation.
	boolean	canInterrupt()	Indicates whether this userop can interrupt execution.
	default void	execute(PcodeExecutor<T> executor, PcodeUseropLibrary<T> library, PcodeOp op)	Invoke/execute the raw userop.
	void	execute(PcodeExecutor<T> executor, PcodeUseropLibrary<T> library, PcodeOp op, Varnode outVar, List<Varnode> inVars)	Invoke/execute the userop.
	PcodeUseropLibrary<?>	getDefiningLibrary()	Get the library that defines (or "owns") this userop
	int	getInputCount()	Get the number of input operands accepted by the userop.
	Method	getJavaMethod()	If this userop is defined as a java callback, get the method
	String	getName()	Get the name of the userop.
	Class<?>	getOutputType()	If this userop is defined as a java callback, get the type of the output
	boolean	hasSideEffects()	Indicates whether this userop may have side effects.
	boolean	isFunctional()	Indicates whether this userop is a "pure function."
	boolean	isInSigned(int index)	Indicates whether a given input 0-up should be sign or zero extended to match a Java primitive parameter size.
	boolean	isOutSigned()	Indicates whether the output should be sign or zero extended to match the output varnode size.
	boolean	modifiesContext()	Indicates that this userop may modify the decode context.

Method Details

getName

String getName()

Get the name of the userop.

This is the symbol assigned to the userop when compiling new Sleigh code. It cannot conflict with existing userops (except those declared, but not defined, by the executor's language) or other symbols of the executor's language. If this userop is to be used generically across many languages, choose an unlikely name. Conventionally, these start with two underscores __.

Returns:

the name of the userop

getInputCount

int getInputCount()

Get the number of input operands accepted by the userop.

Returns:

the count or -1 if the userop is variadic

execute

void execute(PcodeExecutor<T> executor,
 PcodeUseropLibrary<T> library,
 PcodeOp op,
 Varnode outVar,
 List<Varnode> inVars)

Invoke/execute the userop.

Parameters:

executor - the executor invoking this userop.

library - the complete library for this execution. Note the library may have been composed from more than the one defining this userop.

op - the PcodeOp.CALLOTHER op

outVar - if invoked as an rval, the destination varnode for the userop's output. Otherwise, null.

inVars - the input varnodes as ordered in the source.

See Also:

• AnnotatedPcodeUseropLibrary.AnnotatedPcodeUseropDefinition

execute

default void execute(PcodeExecutor<T> executor,
 PcodeUseropLibrary<T> library,
 PcodeOp op)

Invoke/execute the raw userop.

NOTE: The first input to the raw p-code op is the id of this userop. The userop inputs are thus at indices 1..N.

Parameters:

executor - the executor invoking this userop.

library - the complete library for this execution. Note the library may have been composed from more than the one defining this userop.

op - the PcodeOp.CALLOTHER op

isFunctional

boolean isFunctional()

Indicates whether this userop is a "pure function."

This means all inputs are given in the arguments to the userop; and the output, if applicable, is given via the return. Technically, this is only with respect to the emulated machine state. If the library carries its own state, and the userop is stateful with respect to the library, it is still okay to set this to true. When this is set to false, the underlying execution engine must ensure the machine state is consistent, because the userop may access any part of it directly. Functional userops ought to take primitive parameters and return primitives, and should receive neither the executor nor its state object.

WARNING: The term "inputs" include disassembly context. Unfortunately, there is currently no way to access that context via p-code ops generated by Sleigh, so the only way to obtain it is to ask the emulator thread for it out of band. Userops that require this are not "pure functions."

Returns:

true if a pure function.

See Also:

• AnnotatedPcodeUseropLibrary.PcodeUserop.functional()

canInterrupt NEW

boolean canInterrupt()

Indicates whether this userop can interrupt execution.

Optimized execution engines seeks to remove unnecessary variable assignments, computations, etc. If the userop is functional, then the engine can confidently assume only its operands need to be visible at the time of its invocation. If a userop can interrupt execution, then the engine must assure that, once the client has handled the exception, the machine state reflects the state at the time of the interruption. (This is especially critical for user breakpoints.)

NOTE: We're not settled on the case of "unexpected" interrupts, e.g., a null pointer exception in a user's userop library. In a sense, this is undefined behavior, so who's to say the machine had better have a consistent state? On the other hand, for userops that intend to throw exceptions as a means of interrupting execution for client inspection and possible resumption, this attribute must be set. Here's the rule for now:

If the intent is to permit the client to resume execution after the interrupt, the machine state must be consistent, and so this attribute must be true.

Otherwise, the value is set at the userop developer's discretion, but false should be preferred to facilitate better performance.

Returns:

true if the userop can be expected to interrupt execution by throwing an exception

See Also:

• AnnotatedPcodeUseropLibrary.PcodeUserop.canInterrupt()

hasSideEffects

boolean hasSideEffects()

Indicates whether this userop may have side effects.

This means that the function may have an output or an effect other than returning a value. Even if isFunctional() is true, it is possible for a userop to have side effects, e.g., updating a field in a library or printing to the screen. This does not permit a functional userop to modify the emulated machine state, but only "out-of-band" state.

Returns:

true if it has side effects.

See Also:

• AnnotatedPcodeUseropLibrary.PcodeUserop.hasSideEffects()

modifiesContext

boolean modifiesContext()

Indicates that this userop may modify the decode context.

This means that the userop may set a field in contextreg, which could thus affect how subsequent instructions are decoded. Executors which decode ahead will have to consider this effect.

Returns:

true if this can modify the context.

See Also:

• AnnotatedPcodeUseropLibrary.PcodeUserop.modifiesContext()

canInlinePcode

boolean canInlinePcode()

Indicates whether or not this userop definition produces p-code suitable for inlining in place of its invocation.

Generally, if all the userop definition does is feed additional p-code to the executor with the same userop library, then it is suitable for inlining. It is possible for the p-code to depend on other factors, but care must be taken, since the decision could be fixed by the underlying execution system at any time. E.g., if the p-code is translated to JVM byte code, then the userop may be inlined at translation time rather than execution time. Recommended factors include configuration, placement within surrounding instructions, static analysis, etc., but the p-code should probably not depend on the machine's dynamic run-time state.

Returns:

true if inlining is possible, false otherwise.

See Also:

• AnnotatedPcodeUseropLibrary.PcodeUserop.canInline()

isOutSigned NEW

boolean isOutSigned()

Indicates whether the output should be sign or zero extended to match the output varnode size.

This only applies when the userop is implemented as a Java function returning a primitive type. Otherwise, the userop should examine the output varnode and behave accordingly, or just inline use of that output varnode. When returning, e.g., an int, it could happen that the output varnode size 8. Because it's larger, we need to know whether or not the output is meant to be signed. Contrary to Java conventions, but inline with Sleigh conventions, we default to false.

Returns:

true for signed extension

isInSigned NEW

boolean isInSigned(int index)

Indicates whether a given input 0-up should be sign or zero extended to match a Java primitive parameter size.

This only applies when the userop is implemented as a Java function and this input is taken as a primitive type. Otherwise, the userop should examine the input varnode and behave accordingly, or just inline use of that input varnode. When accepting, e.g., a long, it could happen the input varnode is size 2. Because it's smaller, we need to know whether or not that input is meant to be signed. Contrary to Java conventions, but inline with Sleigh conventions, we default to false.

WARNING: Constant varnodes can behave weirdly when interpreted as signed. A userop declaring a signed input must be prepared to deal with this case. Consider the constant 0x80. Sleigh will encode this as the varnode (const, 0x80, 1), i.e., the constant with value 0x80 having size 1. If you mark an int input as signed, and it receives this constant, Java will see it as -128.

Parameters:

index - the position of the input argument, 0 is leftmost.

Returns:

true for signed extension

getOutputType

Class<?> getOutputType()

If this userop is defined as a java callback, get the type of the output

If the method has a @AnnotatedPcodeUseropLibrary.OpOutput annotation, this is the type of the output parameter. Otherwise, this is the method's return type.

Returns:

the output type

getJavaMethod

Method getJavaMethod()

If this userop is defined as a java callback, get the method

Returns:

the method, or null

getDefiningLibrary

PcodeUseropLibrary<?> getDefiningLibrary()

Get the library that defines (or "owns") this userop

A userop can become part of other composed libraries, so the library from which this userop was retrieved may not be the same as the one that defined it. This returns the one that defined it.

As a special consideration, if this userop is a wrapper around another, and this wrapper returns the java method of the delegate, this must return the defining library of the delegate. If this is not defined by a java callback, this method (the defining library) may be null.

Returns:

the defining library