Package ghidra.app.plugin.assembler.sleigh.sem

# Interface AssemblyResolvedPatterns

All Superinterfaces:
  `AssemblyResolution`, `Comparable<AssemblyResolution>`

All Known Implementing Classes:
  `DefaultAssemblyResolvedPatterns`

public interface AssemblyResolvedPatterns extends AssemblyResolution

- ## Method Summary

  Modifier and Type
  Method
  Description
  `AssemblyResolution`
  `backfill(RecursiveDescentSolver solver, Map<String,Long> vals)`
  Apply as many backfill records as possible
  `boolean`
  `bitsEqual(AssemblyResolvedPatterns that)`
  Check if this and another resolution have equal encodings
  `AssemblyResolution`
  `checkNotForbidden()`
  Check if the current encoding is forbidden by one of the attached patterns
  `AssemblyResolvedPatterns`
  `combine(AssemblyResolvedBackfill bf)`
  Combine the given backfill record into this resolution
  `AssemblyResolvedPatterns`
  `combine(AssemblyResolvedPatterns pat)`
  Combine the encodings and backfills of the given resolution into this one
  `AssemblyResolvedPatterns`
  `combineLessBackfill(AssemblyResolvedPatterns that, AssemblyResolvedBackfill bf)`
  Combine a backfill result
  `String`
  `dumpConstructorTree()`
  Used for testing and diagnostics: list the constructor line numbers used to resolve this encoding
  `boolean`
  `equivalentConstructState(ConstructState state)`
  Check if this assembled construct state is the same as the given dis-assembled construct state.
  `Collection<AssemblyResolvedBackfill>`
  `getBackfills()`
  Get the backfill records for this resolution, if any
  `AssemblyPatternBlock`
  `getContext()`
  Get the context block
  `int`
  `getDefinedInstructionLength()`
  Get the length of the instruction encoding, excluding trailing undefined bytes
  `Collection<AssemblyResolvedPatterns>`
  `getForbids()`
  Get the forbidden patterns for this resolution
  `AssemblyPatternBlock`
  `getInstruction()`
  Get the instruction block
  `int`
  `getInstructionLength()`
  Get the length of the instruction encoding
  `boolean`
  `hasBackfills()`
  Check if this resolution has pending backfills to apply
  `AssemblyResolvedPatterns`
  `maskOut(ContextOp cop)`
  Set all bits read by a given context operation to unknown
  `AssemblyResolvedPatterns`
  `nopLeftSibling()`
  Generate a new nop right this resolution to its right.
  `AssemblyResolvedPatterns`
  `parent(String description, int opCount)`
  Get this same resolution, pushing its right siblings down to its children
  `Iterable<byte[]>`
  `possibleInsVals(AssemblyPatternBlock forCtx)`
  Get an iterable over all the possible fillings of the instruction pattern given a context
  `MaskedLong`
  `readContext(int start, int len)`
  Decode a portion of the context block
  `MaskedLong`
  `readContextOp(ContextOp cop)`
  Decode the value from the context located where the given context operation would write
  `MaskedLong`
  `readInstruction(int byteStart, int size)`
  Decode a portion of the instruction block
  `AssemblyResolvedPatterns`
  `shift(int shamt)`
  Shift the resolution's instruction pattern to the right, if applicable
  `AssemblyResolvedPatterns`
  `solveContextChangesForForbids(AssemblyConstructorSemantic sem, Map<String,Long> vals)`
  Solve and apply context changes in reverse to forbidden patterns
  `AssemblyResolvedPatterns`
  `truncate(int shamt)`
  Truncate (unshift) the resolved instruction pattern from the left NOTE: This drops all backfill and forbidden pattern records, since this method is typically used to read token fields rather than passed around for resolution.
  `AssemblyResolvedPatterns`
  `withConstructor(Constructor cons)`
  Create a copy of this resolution with a replaced constructor
  `AssemblyResolvedPatterns`
  `withContext(AssemblyPatternBlock ctx)`
  Create a copy of this resolution with a new context
  `AssemblyResolvedPatterns`
  `withDescription(String description)`
  Create a copy of this resolution with a new description
  `AssemblyResolvedPatterns`
  `withForbids(Set<AssemblyResolvedPatterns> more)`
  Create a new resolution from this one with the given forbidden patterns recorded
  `AssemblyResolvedPatterns`
  `withRight(AssemblyResolution right)`
  Create a copy of this resolution with a sibling to the right
  `AssemblyResolvedPatterns`
  `writeContextOp(ContextOp cop, MaskedLong val)`
  Encode the given value into the context block as specified by an operation

  ### Methods inherited from interface ghidra.app.plugin.assembler.sleigh.sem.AssemblyResolution

  `collectAllRight, getChildren, getDescription, getRight, hasChildren, isBackfill, isError, lineToString, toString, toString`

  ### Methods inherited from interface java.lang.Comparable

  `compareTo`

