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

# Class AssemblyConstructorSemantic

java.lang.Object
ghidra.app.plugin.assembler.sleigh.sem.AssemblyConstructorSemantic

All Implemented Interfaces:
  `Comparable<AssemblyConstructorSemantic>`

public class AssemblyConstructorSemantic extends Object implements Comparable<AssemblyConstructorSemantic>
Describes a SLEIGH constructor semantic

These are collected and associated with productions in the grammar based on the given constructor's print pieces.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Constructor`
  `cons`
  `protected final List<ContextChange>`
  `contextChanges`
  `protected final AbstractAssemblyResolutionFactory<?,?>`
  `factory`
  `protected final List<Integer>`
  `indices`
  `protected final Set<AssemblyResolvedPatterns>`
  `patterns`
  `protected final List<ContextChange>`
  `reversedChanges`
  `protected static final RecursiveDescentSolver`
  `SOLVER`
  `protected Set<AssemblyResolvedPatterns>`
  `upatterns`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AssemblyConstructorSemantic(AbstractAssemblyResolutionFactory<?,?> factory, Constructor cons, List<Integer> indices)`
  Build a new SLEIGH constructor semantic

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addPattern(AssemblyResolvedPatterns pat)`
  Record a pattern that would select the constructor
  `void`
  `addPattern(DisjointPattern pat)`
  Record a pattern that would select the constructor
  `AssemblyResolvedPatterns`
  `applyContextChangesForward(Map<String,Long> vals, AssemblyResolvedPatterns fromLeft)`
  Apply just context transformations in the forward (disassembly) direction
  `Stream<AssemblyResolvedPatterns>`
  `applyPatternsForward(int shift, AssemblyResolvedPatterns fromLeft)`
  Apply just the instruction patterns in the forward (disassembly) direction
  `int`
  `compareTo(AssemblyConstructorSemantic that)`
  `protected void`
  `computeAllForbids()`
  Initialize upatterns with an unmodifiable copy of patterns, with forbidden patterns added
  `Constructor`
  `getConstructor()`
  Get the SLEIGH constructor
  `String`
  `getLocation()`
  Render this constructor's source location for diagnostics
  `static String`
  `getLocation(Constructor cons)`
  Render the constructor's source location for diagnostics
  `int`
  `getOperandIndex(int printpos)`
  Convert the index of a print piece to its associated operand index
  `Iterator<Integer>`
  `getOperandIndexIterator()`
  Get an iterator over the operand indices
  `List<Integer>`
  `getOperandIndices()`
  Get the list of operand indices in print piece order
  `Collection<AssemblyResolvedPatterns>`
  `getPatterns()`
  Get the associated encoding patterns for the constructor
  `AssemblyResolution`
  `solveContextChanges(AssemblyResolvedPatterns res, Map<String,Long> vals)`
  Solve this constructor's context changes
  `String`
  `toString()`
  `protected AssemblyResolvedPatterns`
  `withComputedForbids(AssemblyResolvedPatterns pat)`
  Add the list of forbidden patterns to one of the constructor's patterns

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

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

- ## Field Details

  - ### SOLVER

    protected static final RecursiveDescentSolver SOLVER

  - ### patterns

    protected final Set<AssemblyResolvedPatterns> patterns

  - ### factory

    protected final AbstractAssemblyResolutionFactory<?,?> factory

  - ### cons

    protected final Constructor cons

  - ### indices

    protected final List<Integer> indices

  - ### contextChanges

    protected final List<ContextChange> contextChanges

  - ### reversedChanges

    protected final List<ContextChange> reversedChanges

  - ### upatterns

    protected Set<AssemblyResolvedPatterns> upatterns

- ## Constructor Details

  - ### AssemblyConstructorSemantic

    public AssemblyConstructorSemantic(AbstractAssemblyResolutionFactory<?,?> factory, Constructor cons, List<Integer> indices)
    Build a new SLEIGH constructor semantic
    Parameters:
      `cons` - the SLEIGH constructor
      `indices` - the indices of RHS non-terminals in the associated production that represent an operand in the SLEIGH constructor

