Annotation Interface AnnotatedPcodeUseropLibrary.PcodeUserop

Enclosing class:
AnnotatedPcodeUseropLibrary<T>
@Retention(RUNTIME) @Target(METHOD) public static @interface AnnotatedPcodeUseropLibrary.PcodeUserop
An annotation to export a Java method as a userop in the library.

This can annotate a Java callback userop or a Sleigh-defined userop.

For a Java callback, each parameter ordinarily receives an input to the userop. Each parameter may be annotated with at most one of AnnotatedPcodeUseropLibrary.OpExecutor, AnnotatedPcodeUseropLibrary.OpState, AnnotatedPcodeUseropLibrary.OpLibrary, or AnnotatedPcodeUseropLibrary.OpOutput to change what it receives. If variadic() is false, non-annotated parameters receive the inputs to the userop in matching order. Conventionally, annotated parameters should be placed first or last. Parameters accepting inputs must have type Varnode, a type assignable from T, or a primitive type, and may be annotated with AnnotatedPcodeUseropLibrary.OpInput. A parameter of type Varnode will receive the input Varnode. A parameter that is of primitive type or assignable from T will receive the input value. If it so happens that T is assignable from Varnode, the parameter will receive the Varnode, not the value. NOTE: Receiving a value instead of a variable may lose its size. Depending on the type of the value, that size may or may not be recoverable. Values passed as primitives imply an attempt to concretize the value.

If variadic() is true, then a single non-annotated parameter receives all inputs in order. This parameter must have a type Varnode[] to receive variables or have type assignable from T[] to receive values.

Note that there is no annotation to receive the "thread," because threads are not a concept known to the p-code executor or userop libraries, in general. In most cases, receiving the executor and/or state (which are usually bound to a specific thread) is sufficient. The preferred means of exposing thread-specific userops is to construct a library bound to that specific thread. That strategy should preserve compile-time type safety. Alternatively, you can receive the executor or state, cast it to your specific type, and use an accessor to get its thread.

For a Sleigh-defined userop, the method must return SleighPcodeUseropDefinition and accept a single parameter of type SleighPcodeUseropDefinition.BuilderStage1. The method is invoked once at library construction. The method can use the builder to create the userop definition. The various attributes and attestations accepted by this annotation are currently ignored for Sleigh-defined userops. The various Op-prefixed annotations, e.g., AnnotatedPcodeUseropLibrary.OpExecutor have no effect on the single parameter and should not be applied.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    boolean
    canInline
    Set to true to suggest inlining.
    boolean
    canInterrupt
    Set to false to attest that the userop will not interrupt execution.
    boolean
    functional
    Set to true to attest that the userop is a pure function.
    boolean
    hasSideEffects
    Set to false to attest the userop has no side effects.
    boolean
    modifiesContext
    Set to true to indicate the userop can modify the decode context.
    boolean
    signed
    Set true to indicate sign extension of the output.
    boolean
    variadic
    Set to true to receive all inputs in an array.

  • Element Details

    • variadic

      boolean variadic
      Set to true to receive all inputs in an array.
      Default:
      false

    • functional

      boolean functional
      Set to true to attest that the userop is a pure function.

      An incorrect attestation can lead to erroneous execution results.

      See Also:
      Default:
      false

    • canInterrupt

      boolean canInterrupt
      Set to false to attest that the userop will not interrupt execution.

      This defaults to false, even though it seems unsafe to attest to no interrupts. Generally, this is about expected interruptions, not exceptions that occur because of buggy userop implementations. In general, userops that interrupt on purpose are uncommon. Userop authors may, at their discretion, adjust this attribute to ease debugging. If this userop can throw an exception and the emulator is meant to resume execution after handling it, this must be set to true.

      See Also:
      Default:
      false

    • hasSideEffects

      boolean hasSideEffects
      Set to false to attest the userop has no side effects.

      An incorrect attestation can lead to erroneous execution results.

      See Also:
      Default:
      true

    • modifiesContext

      boolean modifiesContext
      Set to true to indicate the userop can modify the decode context.

      Failure to indicate context modifications can lead to erroneous decodes and thus incorrect execution results.

      See Also:
      Default:
      false

    • canInline

      boolean canInline
      Set to true to suggest inlining.
      See Also:
      Default:
      false

    • signed

      boolean signed
      Set true to indicate sign extension of the output.
      See Also:
      Default:
      true