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

# 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 Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Set<AssemblyResolvedBackfill>`
  `backfills`
  `protected final Constructor`
  `cons`
  `protected final AssemblyPatternBlock`
  `ctx`
  `protected static final String`
  `CTX`
  `protected final Set<AssemblyResolvedPatterns>`
  `forbids`
  `protected final AssemblyPatternBlock`
  `ins`
  `protected static final String`
  `INS`
  `protected static final Pattern`
  `pat`
  `protected static final String`
  `SEP`

  ### Fields inherited from class ghidra.app.plugin.assembler.sleigh.sem.AssemblyResolution

  `children, description, right`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `AssemblyResolution`
  `backfill(RecursiveDescentSolver solver, Map<String,Long> vals)`
  Apply as many backfill records as possible
  `protected 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
  `protected String`
  `childrenToString(String indent)`
  Get the child portion of `AssemblyResolution.toString()`
  `AssemblyResolvedPatterns`
  `combine(AssemblyResolvedBackfill bf)`
  Combine the given backfill record into this resolution
  `AssemblyResolvedPatterns`
  `combine(AssemblyResolvedPatterns that)`
  Combine the encodings and backfills of the given resolution into this one
  `protected AssemblyResolvedPatterns`
  `combineLessBackfill(AssemblyResolvedPatterns that, AssemblyResolvedBackfill bf)`
  Combine a backfill result
  `protected int`
  `computeHash()`
  `AssemblyResolvedPatterns`
  `copyAppendDescription(String append)`
  Duplicate this resolution, with additional description text appended
  `String`
  `dumpConstructorTree()`
  Used for testing and diagnostics: list the constructor line numbers used to resolve this encoding
  `boolean`
  `equals(Object obj)`
  `boolean`
  `equivalentConstructState(ConstructState state)`
  `static AssemblyResolvedPatterns`
  `fromString(String str, String description, List<AssemblyResolution> children)`
  Build a new successful SLEIGH constructor resolution from a string representation
  `AssemblyPatternBlock`
  `getContext()`
  Get the context block
  `int`
  `getDefinedInstructionLength()`
  Get the length of the instruction encoding, excluding trailing undefined bytes
  `AssemblyPatternBlock`
  `getInstruction()`
  Get the instruction block
  `int`
  `getInstructionLength()`
  Get the length of the instruction encoding
  `protected static int`
  `getOpIndex(String piece)`
  `protected static ConstructState`
  `getPureRecursion(ConstructState state)`
  If the construct state is a `^instruction` or other purely-recursive constructor, get its single child.
  `int`
  `getSpecificity()`
  Count the number of bits specified in the resolution patterns
  `boolean`
  `hasBackfills()`
  Check if this resolution has pending backfills to apply
  `boolean`
  `hasChildren()`
  Check if this record has children
  `boolean`
  `isBackfill()`
  Check if this record describes a backfill
  `boolean`
  `isError()`
  Check if this record describes an error
  `String`
  `lineToString()`
  Display the resolution result in one line (omitting child details)
  `AssemblyResolvedPatterns`
  `maskOut(ContextOp cop)`
  Set all bits read by a given context operation to unknown
  `AssemblyResolvedPatterns`
  `nopLeftSibling()`
  `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 start, int len)`
  Decode a portion of the instruction block
  `AssemblyResolvedPatterns`
  `shift(int amt)`
  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 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.
  `AssemblyResolvedPatterns`
  `withConstructor(Constructor cons)`
  Create a copy of this resolution with a replaced constructor
  `AssemblyResolvedPatterns`
  `withDescription(String desc)`
  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)`
  Get this same resolution, but with the given right sibling
  `AssemblyResolvedPatterns`
  `writeContextOp(ContextOp cop, MaskedLong val)`
  Encode the given value into the context block as specified by an operation

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

  `backfill, collectAllRight, compareTo, contextOnly, error, error, error, fromPattern, getAllRight, hashCode, instrOnly, nop, nop, resolved, toString, toString, withoutRight`

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### INS

    protected static final String INS
    See Also:
      - Constant Field Values

  - ### CTX

    protected static final String CTX
    See Also:
      - Constant Field Values

  - ### SEP

    protected static final String SEP
    See Also:
      - Constant Field Values

  - ### cons

    protected final Constructor cons

  - ### ins

    protected final AssemblyPatternBlock ins

  - ### ctx

    protected final AssemblyPatternBlock ctx

  - ### backfills

    protected final Set<AssemblyResolvedBackfill> backfills

  - ### forbids

    protected final Set<AssemblyResolvedPatterns> forbids

  - ### pat

    protected static final Pattern pat

- ## 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:
      - `NumericUtilities.convertHexStringToMaskedValue(AtomicLong, AtomicLong, String, int, int, String)`

  - ### 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

    public AssemblyResolvedPatterns combine(AssemblyResolvedPatterns that)
    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

    protected 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

  - ### combine

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

  - ### withForbids

    public 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

  - ### 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:
      - `AssemblyPatternBlock.maskOut(ContextOp)`

  - ### 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:
      - `AssemblyConstructorSemantic.solveContextChanges(AssemblyResolvedPatterns, Map)`

  - ### 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:
      - `AssemblyPatternBlock.readBytes(int, int)`

  - ### 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:
      - `AssemblyPatternBlock.readBytes(int, int)`

  - ### 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:
      - `AssemblyResolution.childrenToString(String)`

  - ### 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:
      - `AssemblyResolution.hasChildren()`

  - ### 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:
      - `ConstructState.dumpConstructorTree()`

  - ### 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:
      - `AssemblyPatternBlock.getSpecificity()`

  - ### 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)