Package ghidra.pcode.exec

# Class AnnotatedPcodeUseropLibrary.AnnotatedPcodeUseropDefinition<T>

java.lang.Object
ghidra.pcode.exec.AnnotatedPcodeUseropLibrary.AnnotatedPcodeUseropDefinition<T>

Type Parameters:
  `T` - the type of data processed by the userop

All Implemented Interfaces:
  `PcodeUseropLibrary.PcodeUseropDefinition<T>`

Direct Known Subclasses:
  `AnnotatedPcodeUseropLibrary.FixedArgsAnnotatedPcodeUseropDefinition`, `AnnotatedPcodeUseropLibrary.VariadicAnnotatedPcodeUseropDefinition`

Enclosing class:
  `AnnotatedPcodeUseropLibrary<T>`

protected abstract static class AnnotatedPcodeUseropLibrary.AnnotatedPcodeUseropDefinition<T> extends Object implements PcodeUseropLibrary.PcodeUseropDefinition<T>
A wrapped, annotated Java method, exported as a userop definition

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Method`
  `method`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AnnotatedPcodeUseropDefinition(AnnotatedPcodeUseropLibrary<T> library, Type opType, MethodHandles.Lookup lookup, Method method, AnnotatedPcodeUseropLibrary.PcodeUserop annot)`

- ## Method Summary

  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.
  `protected static <T> AnnotatedPcodeUseropLibrary.AnnotatedPcodeUseropDefinition<T>`
  `create(AnnotatedPcodeUseropLibrary.PcodeUserop annot, AnnotatedPcodeUseropLibrary<T> library, Type opType, MethodHandles.Lookup lookup, Method method)`
  `void`
  `execute(PcodeExecutor<T> executor, PcodeUseropLibrary<T> library, Varnode outVar, List<Varnode> inVars)`
  Invoke/execute the userop.
  `protected static <T> T`
  `fromPrimitive(Object value, int size, PcodeArithmetic<T> arithmetic)`
  `PcodeUseropLibrary<T>`
  `getDefiningLibrary()`
  Get the library that defines (or "owns") this 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.
  `protected void`
  `initFinished()`
  `protected void`
  `initStarting()`
  `boolean`
  `isFunctional()`
  Indicates whether this userop is a "pure function."
  `protected static boolean`
  `isPrimitive(Type type)`
  `boolean`
  `modifiesContext()`
  Indicates that this userop may modify the decode context.
  `protected abstract void`
  `placeInputs(PcodeExecutor<T> executor, List<Object> args, List<Varnode> inVars)`
  `protected abstract void`
  `processNonAnnotatedParameter(Type declClsOpType, Type opType, int i, Parameter p)`
  `protected void`
  `validateInputs(List<Varnode> inVars)`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ghidra.pcode.exec.PcodeUseropLibrary.PcodeUseropDefinition

  `execute, getInputCount`

- ## Field Details

  - ### method

    protected final Method method

- ## Constructor Details

  - ### AnnotatedPcodeUseropDefinition

    public AnnotatedPcodeUseropDefinition(AnnotatedPcodeUseropLibrary<T> library, Type opType, MethodHandles.Lookup lookup, Method method, AnnotatedPcodeUseropLibrary.PcodeUserop annot)

- ## Method Details

  - ### isPrimitive

    protected static boolean isPrimitive(Type type)

  - ### create

    protected static <T> AnnotatedPcodeUseropLibrary.AnnotatedPcodeUseropDefinition<T> create(AnnotatedPcodeUseropLibrary.PcodeUserop annot, AnnotatedPcodeUseropLibrary<T> library, Type opType, MethodHandles.Lookup lookup, Method method)

  - ### fromPrimitive

    protected static <T> T fromPrimitive(Object value, int size, PcodeArithmetic<T> arithmetic)

  - ### getName

    public String getName()
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    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 `__`.

    Specified by:
      `getName` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    Returns:
      the name of the userop

  - ### execute

    public void execute(PcodeExecutor<T> executor, PcodeUseropLibrary<T> library, Varnode outVar, List<Varnode> inVars)
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    Invoke/execute the userop.
    Specified by:
      `execute` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    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.
      `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`

  - ### isFunctional

    public boolean isFunctional()
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    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."

    Specified by:
      `isFunctional` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    Returns:
      true if a pure function.
    See Also:
      - `AnnotatedPcodeUseropLibrary.PcodeUserop.functional()`

  - ### hasSideEffects

    public boolean hasSideEffects()
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    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 `PcodeUseropLibrary.PcodeUseropDefinition.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.

    Specified by:
      `hasSideEffects` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    Returns:
      true if it has side effects.
    See Also:
      - `AnnotatedPcodeUseropLibrary.PcodeUserop.hasSideEffects()`

  - ### modifiesContext

    public boolean modifiesContext()
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    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.

    Specified by:
      `modifiesContext` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    Returns:
      true if this can modify the context.
    See Also:
      - `AnnotatedPcodeUseropLibrary.PcodeUserop.modifiesContext()`

  - ### canInlinePcode

    public boolean canInlinePcode()
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    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.

    Specified by:
      `canInlinePcode` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    Returns:
      true if inlining is possible, false otherwise.
    See Also:
      - `AnnotatedPcodeUseropLibrary.PcodeUserop.canInline()`

  - ### getOutputType

    public Class<?> getOutputType()
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    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.

    Specified by:
      `getOutputType` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    Returns:
      the output type

  - ### getJavaMethod

    public Method getJavaMethod()
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    If this userop is defined as a java callback, get the method
    Specified by:
      `getJavaMethod` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    Returns:
      the method, or null

  - ### getDefiningLibrary

    public PcodeUseropLibrary<T> getDefiningLibrary()
    Description copied from interface: `PcodeUseropLibrary.PcodeUseropDefinition`
    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.

    Specified by:
      `getDefiningLibrary` in interface `PcodeUseropLibrary.PcodeUseropDefinition<T>`
    Returns:
      the defining library

  - ### initStarting

    protected void initStarting()

  - ### processNonAnnotatedParameter

    protected abstract void processNonAnnotatedParameter(Type declClsOpType, Type opType, int i, Parameter p)

  - ### initFinished

    protected void initFinished()

  - ### validateInputs

    protected void validateInputs(List<Varnode> inVars) throws PcodeExecutionException
    Throws:
      `PcodeExecutionException`

  - ### placeInputs

    protected abstract void placeInputs(PcodeExecutor<T> executor, List<Object> args, List<Varnode> inVars)