Package ghidra.program.model.correlate

# Class HashedFunctionAddressCorrelation

java.lang.Object
ghidra.program.model.correlate.HashedFunctionAddressCorrelation

All Implemented Interfaces:
  `ListingAddressCorrelation`

public class HashedFunctionAddressCorrelation extends Object implements ListingAddressCorrelation
Correlator to construct a 1-1 map between the Instructions of two similar Functions. Matching is performed via a greedy algorithm that looks for sequences (n-grams) of Instructions that are similar between the two Functions. Similarity of two sequences is determined by comparing hashes generated by the HashCalculator object. 1) Potential sequences and their hashes are generated for both functions (see HashStore). 2) Sequences are pulled from the HashStore based on the uniqueness of a potential match and on the size of the sequence. 3) If a unique match is found between sequences, it is extended in either direction as far as possible, as constrained by HashCalculator and the containing basic-blocks. 4) The matching Instruction pairs are put in the final map and removed from further sequence lists to allow other potential matches to be considered. 5) Sequences with no corresponding match are also removed from consideration. 6) Sequences are limited to a single basic-block, and the algorithm is basic-block aware. Once a match establishes a correspondence between a pair of basic blocks, the algorithm uses 7) If a particular sequence has matches that are not unique, the algorithm tries to disambiguate the potential matches by looking at parent/child relationships of the containing basic-blocks. (see DisambiguateStrategy) 8) Multiple passes are attempted, each time the set of potential sequences is completely regenerated, varying the range of sequence sizes for which a match is attempted and other hash parameters. This allows matches discovered by earlier passes to disambiguate sequences in later passes.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `HashedFunctionAddressCorrelation(Function leftFunction, Function rightFunction, TaskMonitor monitor)`
  Correlates addresses between the two specified functions.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Address`
  `getAddress(Duo.Side side, Address otherSideAddress)`
  Gets the address for the given side that matches the given address from the other side.
  `AddressSetView`
  `getAddresses(Duo.Side side)`
  Gets the addresses that are part of the correlator for the given side
  `Iterator<Map.Entry<Address,Address>>`
  `getFirstToSecondIterator()`
  Gets an iterator of the matching addresses from the first function to the second.
  `Function`
  `getFunction(Duo.Side side)`
  Gets the function for the given side.
  `Program`
  `getProgram(Duo.Side side)`
  Gets the program for the given side.
  `int`
  `getTotalInstructionsInFirst()`
  Gets the total number of instructions that are in the first function.
  `int`
  `getTotalInstructionsInSecond()`
  Gets the total number of instructions that are in the second function.
  `List<Instruction>`
  `getUnmatchedInstructionsInFirst()`
  Determines the number of instructions from the first function that do not match an instruction in the second function.
  `List<Instruction>`
  `getUnmatchedInstructionsInSecond()`
  Determines the number of instructions from the second function that do not match an instruction in the first function.
  `int`
  `numMatchedInstructionsInFirst()`
  Determines the number of instructions from the first function that match an instruction in the second function.
  `int`
  `numMatchedInstructionsInSecond()`
  Determines the number of instructions from the second function that match an instruction in the first function.

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

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

- ## Constructor Details

  - ### HashedFunctionAddressCorrelation

    public HashedFunctionAddressCorrelation(Function leftFunction, Function rightFunction, TaskMonitor monitor) throws CancelledException, MemoryAccessException
    Correlates addresses between the two specified functions.
    Parameters:
      `leftFunction` - the first function
      `rightFunction` - the second function
      `monitor` - the task monitor that indicates progress and allows the user to cancel.
    Throws:
      `CancelledException` - if the user cancels1
      `MemoryAccessException` - if either functions memory can't be accessed.

- ## Method Details

  - ### getProgram

    public Program getProgram(Duo.Side side)
    Description copied from interface: `ListingAddressCorrelation`
    Gets the program for the given side.
    Specified by:
      `getProgram` in interface `ListingAddressCorrelation`
    Parameters:
      `side` - LEFT or RIGHT
    Returns:
      the program for the given side

  - ### getAddresses

    public AddressSetView getAddresses(Duo.Side side)
    Description copied from interface: `ListingAddressCorrelation`
    Gets the addresses that are part of the correlator for the given side
    Specified by:
      `getAddresses` in interface `ListingAddressCorrelation`
    Parameters:
      `side` - LEFT or RIGHT
    Returns:
      the addresses that are part of the correlator for the given side

  - ### getTotalInstructionsInFirst

    public int getTotalInstructionsInFirst()
    Gets the total number of instructions that are in the first function.
    Returns:
      the first function's instruction count.

  - ### getTotalInstructionsInSecond

    public int getTotalInstructionsInSecond()
    Gets the total number of instructions that are in the second function.
    Returns:
      the second function's instruction count.

  - ### numMatchedInstructionsInFirst

    public int numMatchedInstructionsInFirst()
    Determines the number of instructions from the first function that match an instruction in the second function.
    Returns:
      the number of instructions in the first function that have matches.

  - ### numMatchedInstructionsInSecond

    public int numMatchedInstructionsInSecond()
    Determines the number of instructions from the second function that match an instruction in the first function.
    Returns:
      the number of instructions in the second function that have matches.

  - ### getUnmatchedInstructionsInFirst

    public List<Instruction> getUnmatchedInstructionsInFirst()
    Determines the number of instructions from the first function that do not match an instruction in the second function.
    Returns:
      the number of instructions in the first function without matches.

  - ### getUnmatchedInstructionsInSecond

    public List<Instruction> getUnmatchedInstructionsInSecond()
    Determines the number of instructions from the second function that do not match an instruction in the first function.
    Returns:
      the number of instructions in the second function without matches.

  - ### getFirstToSecondIterator

    public Iterator<Map.Entry<Address,Address>> getFirstToSecondIterator()
    Gets an iterator of the matching addresses from the first function to the second.
    Returns:
      the iterator

  - ### getAddress

    public Address getAddress(Duo.Side side, Address otherSideAddress)
    Description copied from interface: `ListingAddressCorrelation`
    Gets the address for the given side that matches the given address from the other side.
    Specified by:
      `getAddress` in interface `ListingAddressCorrelation`
    Parameters:
      `side` - the side to get an address for
      `otherSideAddress` - the address from the other side to find a match for
    Returns:
      the address for the given side that matches the given address from the other side.

  - ### getFunction

    public Function getFunction(Duo.Side side)
    Description copied from interface: `ListingAddressCorrelation`
    Gets the function for the given side. This will be null if the addresses are not function based.
    Specified by:
      `getFunction` in interface `ListingAddressCorrelation`
    Parameters:
      `side` - LEFT or RIGHT
    Returns:
      the function for the given side or null if not function based