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

Class AssemblyPatternBlock

  • All Implemented Interfaces:
    java.lang.Comparable<AssemblyPatternBlock>
    public class AssemblyPatternBlock
extends java.lang.Object
implements java.lang.Comparable<AssemblyPatternBlock>
    The analog of PatternBlock, designed for use by the assembler It is suitable for the assembler because it is represented byte-by-byte, and it offers a number of useful conversions and operations. TODO A lot of this could probably be factored into the PatternBlock class, but it was best to experiment in another class altogether to avoid breaking things.

    • Constructor Detail

      • AssemblyPatternBlock

        protected AssemblyPatternBlock​(int offset,
                               byte[] mask,
                               byte[] vals)
        Construct a new pattern block with the given mask, values, and offset
        Parameters:
        offset - an offset (0-up, left-to-right) where the pattern actually starts
        mask - a mask: only 1 bits are included in the pattern
        vals - the value, excluding corresponding 0 bits in the mask

      • AssemblyPatternBlock

        protected AssemblyPatternBlock​(int offset,
                               int capacity)
        Construct a new empty pattern block at the given offset, prepared with the given capacity
        Parameters:
        offset - an offset (0-up, left-to-right) where the pattern will start
        capacity - the space to allocate for the mask and values

    • Method Detail

      • nop

        public static AssemblyPatternBlock nop()
        Get an empty pattern block
        Returns:
        the pattern block

      • fromBytes

        public static AssemblyPatternBlock fromBytes​(int offset,
                                             byte[] vals)
        Get a pattern block with the given (fully-included) values at the given offset
        Parameters:
        offset - the offset (0-up, left-to-right)
        vals - the values
        Returns:
        a pattern block (having a full mask)

      • fromLong

        public static AssemblyPatternBlock fromLong​(long value)
        Convert the given long to a pattern block (having offset 0 and a full mask) NOTE: The result will be 8 bytes in length
        Parameters:
        value - the value to convert
        Returns:
        the pattern block containing the big-endian representation of the value

      • fromMaskedLong

        public static AssemblyPatternBlock fromMaskedLong​(MaskedLong ml)
        Convert the given masked long to a pattern block (having offset 0) NOTE: The result will be 8 bytes in length
        Parameters:
        ml - the masked long, whose values and mask to convert
        Returns:
        the pattern block containing the big-endian representation of the value

      • fromPattern

        public static AssemblyPatternBlock fromPattern​(DisjointPattern pat,
                                               int minLen,
                                               boolean context)
        Convert a block from a disjoint pattern into an assembly pattern block
        Parameters:
        pat - the pattern to convert
        context - true to select the context block, false to select the instruction block
        Returns:
        the converted pattern block

      • fromTokenField

        public static AssemblyPatternBlock fromTokenField​(TokenField tf,
                                                  MaskedLong val)
        Encode the given masked long into a pattern block as specified by a given token field
        Parameters:
        tf - the token field specifying the location of the value to encode
        val - the value to encode
        Returns:
        the pattern block with the encoded value

      • fromContextField

        public static AssemblyPatternBlock fromContextField​(ContextField cf,
                                                    MaskedLong val)
        Encode the given masked long into a pattern block as specified by a given context field
        Parameters:
        cf - the context field specifying the location of the value to encode
        val - the value to encode
        Returns:
        the pattern block with the encoded value

      • fromRegisterValue

        public static AssemblyPatternBlock fromRegisterValue​(RegisterValue rv)
        Convert a register value into a pattern block
        Parameters:
        rv - the register value
        Returns:
        the pattern block This is used primarily to compute default context register values, and pass them into an assembler.

      • fromLength

        public static AssemblyPatternBlock fromLength​(int length)
        Allocate a fully-undefined pattern block of the given length
        Parameters:
        length - the length in bytes
        Returns:
        the block of all unknown bits

      • length

        public int length()
        Get the length (plus the offset) of this pattern block
        Returns:
        the total length

      • shift

        public AssemblyPatternBlock shift​(int amt)
        Shift, i.e., increase the offset of, this pattern block
        Parameters:
        amt - the amount to shift right
        Returns:
        the shifted pattern block

      • truncate

        public AssemblyPatternBlock truncate​(int amt)
        Truncate (unshift) this pattern block by removing bytes from the left
        Parameters:
        amt - the amount to truncate or shift left
        Returns:
        the truncated pattern block

      • combine

        public AssemblyPatternBlock combine​(AssemblyPatternBlock that)
        Combine this pattern block with another given block Two blocks can be combined in their corresponding defined bits agree. When blocks are combined, their bytes are aligned according to their shifts, and the defined bits are taken from either block. If neither block defines a bit (i.e., the mask bit at that position is 0 for both input blocks, then the output has an undefined bit in the corresponding position. If both blocks define the bit, but they have opposite values, then the result is an error.
        Parameters:
        that - the other block
        Returns:
        the new combined block, or null if the blocks disagree for any bit

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

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

      • checkRead

        protected static int checkRead​(byte[] arr,
                               int idx,
                               int def)
        Read an array, returning a default if the index is out of bounds
        Parameters:
        arr - the array to read
        idx - the index
        def - the default value
        Returns:
        the read value

      • writeContextOp

        public AssemblyPatternBlock writeContextOp​(ContextOp cop,
                                           MaskedLong val)
        Encode the given value into a copy of this pattern block as specified by a context operation NOTE: this method is given as a special operation, instead of a conversion factory method, because this is a write operation, not a combine operation. As such, the bits (including undefined bits) replace the bits in the existing pattern block. Were this a conversion method, we would lose the distinction between unknown bits being written, and bits whose values are simply not included in the write.
        Parameters:
        cop - the context operation specifying the location of the value to encode
        val - the value to encode
        Returns:
        the new copy with the encoded value

      • readContextOp

        public MaskedLong readContextOp​(ContextOp cop)
        Read the input of a context operation from this pattern block
        Parameters:
        cop - the context operation
        Returns:
        the decoded input, as a masked value

      • maskOut

        public AssemblyPatternBlock maskOut​(ContextOp cop)
        Set all bits read by a given context operation to unknown
        Parameters:
        cop - the context operation
        Returns:
        the result This is used during resolution to remove a context requirement passed upward by a child. When a parent constructor writes the required value to the context register, that requirement need not be passed further upward, since the write satisfies the requirement.

      • getVals

        public byte[] getVals()
        Get the values array
        Returns:
        the array

      • getMask

        public byte[] getMask()
        Get the mask array
        Returns:
        the array

      • getOffset

        public int getOffset()
        Get the number of undefined bytes preceding the mask and values arrays
        Returns:
        the offset

      • readValBytes

        public long readValBytes​(int start,
                         int len)
        Decode len value bytes in big-endian format, beginning at start
        Parameters:
        start - the first byte to decode
        len - the number of bytes to decode
        Returns:
        the decoded long

      • readMaskBytes

        public long readMaskBytes​(int start,
                          int len)
        Decode len mask bytes in big-endian format, beginning at start
        Parameters:
        start - the first byte to decode
        len - the number of bytes to decode
        Returns:
        the decoded long

      • readBytes

        public MaskedLong readBytes​(int start,
                            int len)
        Decode len bytes (values and mask) in big-endian format, beginning at start
        Parameters:
        start - the first byte to decode
        len - the number of bytes to decode
        Returns:
        the decoded masked long

      • fillMask

        public AssemblyPatternBlock fillMask()
        Fill all unknown bits with 0 bits
        Returns:
        the result

      • isFullMask

        public boolean isFullMask()
        Check if there are any unknown bits
        Returns:
        true if no unknown bits are present, false otherwise

      • isZero

        public boolean isZero()
        Check if all bits are 0 bits
        Returns:
        true if all are 0, false otherwise

      • toBigInteger

        public java.math.BigInteger toBigInteger​(int n)
        Decode the values array into a BigInteger of length n bytes The array is either truncated or zero-extended on the right to match the requested number of bytes, then decoded in big-endian format as an unsigned value.
        Parameters:
        n - the number of bytes (left-to-right) to decode
        Returns:
        the decoded big integer

      • getSpecificity

        public int getSpecificity()
        Counts the total number of known bits in the pattern At a slightly lower level, counts the number of 1-bits in the mask.
        Returns:
        the count

      • countPossibleVals

        public int countPossibleVals()

      • possibleVals

        public java.lang.Iterable<byte[]> possibleVals()
        Get an iterable over all the possible fillings of the value, given a partial mask This is meant to be used idiomatically, as in an enhanced for loop: 
         
 for (byte[] val : pattern.possibleVals()) {
     System.out.println(format(val));
 }
        NOTE: A single byte array is instantiated with the call to Iterable.iterator(). Each call to Iterator.next() modifies the one byte array and returns it. As such, if you intend to preserve the value in the array for later use, you must make a copy.
        Returns:
        the iterable.