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

# Class AssemblyPatternBlock

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

All Implemented Interfaces:
  `Comparable<AssemblyPatternBlock>`

public class AssemblyPatternBlock extends Object implements 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.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final String`
  `SHIFT_STR`
  `protected static final String`
  `SHIFT_STR_END`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `AssemblyPatternBlock(int offset, byte[] mask, byte[] vals)`
  Construct a new pattern block with the given mask, values, and offset
  `protected`
  `AssemblyPatternBlock(int offset, int capacity)`
  Construct a new empty pattern block at the given offset, prepared with the given capacity

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected static int`
  `checkRead(byte[] arr, int idx, int def)`
  Read an array, returning a default if the index is out of bounds
  `AssemblyPatternBlock`
  `combine(AssemblyPatternBlock that)`
  Combine this pattern block with another given block
  `int`
  `compareTo(AssemblyPatternBlock that)`
  `AssemblyPatternBlock`
  `copy()`
  Duplicate this pattern block
  `int`
  `countPossibleVals()`
  `boolean`
  `equals(Object obj)`
  `AssemblyPatternBlock`
  `fillMask()`
  Fill all unknown bits with 0 bits
  `static AssemblyPatternBlock`
  `fromBytes(int offset, byte[] vals)`
  Get a pattern block with the given (fully-included) values at the given offset
  `static AssemblyPatternBlock`
  `fromContextField(ContextField cf, MaskedLong val)`
  Encode the given masked long into a pattern block as specified by a given context field
  `static AssemblyPatternBlock`
  `fromLength(int length)`
  Allocate a fully-undefined pattern block of the given length
  `static AssemblyPatternBlock`
  `fromPattern(DisjointPattern pat, int minLen, boolean context)`
  Convert a block from a disjoint pattern into an assembly pattern block
  `static AssemblyPatternBlock`
  `fromRegisterValue(RegisterValue rv)`
  Convert a register value into a pattern block This is used primarily to compute default context register values, and pass them into an assembler.
  `static AssemblyPatternBlock`
  `fromString(String str)`
  Convert a string representation to a pattern block
  `static AssemblyPatternBlock`
  `fromTokenField(TokenField tf, MaskedLong val)`
  Encode the given masked long into a pattern block as specified by a given token field
  `byte[]`
  `getMask()`
  Get the mask array
  `int`
  `getOffset()`
  Get the number of undefined bytes preceding the mask and values arrays
  `int`
  `getSpecificity()`
  Counts the total number of known bits in the pattern
  `byte[]`
  `getVals()`
  Get the values array
  `int`
  `hashCode()`
  `boolean`
  `isFullMask()`
  Check if there are any unknown bits
  `boolean`
  `isZero()`
  Check if all bits are 0 bits
  `int`
  `length()`
  Get the length (plus the offset) of this pattern block
  `AssemblyPatternBlock`
  `maskOut(ContextOp cop)`
  Set all bits read by a given context operation to unknown
  `static AssemblyPatternBlock`
  `nop()`
  Get an empty pattern block
  `Iterable<byte[]>`
  `possibleVals()`
  Get an iterable over all the possible fillings of the value, given a partial mask
  `MaskedLong`
  `readBytes(int start, int len)`
  Decode `len` bytes (values and mask) in big-endian format, beginning at `start`
  `MaskedLong`
  `readContextOp(ContextOp cop)`
  Read the input of a context operation from this pattern block
  `long`
  `readMaskBytes(int start, int len)`
  Decode `len` mask bytes in big-endian format, beginning at `start`
  `long`
  `readValBytes(int start, int len)`
  Decode `len` value bytes in big-endian format, beginning at `start`
  `AssemblyPatternBlock`
  `shift(int amt)`
  Shift, i.e., increase the offset of, this pattern block
  `BigInteger`
  `toBigInteger(int n)`
  Decode the values array into a `BigInteger` of length `n` bytes
  `String`
  `toString()`
  `AssemblyPatternBlock`
  `truncate(int amt)`
  Truncate (unshift) this pattern block by removing bytes from the left
  `AssemblyPatternBlock`
  `writeContextOp(ContextOp cop, MaskedLong val)`
  Encode the given value into a copy of this pattern block as specified by a context operation

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

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

- ## Field Details

  - ### SHIFT_STR

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

  - ### SHIFT_STR_END

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

- ## Constructor Details

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

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

  - ### fromString

    public static AssemblyPatternBlock fromString(String str)
    Convert a string representation to a pattern block
    Parameters:
      `str` - the string to convert
    Returns:
      the resulting pattern block
    See Also:
      - `NumericUtilities.convertHexStringToMaskedValue(AtomicLong, AtomicLong, String, int, int, String)`

  - ### 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 This is used primarily to compute default context register values, and pass them into an assembler.
    Parameters:
      `rv` - the register value
    Returns:
      the pattern block

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

  - ### copy

    public AssemblyPatternBlock copy()
    Duplicate this pattern block
    Returns:
      the duplicate

  - ### 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 String toString()
    Overrides:
      `toString` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### equals

    public boolean equals(Object obj)
    Overrides:
      `equals` in class `Object`

  - ### compareTo

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

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

    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.

    Parameters:
      `cop` - the context operation
    Returns:
      the result

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