- ## Method Details

  - ### getInstruction

    AssemblyPatternBlock getInstruction()
    Get the instruction block
    Returns:
      the instruction block

  - ### getContext

    AssemblyPatternBlock getContext()
    Get the context block
    Returns:
      the context block

  - ### withContext

    AssemblyResolvedPatterns withContext(AssemblyPatternBlock ctx)
    Create a copy of this resolution with a new context
    Parameters:
      `ctx` - the new context
    Returns:
      the copy

  - ### getInstructionLength

    int getInstructionLength()
    Get the length of the instruction encoding

    This is used to ensure each operand is encoded at the correct offset

    NOTE: this DOES include the offset
    NOTE: this DOES include pending backfills

    Returns:
      the length of the instruction block

  - ### getDefinedInstructionLength

    int getDefinedInstructionLength()
    Get the length of the instruction encoding, excluding trailing undefined bytes

    NOTE: this DOES include the offset
    NOTE: this DOES NOT include pending backfills

    Returns:
      the length of the defined bytes in the instruction block

  - ### getBackfills

    Collection<AssemblyResolvedBackfill> getBackfills()
    Get the backfill records for this resolution, if any
    Returns:
      the backfills

  - ### hasBackfills

    boolean hasBackfills()
    Check if this resolution has pending backfills to apply
    Returns:
      true if there are backfills

  - ### getForbids

    Collection<AssemblyResolvedPatterns> getForbids()
    Get the forbidden patterns for this resolution

    These represent patterns included in the current resolution that would actually get matched by a more specific constructor somewhere in the resolved tree, and thus are subtracted.

    Returns:
      the forbidden patterns

  - ### readInstruction

    MaskedLong readInstruction(int byteStart, int size)
    Decode a portion of the instruction block
    Parameters:
      `byteStart` - the first byte to decode
      `size` - the number of bytes to decode
    Returns:
      the read masked value
    See Also:
      - `AssemblyPatternBlock.readBytes(int, int)`

  - ### readContext

    MaskedLong readContext(int start, int len)
    Decode a portion of the context block
    Parameters:
      `start` - the first byte to decode
      `len` - the number of bytes to decode
    Returns:
      the read masked value
    See Also:
      - `AssemblyPatternBlock.readBytes(int, int)`

  - ### readContextOp

    MaskedLong readContextOp(ContextOp cop)
    Decode the value from the context located where the given context operation would write

    This is used to read the value from the left-hand-side "variable" of a context operation. It seems backward, because it is. When assembling, the right-hand-side expression of a context operation must be solved. This means the "variable" is known from the context(s) of the resolved children constructors. The value read is then used as the goal in solving the expression.

    Parameters:
      `cop` - the context operation whose "variable" to read.
    Returns:
      the masked result.

  - ### bitsEqual

    boolean bitsEqual(AssemblyResolvedPatterns that)
    Check if this and another resolution have equal encodings

    This is like `Object.equals(Object)`, but it ignores backfill records and forbidden patterns.

    Parameters:
      `that` - the other resolution
    Returns:
      true if both have equal encodings

  - ### equivalentConstructState

    boolean equivalentConstructState(ConstructState state)
    Check if this assembled construct state is the same as the given dis-assembled construct state.

  - ### shift

    AssemblyResolvedPatterns shift(int shamt)
    Description copied from interface: `AssemblyResolution`
    Shift the resolution's instruction pattern to the right, if applicable

    This also shifts any backfill and forbidden pattern records.

    Specified by:
      `shift` in interface `AssemblyResolution`
    Parameters:
      `shamt` - the number of bytes to shift.
    Returns:
      the result

  - ### withDescription

    AssemblyResolvedPatterns withDescription(String description)
    Create a copy of this resolution with a new description
    Parameters:
      `description` - the new description
    Returns:
      the copy

  - ### withRight

    AssemblyResolvedPatterns withRight(AssemblyResolution right)
    Create a copy of this resolution with a sibling to the right

    The right sibling is a mechanism for collecting children of a parent yet to be created. See `parent(String, int)`.

    Parameters:
      `right` - the right sibling
    Returns:
      the new resolution

  - ### withConstructor

    AssemblyResolvedPatterns withConstructor(Constructor cons)
    Create a copy of this resolution with a replaced constructor
    Parameters:
      `cons` - the new constructor
    Returns:
      the copy

  - ### combine

    AssemblyResolvedPatterns combine(AssemblyResolvedPatterns pat)
    Combine the encodings and backfills of the given resolution into this one

    This combines corresponding pattern blocks (assuming they agree), collects backfill records, and collects forbidden patterns.

    Parameters:
      `pat` - the other resolution
    Returns:
      the result if successful, or null

  - ### combine

    AssemblyResolvedPatterns combine(AssemblyResolvedBackfill bf)
    Combine the given backfill record into this resolution
    Parameters:
      `bf` - the backfill record
    Returns:
      the result

  - ### combineLessBackfill

    AssemblyResolvedPatterns combineLessBackfill(AssemblyResolvedPatterns that, AssemblyResolvedBackfill bf)
    Combine a backfill result

    When a backfill is successful, the result should be combined with the owning resolution. In addition, for bookkeeping's sake, the resolved record should be removed from the list of backfills.

    Parameters:
      `that` - the result from backfilling
      `bf` - the resolved backfilled record
    Returns:
      the result if successful, or null

  - ### parent

    AssemblyResolvedPatterns parent(String description, int opCount)
    Description copied from interface: `AssemblyResolution`
    Get this same resolution, pushing its right siblings down to its children
    Specified by:
      `parent` in interface `AssemblyResolution`

  - ### backfill

    AssemblyResolution backfill(RecursiveDescentSolver solver, Map<String,Long> vals)
    Apply as many backfill records as possible

    Each backfill record is resolved in turn, if the record cannot be resolved, it remains listed. If the record can be resolved, but it conflicts, an error record is returned. Each time a record is resolved and combined successfully, all remaining records are tried again. The result is the combined resolved backfills, with only the unresolved backfill records listed.

    Parameters:
      `solver` - the solver, usually the same as the original attempt to solve.
      `vals` - the values.
    Returns:
      the result, or an error.

  - ### checkNotForbidden

    AssemblyResolution checkNotForbidden()
    Check if the current encoding is forbidden by one of the attached patterns

    The pattern becomes forbidden if this encoding's known bits are an overset of any forbidden pattern's known bits.

    Returns:
      false if the pattern is forbidden (and thus in error), true if permitted

  - ### nopLeftSibling

    AssemblyResolvedPatterns nopLeftSibling()
    Generate a new nop right this resolution to its right.

    Alternatively phrased: append a nop to the left of this list of siblings, returning the new head.

    Returns:
      the nop resolution

  - ### solveContextChangesForForbids

    AssemblyResolvedPatterns solveContextChangesForForbids(AssemblyConstructorSemantic sem, Map<String,Long> vals)
    Solve and apply context changes in reverse to forbidden patterns

    To avoid circumstances where a context change during disassembly would invoke a more specific sub-constructor than was used to assembly the instruction, we must solve the forbidden patterns in tandem with the overall resolution. If the context of any forbidden pattern cannot be solved, we simply drop the forbidden pattern -- the lack of a solution implies there is no way the context change could produce the forbidden pattern.

    Parameters:
      `sem` - the constructor whose context changes to solve
      `vals` - any defined symbols
    Returns:
      the result
    See Also:
      - `AssemblyConstructorSemantic.solveContextChanges(AssemblyResolvedPatterns, Map)`

  - ### possibleInsVals

    Iterable<byte[]> possibleInsVals(AssemblyPatternBlock forCtx)
    Get an iterable over all the possible fillings of the instruction pattern given a context

    This is meant to be used idiomatically, as in an enhanced for loop:

         for (byte[] ins : rcon.possibleInsVals(ctx)) {
                System.out.println(format(ins));
         }

    This is similar to calling `getInstruction()`.`AssemblyPatternBlock.possibleVals()`, but with forbidden patterns removed. A context is required so that only those forbidden patterns matching the given context are actually removed. This method should always be preferred to the sequence mentioned above, since `AssemblyPatternBlock.possibleVals()` on its own may yield bytes that do not produce the desired instruction.

    NOTE: The implementation is based on `AssemblyPatternBlock.possibleVals()`, so be aware that a single array is reused for each iterate. You should not retain a pointer to the array, but rather make a copy.

    Parameters:
      `forCtx` - the context at the assembly address
    Returns:
      the iterable

  - ### dumpConstructorTree

    String dumpConstructorTree()
    Used for testing and diagnostics: list the constructor line numbers used to resolve this encoding

    This includes braces to describe the tree structure

    Returns:
      the constructor tree
    See Also:
      - `ConstructState.dumpConstructorTree()`

  - ### truncate

    AssemblyResolvedPatterns truncate(int shamt)
    Truncate (unshift) the resolved instruction pattern from the left NOTE: This drops all backfill and forbidden pattern records, since this method is typically used to read token fields rather than passed around for resolution.
    Parameters:
      `shamt` - the number of bytes to remove from the left
    Returns:
      the result

  - ### withForbids

    AssemblyResolvedPatterns withForbids(Set<AssemblyResolvedPatterns> more)
    Create a new resolution from this one with the given forbidden patterns recorded
    Parameters:
      `more` - the additional forbidden patterns to record
    Returns:
      the new resolution

  - ### maskOut

    AssemblyResolvedPatterns maskOut(ContextOp cop)
    Set all bits read by a given context operation to unknown
    Parameters:
      `cop` - the context operation
    Returns:
      the result
    See Also:
      - `AssemblyPatternBlock.maskOut(ContextOp)`

  - ### writeContextOp

    AssemblyResolvedPatterns writeContextOp(ContextOp cop, MaskedLong val)
    Encode the given value into the context block as specified by an operation

    This is the forward (as in disassembly) direction of applying context operations. The pattern expression is evaluated, and the result is written as specified.

    Parameters:
      `cop` - the context operation specifying the location of the value to encode
      `val` - the masked value to encode
    Returns:
      the result