Class AssemblyResolvedPatterns

java.lang.Object
ghidra.app.plugin.assembler.sleigh.sem.AssemblyResolution
ghidra.app.plugin.assembler.sleigh.sem.AssemblyResolvedPatterns
All Implemented Interfaces:
Comparable<AssemblyResolution>

public class AssemblyResolvedPatterns extends AssemblyResolution
A AssemblyResolution indicating successful application of a constructor

This is almost analogous to DisjointPattern, in that is joins an instruction AssemblyPatternBlock with a corresponding context AssemblyPatternBlock. However, this object is mutable, and it collects backfill records, as well as forbidden patterns.

When the applied constructor is from the "instruction" subtable, this represents a fully- constructed instruction with required context. All backfill records ought to be resolved and applied before the final result is given to the user, i.e., passed into the AssemblySelector. If at any time during the resolution or backfill process, the result becomes confined to one of the forbidden patterns, it must be dropped, since the encoding will actually invoke a more specific SLEIGH constructor.

  • Field Details

  • Method Details

    • computeHash

      protected int computeHash()
      Specified by:
      computeHash in class AssemblyResolution
    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
    • fromString

      public static AssemblyResolvedPatterns fromString(String str, String description, List<AssemblyResolution> children)
      Build a new successful SLEIGH constructor resolution from a string representation

      This was used primarily in testing, to specify expected results.

      Parameters:
      str - the string representation: "ins:[pattern],ctx:[pattern]"
      description - a description of the resolution
      children - any children involved in the resolution
      Returns:
      the decoded resolution
      See Also:
    • shift

      public AssemblyResolvedPatterns shift(int amt)
      Description copied from class: 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 class AssemblyResolution
      Parameters:
      amt - the number of bytes to shift.
      Returns:
      the result
    • truncate

      public AssemblyResolvedPatterns truncate(int amt)
      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:
      amt - the number of bytes to remove from the left
      Returns:
      the result
    • checkNotForbidden

      public 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
    • bitsEqual

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

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

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

      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:
      that - the other resolution
      Returns:
      the result if successful, or null
    • combineLessBackfill

      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
    • combine

      Combine the given backfill record into this resolution
      Parameters:
      bf - the backfill record
      Returns:
      the result
    • withForbids

      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
    • withDescription

      public AssemblyResolvedPatterns withDescription(String desc)
      Create a copy of this resolution with a new description
      Parameters:
      desc - the new description
      Returns:
      the copy
    • withConstructor

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

      public AssemblyResolvedPatterns writeContextOp(ContextOp cop, MaskedLong val)
      Encode the given value into the context block as specified by an operation
      Parameters:
      cop - the context operation specifying the location of the value to encode
      val - the masked value to encode
      Returns:
      the result This is the forward (as in disassembly) direction of applying context operations. The pattern expression is evaluated, and the result is written as specified.
    • readContextOp

      public 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.
    • copyAppendDescription

      public AssemblyResolvedPatterns copyAppendDescription(String append)
      Duplicate this resolution, with additional description text appended
      Parameters:
      append - the text to append
      Returns:
      the duplicate NOTE: An additional separator ": " is inserted
    • withRight

      public AssemblyResolvedPatterns withRight(AssemblyResolution right)
      Description copied from class: AssemblyResolution
      Get this same resolution, but with the given right sibling
      Specified by:
      withRight in class AssemblyResolution
      Returns:
      the resolution
    • nopLeftSibling

      public AssemblyResolvedPatterns nopLeftSibling()
    • parent

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

      public 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:
    • backfill

      public 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.
    • lineToString

      public String lineToString()
      Description copied from class: AssemblyResolution
      Display the resolution result in one line (omitting child details)
      Specified by:
      lineToString in class AssemblyResolution
      Returns:
      the display description
    • hasBackfills

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

      public 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:
    • getInstructionLength

      public 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

      public 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
    • getInstruction

      public AssemblyPatternBlock getInstruction()
      Get the instruction block
      Returns:
      the instruction block
    • getContext

      public AssemblyPatternBlock getContext()
      Get the context block
      Returns:
      the context block
    • readInstruction

      public MaskedLong readInstruction(int start, int len)
      Decode a portion of the instruction block
      Parameters:
      start - the first byte to decode
      len - the number of bytes to decode
      Returns:
      the read masked value
      See Also:
    • readContext

      public 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:
    • isError

      public boolean isError()
      Description copied from class: AssemblyResolution
      Check if this record describes an error
      Specified by:
      isError in class AssemblyResolution
      Returns:
      true if the record is an error
    • isBackfill

      public boolean isBackfill()
      Description copied from class: AssemblyResolution
      Check if this record describes a backfill
      Specified by:
      isBackfill in class AssemblyResolution
      Returns:
      true if the record is a backfill
    • hasChildren

      public boolean hasChildren()
      Description copied from class: AssemblyResolution
      Check if this record has children

      If a subclass has another, possibly additional, notion of children that it would like to include in AssemblyResolution.toString(), it must override this method to return true when such children are present.

      Overrides:
      hasChildren in class AssemblyResolution
      Returns:
      true if this record has children
      See Also:
    • childrenToString

      protected String childrenToString(String indent)
      Description copied from class: AssemblyResolution
      Get the child portion of AssemblyResolution.toString()

      If a subclass has another, possible additional, notion of children that it would like to include in AssemblyResolution.toString(), it must override this method.

      Overrides:
      childrenToString in class AssemblyResolution
      Parameters:
      indent - the current indentation
      Returns:
      the indented description for each child on its own line
      See Also:
    • dumpConstructorTree

      public 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:
    • getSpecificity

      public int getSpecificity()
      Count the number of bits specified in the resolution patterns

      Totals the specificity of the instruction and context pattern blocks.

      Returns:
      the number of bits in the resulting patterns
      See Also:
    • possibleInsVals

      public 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
    • getOpIndex

      protected static int getOpIndex(String piece)
    • getPureRecursion

      protected static ConstructState getPureRecursion(ConstructState state)
      If the construct state is a ^instruction or other purely-recursive constructor, get its single child.
      Parameters:
      state - the parent state
      Returns:
      the child state if recursive, or null
    • equivalentConstructState

      public boolean equivalentConstructState(ConstructState state)