- ## Method Details

  - ### addPattern

    public void addPattern(DisjointPattern pat)
    Record a pattern that would select the constructor
    Parameters:
      `pat` - the pattern

  - ### addPattern

    public void addPattern(AssemblyResolvedPatterns pat)
    Record a pattern that would select the constructor
    Parameters:
      `pat` - the pattern

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### getLocation

    public static String getLocation(Constructor cons)
    Render the constructor's source location for diagnostics
    Parameters:
      `cons` - the constructor
    Returns:
      the location as `file:lineno`

  - ### getLocation

    public String getLocation()
    Render this constructor's source location for diagnostics
    Returns:
      the location

  - ### getConstructor

    public Constructor getConstructor()
    Get the SLEIGH constructor
    Returns:
      the constructor

  - ### getPatterns

    public Collection<AssemblyResolvedPatterns> getPatterns()
    Get the associated encoding patterns for the constructor
    Returns:
      the patterns

  - ### getOperandIndex

    public int getOperandIndex(int printpos)
    Convert the index of a print piece to its associated operand index
    Parameters:
      `printpos` - position excluding whitespace and string tokens.
    Returns:
      the operand index

  - ### getOperandIndices

    public List<Integer> getOperandIndices()
    Get the list of operand indices in print piece order
    Returns:
      the list

  - ### getOperandIndexIterator

    public Iterator<Integer> getOperandIndexIterator()
    Get an iterator over the operand indices

    If this iterator is advanced for each non-terminal, while simultaneously iterating over the RHS of the associated production, then this will identify the corresponding operand index for each non-terminal

    Returns:
      the iterator

  - ### computeAllForbids

    protected void computeAllForbids()
    Initialize upatterns with an unmodifiable copy of patterns, with forbidden patterns added

  - ### withComputedForbids

    protected AssemblyResolvedPatterns withComputedForbids(AssemblyResolvedPatterns pat)
    Add the list of forbidden patterns to one of the constructor's patterns

    SLEIGH disambiguates multiple matching pattern by two rules. First, if one is more specific than ("specializes") another, i.e., it matches on more bits than another pattern, the more specific pattern is chosen. Second, if the two are equally special, then the one that occurs first in the SLEIGH specification is taken. So, during resolution, if a less-special or later-occurring constructor is chosen, we must prevent continued resolution from matching the more-special or earlier-occurring pattern(s).

    Essentially, this states, "you may choose any value matching my pattern, except those that match these forbidden patterns."

    This takes a given pattern, and searches the rest of the language for any patterns that would take precedence, and combines them as forbidden patterns with the given pattern.

    Parameters:
      `pat` - the given pattern
    Returns:
      the same pattern with forbidden records added

  - ### solveContextChanges

    public AssemblyResolution solveContextChanges(AssemblyResolvedPatterns res, Map<String,Long> vals)
    Solve this constructor's context changes

    Each value in `opvals` must either be a numeric value, e.g., an index from a varnode list, or another `AssemblyResolvedPatterns` for a subconstructor operand.

    It's helpful to think of the SLEIGH disassembly process here. Normally, once the appropriate constructor has been identified (by matching patterns), its context changes are applied, and then its operands parsed (possibly parsing subconstructor operands). Thus, `res` can be thought of as the intermediate result between applying context changes and parsing operands, except in reverse. The output of this method corresponds to the state before context changes were applied, i.e., immediately after selecting the constructor. Thus, in reverse, the context is solved immediately before applying the selected constructor patterns.

    Parameters:
      `res` - the combined resolution requirements derived from the subconstructors
      `vals` - any defined symbols (usually `inst_start`, and `inst_next`)
    Returns:
      the resolution with context changes applied in reverse, or an error

  - ### applyContextChangesForward

    public AssemblyResolvedPatterns applyContextChangesForward(Map<String,Long> vals, AssemblyResolvedPatterns fromLeft)
    Apply just context transformations in the forward (disassembly) direction

    Unlike the usual disassembly process, this method does not take into account any information from the instruction encoding. Any context bits that depend on it are set to unknown (`x`) in the output. This method is used to pre-compute a context transition graph in order to quickly resolve purely-recursive semantics on the root constructor table.

    Parameters:
      `fromLeft` - the state before context changes
    Returns:
      the state after context changes

  - ### applyPatternsForward

    public Stream<AssemblyResolvedPatterns> applyPatternsForward(int shift, AssemblyResolvedPatterns fromLeft)
    Apply just the instruction patterns in the forward (disassembly) direction
    Parameters:
      `shift` - the (right) shift in bytes to apply to the patterns before combining
      `fromLeft` - the accumulated patterns from the left sibling or parent
    Returns:
      the stream of results

  - ### compareTo

    public int compareTo(AssemblyConstructorSemantic that)
    Specified by:
      `compareTo` in interface `Comparable<AssemblyConstructorSemantic>`