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

Class AssemblyResolvedConstructor

  • All Implemented Interfaces:
    java.lang.Comparable<AssemblyResolution>
    public class AssemblyResolvedConstructor
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.

    • Method Detail

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • shift

        public AssemblyResolvedConstructor shift​(int amt)
        Shift the resolved instruction pattern to the right This also shifts any backfill and forbidden pattern records.
        Parameters:
        amt - the number of bytes to shift.
        Returns:
        the result

      • truncate

        public AssemblyResolvedConstructor 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 become 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​(AssemblyResolvedConstructor that)
        Check if this and another resolution have equal encodings This is like equals(Object), but it ignores backfills records and forbidden patterns.
        Parameters:
        that - the other resolution
        Returns:
        true if both have equal encodings

      • combine

        public AssemblyResolvedConstructor combine​(AssemblyResolvedConstructor 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 AssemblyResolvedConstructor combineLessBackfill​(AssemblyResolvedConstructor that,
                                                          AssemblyResolvedBackfill bf)
        Combine a backfill result
        Parameters:
        that - the result from backfilling
        bf - the resolved backfilled record
        Returns:
        the result if successful, or null 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.

      • withForbids

        public AssemblyResolvedConstructor withForbids​(java.util.Set<AssemblyResolvedConstructor> 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 AssemblyResolvedConstructor withDescription​(java.lang.String desc)
        Create a copy of this resolution with a new description
        Parameters:
        desc - the new description
        Returns:
        the copy

      • writeContextOp

        public AssemblyResolvedConstructor 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 AssemblyResolvedConstructor copyAppendDescription​(java.lang.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

      • backfill

        public AssemblyResolution backfill​(RecursiveDescentSolver solver,
                                   java.util.Map<java.lang.String,​java.lang.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 java.lang.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 AssemblyResolvedConstructor solveContextChangesForForbids​(AssemblyConstructorSemantic sem,
                                                                 java.util.Map<java.lang.String,​java.lang.Long> vals,
                                                                 java.util.Map<java.lang.Integer,​java.lang.Object> opvals)
        Solve and apply context changes in reverse to forbidden patterns To avoid circumstances where a context change during disassembly would invoke a more specific subconstructor 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
        opvals - the operand values
        Returns:
        the result
        See Also:
        AssemblyConstructorSemantic.solveContextChanges(AssemblyResolvedConstructor, Map, 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
        Returns:
        the length of the instruction block NOTE: this DOES include the offset NOTE: this DOES include pending backfills

      • getDefinedInstructionLength

        public int getDefinedInstructionLength()
        Get the length of the instruction encoding, excluding trailing undefined bytes
        Returns:
        the length of the defined bytes in the instruction block NOTE: this DOES include the offset NOTE: this DOES NOT include pending backfills

      • 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

      • dumpConstructorTree

        public java.lang.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 java.lang.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