Package ghidra.program.util

# Class ProgramDiff

java.lang.Object
ghidra.program.util.ProgramDiff

public class ProgramDiff extends Object
`ProgramDiff` is a class for comparing two programs and determining where there are differences between them.

Currently, the differences can be determined if the two programs have equivalent address spaces. If the programs have different program context registers, the Diff can still occur but will not determine program context differences.

See Also:
  - `ProgramDiffFilter`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ProgramDiff(Program program1, Program program2)`
  `ProgramDiff` is used to determine the addresses where there are differences between two programs.
  `ProgramDiff(Program program1, Program program2, AddressSetView checkAddressSet)`
  `ProgramDiff` is used to determine the addresses where there are differences between two programs.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `checkCancelled(TaskMonitor monitor)`
  Checks the task associated with the indicated monitor to determine if it has been canceled.
  `protected Object`
  `clone()`
  Returns a copy of this ProgramDiff.
  `boolean`
  `equalRefArrays(Reference[] refs1, Reference[] refs2)`
  Compares an array of references from program1 with an array of references from program2 to see if they are equivalent.
  `boolean`
  `equalRefs(Reference ref1, Reference ref2)`
  Compares reference from program1 with reference from program2 to see if they are equivalent.
  `static boolean`
  `equivalentFunctions(Function f1, Function f2)`
  `static boolean`
  `equivalentFunctions(Function f1, Function f2, boolean ignoreName)`
  `AddressSet`
  `getAddressesInCommon()`
  Returns the addresses in common between program1 and program2.
  `AddressSet`
  `getAddressesOnlyInOne()`
  Returns the addresses that are in program1, but not in program2.
  `AddressSet`
  `getAddressesOnlyInTwo()`
  Returns the addresses that are in program2, but not in program1.
  `AddressSetView`
  `getCombinedAddresses()`
  Returns the addresses from combining the address sets in program1 and program2.
  `AddressSetView`
  `getDifferences(ProgramDiffFilter filter, TaskMonitor monitor)`
  `getDifferences` is used to determine the addresses where there are differences between two programs.
  `AddressSetView`
  `getDifferences(TaskMonitor monitor)`
  `getDifferences` is used to determine the addresses where there are differences between two programs using the current filter.
  `static Reference[]`
  `getDiffRefs(Reference[] refs)`
  Gets the references that need to be checked for differences from those that are handed to it via the refs parameter.
  `ProgramDiffFilter`
  `getFilter()`
  Returns a new ProgramDiffFilter equal to the one in this program diff.
  `AddressSetView`
  `getIgnoreAddressSet()`
  Get the address set that contains addresses that should not be indicated as having any differences.
  `AddressSet`
  `getInitializedInCommon()`
  Returns the initialized memory addresses in common between program1 and program2.
  `AddressSetView`
  `getLimitedAddressSet()`
  Get the address set that the diff process is limited to when checking for differences.
  `Program`
  `getProgramOne()`
  Gets the first program being compared by the ProgramDiff.
  `Program`
  `getProgramTwo()`
  Gets the second program being compared by the ProgramDiff.
  `AddressSetView`
  `getRestrictedAddressSet()`
  Get the address set that the getDifferences method results are restricted to.
  `AddressSetView`
  `getTypeDiffs(int diffType, AddressSetView addrs, TaskMonitor monitor)`
  Creates an address set indicating the differences between program1 and program2 of the specified type.
  `AddressSetView`
  `getUserDefinedDiffs(String property, AddressSetView addrs, TaskMonitor monitor)`
  Returns an address set indicating where the user defined property differs between the Diff's two programs within the specified address set.
  `String`
  `getWarnings()`
  Get a message indicating any warnings about this PRogramDiff.
  `void`
  `ignore(AddressSetView addrs)`
  Set the indicated additional addresses that should not report any differences that are found at them.
  `boolean`
  `isCancelled()`
  Returns whether the last `getDifferences` call was cancelled.
  `static boolean`
  `isEquivalentThunk(Function thunkFunction1, Function thunkFunction2)`
  Compares two thunk functions from different programs to determine if they are equivalent to each other (effectively the same thunk function in the other program).
  `boolean`
  `isSameOperandEquates(Address address, int opIndex)`
  Determines if the two programs have the same equates specified at the indicated address and operand
  `boolean`
  `memoryMatches()`
  Return true if the programs to compare have matching memory maps.
  `void`
  `printDifferences()`
  Print the differences that have been found so far by calls to `getDifferences`.
  `void`
  `printKnownDifferences(int type)`
  Print the differences matching the types indicated that were found thus far by all calls to `getDifferences`.
  `void`
  `printKnownDifferencesByType(int type)`
  Print the differences matching the types indicated that were found thus far by all calls to getDifferences.
  `static boolean`
  `sameFunctionNames(Function f1, Function f2)`
  `void`
  `setFilter(ProgramDiffFilter filter)`
  Sets the ProgramDiffFilter for this program diff.

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

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

- ## Constructor Details

  - ### ProgramDiff

    public ProgramDiff(Program program1, Program program2) throws ProgramConflictException, IllegalArgumentException
    `ProgramDiff` is used to determine the addresses where there are differences between two programs. Possible differences are: the actual bytes at an address, comments, labels, mnemonics, references, equates, properties, functions, program context.

    Currently, the differences can be determined only if the address spaces match between the programs.

    Parameters:
      `program1` - the first program
      `program2` - the second program
    Throws:
      `ProgramConflictException` - indicates that programs couldn't be compared to determine the differences.

      For example,

      the two programs have different address spaces.

      `IllegalArgumentException` - if one of the programs is null.

  - ### ProgramDiff

    public ProgramDiff(Program program1, Program program2, AddressSetView checkAddressSet) throws ProgramConflictException, IllegalArgumentException
    `ProgramDiff` is used to determine the addresses where there are differences between two programs. Possible differences are: the actual bytes at an address, comments, labels, mnemonics, references, equates, properties, functions, program context.

    Currently, the differences can be determined only if the address spaces match between the programs.

    Parameters:
      `program1` - the first program
      `program2` - the second program
      `checkAddressSet` - the address set to be used to constrain where differences are found. The addresses in this address set should be derived from program1.
    Throws:
      `ProgramConflictException` - indicates that programs couldn't be compared to determine the differences.

      For example,

      the two programs have different address spaces. between the two programs, do not match.

      `IllegalArgumentException` - if one of the programs is null.

- ## Method Details

  - ### memoryMatches

    public boolean memoryMatches()
    Return true if the programs to compare have matching memory maps.
    Returns:
      true if program1 and program2 memory address set matches

  - ### clone

    protected Object clone()
    Returns a copy of this ProgramDiff.
    Overrides:
      `clone` in class `Object`
    Returns:
      the copy of this ProgramDiff or null if a MemoryConflictException occurs.

  - ### getWarnings

    public String getWarnings()
    Get a message indicating any warnings about this PRogramDiff. For example, if the program context registers don't match between the programs, the string is a message indicating this.
    Returns:
      the warning message string. null if no warnings.

  - ### getFilter

    public ProgramDiffFilter getFilter()
    Returns a new ProgramDiffFilter equal to the one in this program diff. The filter indicates which types of differences are to be determined.
    Returns:
      a copy of the program diff filter currently in use.

  - ### setFilter

    public void setFilter(ProgramDiffFilter filter)
    Sets the ProgramDiffFilter for this program diff. The filter indicates which types of differences are to be determined.
    Parameters:
      `filter` - the program diff filter

  - ### getProgramOne

    public Program getProgramOne()
    Gets the first program being compared by the ProgramDiff.
    Returns:
      program1.

  - ### getProgramTwo

    public Program getProgramTwo()
    Gets the second program being compared by the ProgramDiff.
    Returns:
      program2.

  - ### getCombinedAddresses

    public AddressSetView getCombinedAddresses()
    Returns the addresses from combining the address sets in program1 and program2.
    Returns:
      the addresses for both program1 and program2. The addresses in this address set are derived from program1.

  - ### getInitializedInCommon

    public AddressSet getInitializedInCommon()
    Returns the initialized memory addresses in common between program1 and program2.
    Returns:
      the initialized memory addresses in common between program1 and program2. The addresses in this set are derived from program1.

  - ### getAddressesInCommon

    public AddressSet getAddressesInCommon()
    Returns the addresses in common between program1 and program2.
    Returns:
      the addresses in common between program1 and program2. The addresses in this address set are derived from program1.

  - ### getAddressesOnlyInOne

    public AddressSet getAddressesOnlyInOne()
    Returns the addresses that are in program1, but not in program2.
    Returns:
      the addresses that are in program1, but not in program2. The addresses in this address set are derived from program1.

  - ### getAddressesOnlyInTwo

    public AddressSet getAddressesOnlyInTwo()
    Returns the addresses that are in program2, but not in program1.
    Returns:
      the addresses that are in program2, but not in program1. The addresses in this address set are derived from program2.

  - ### getDifferences

    public AddressSetView getDifferences(TaskMonitor monitor) throws CancelledException
    `getDifferences` is used to determine the addresses where there are differences between two programs using the current filter. This method only indicates that there is a difference at the address, not what type of difference it is. Possible differences are: the actual bytes at an address, comments, labels, code units, references, equates, properties, and program context register values.
    Parameters:
      `monitor` - the task monitor for indicating the progress of determining differences. This monitor also allows the user to cancel if the diff takes too long. If no monitor is desired, use null.
    Returns:
      an address set of where differences were found between the two programs based on the current filter setting. The addresses in this address set are derived from program1.
    Throws:
      `CancelledException` - if the user cancelled the Diff.

  - ### getDifferences

    public AddressSetView getDifferences(ProgramDiffFilter filter, TaskMonitor monitor) throws CancelledException
    `getDifferences` is used to determine the addresses where there are differences between two programs. This method only indicates that there is a difference at the address, not what type of difference it is. Possible differences are: the actual bytes at an address, comments, labels, code units, references, equates, properties, tags and program context register values.

    The specified filter will become the new current filter.

    Parameters:
      `filter` - the filter to use instead of the current filter defined for this ProgramDiff.
      `monitor` - the task monitor for indicating the progress of determining differences. This monitor also allows the user to cancel if the diff takes too long. If no monitor is desired, use null.
    Returns:
      an address set of where differences were found between the two programs based on the specified filter setting. The addresses in this address set are derived from program1.
    Throws:
      `CancelledException` - if the user cancelled the Diff.

  - ### getUserDefinedDiffs

    public AddressSetView getUserDefinedDiffs(String property, AddressSetView addrs, TaskMonitor monitor) throws CancelledException
    Returns an address set indicating where the user defined property differs between the Diff's two programs within the specified address set.
    Parameters:
      `property` - the user defined property
      `addrs` - the address set for limiting checking. The addresses in this address set should be derived from program1.
      `monitor` - the progress monitor.
    Returns:
      the address set indicating where the property differs. The addresses in this address set are derived from program1.
    Throws:
      `CancelledException` - if the user cancelled the Diff.

  - ### getTypeDiffs

    public AddressSetView getTypeDiffs(int diffType, AddressSetView addrs, TaskMonitor monitor) throws ProgramConflictException, CancelledException
    Creates an address set indicating the differences between program1 and program2 of the specified type.
    Parameters:
      `diffType` - the type of difference to look for between the programs.
      `addrs` - the addresses to check for differences. The addresses in this address set should be derived from program1.
      `monitor` - the task monitor for indicating the progress of determining differences. This monitor reports the progress to the user.
    Returns:
      the address set indicating the differences. The addresses in this address set are derived from program1.
    Throws:
      `ProgramConflictException` - context register definition differs between programs
      `CancelledException` - if the user cancelled the Diff.

  - ### getLimitedAddressSet

    public AddressSetView getLimitedAddressSet()
    Get the address set that the diff process is limited to when checking for differences. Returns null if the diff is not limited (i.e. the entire program is being diffed). The addresses in the returned address set are derived from program1.
    Returns:
      limited address set

  - ### getRestrictedAddressSet

    public AddressSetView getRestrictedAddressSet()
    Get the address set that the getDifferences method results are restricted to. null indicates no current restrictions. The addresses in the returned address set are derived from program1.
    Returns:
      restricted address set

  - ### getIgnoreAddressSet

    public AddressSetView getIgnoreAddressSet()
    Get the address set that contains addresses that should not be indicated as having any differences. The addresses in this address set are derived from program1.
    Returns:
      ignored addresses

  - ### ignore

    public void ignore(AddressSetView addrs)
    Set the indicated additional addresses that should not report any differences that are found at them.
    Parameters:
      `addrs` - the set of addresses to add to the current ignore set. The addresses in this address set should be derived from program1.

  - ### isCancelled

    public boolean isCancelled()
    Returns whether the last `getDifferences` call was cancelled. If a TaskMonitor displays a progress dialog to the user, then the cancel button could have been pressed.
    Returns:
      true if the last `getDifferences` call was cancelled.

  - ### checkCancelled

    public void checkCancelled(TaskMonitor monitor) throws CancelledException
    Checks the task associated with the indicated monitor to determine if it has been canceled.
    Parameters:
      `monitor` - the task monitor, associated with getting differences from this Diff, to be checked
    Throws:
      `CancelledException` - if the getDifferences() task has been canceled by the user.

  - ### printDifferences

    public void printDifferences()
    Print the differences that have been found so far by calls to `getDifferences`.

  - ### printKnownDifferences

    public void printKnownDifferences(int type)
    Print the differences matching the types indicated that were found thus far by all calls to `getDifferences`.
    Parameters:
      `type` - the type(s) of differences we want to see. Valid types are: BYTE_DIFFS, CODE_UNIT_DIFFS, COMMENT_DIFFS, REFERENCE_DIFFS, USER_DEFINED_DIFFS, SYMBOL_DIFFS, EQUATE_DIFFS, PROGRAM_CONTEXT_DIFFS.

  - ### printKnownDifferencesByType

    public void printKnownDifferencesByType(int type)
    Print the differences matching the types indicated that were found thus far by all calls to getDifferences. The differences are grouped by each of the primary difference types.
    Parameters:
      `type` - the type(s) of differences we want to see. Valid types are: BYTE_DIFFS, CODE_UNIT_DIFFS, COMMENT_DIFFS, REFERENCE_DIFFS, USER_DEFINED_DIFFS, SYMBOL_DIFFS, EQUATE_DIFFS, PROGRAM_CONTEXT_DIFFS.

  - ### isSameOperandEquates

    public boolean isSameOperandEquates(Address address, int opIndex)
    Determines if the two programs have the same equates specified at the indicated address and operand
    Parameters:
      `address` - the address This address should be derived from program1.
      `opIndex` - the operand index
    Returns:
      true if both programs have the same operands.

  - ### equivalentFunctions

    public static boolean equivalentFunctions(Function f1, Function f2)

  - ### equivalentFunctions

    public static boolean equivalentFunctions(Function f1, Function f2, boolean ignoreName)

  - ### isEquivalentThunk

    public static boolean isEquivalentThunk(Function thunkFunction1, Function thunkFunction2)
    Compares two thunk functions from different programs to determine if they are equivalent to each other (effectively the same thunk function in the other program).
    Parameters:
      `thunkFunction1` - the first thunk function
      `thunkFunction2` - the second thunk function
    Returns:
      true if the functions are equivalent thunk functions.

  - ### sameFunctionNames

    public static boolean sameFunctionNames(Function f1, Function f2)

  - ### equalRefArrays

    public boolean equalRefArrays(Reference[] refs1, Reference[] refs2)
    Compares an array of references from program1 with an array of references from program2 to see if they are equivalent.
    Parameters:
      `refs1` - program1 array of references
      `refs2` - program2 array of references
    Returns:
      true if the arrays of references are equal.

  - ### equalRefs

    public boolean equalRefs(Reference ref1, Reference ref2)
    Compares reference from program1 with reference from program2 to see if they are equivalent.
    Parameters:
      `ref1` - program1 reference
      `ref2` - program2 reference
    Returns:
      true if they are equivalent

  - ### getDiffRefs

    public static Reference[] getDiffRefs(Reference[] refs)
    Gets the references that need to be checked for differences from those that are handed to it via the refs parameter.
    Parameters:
      `refs` - the references before removing those that we don't want to diff.
    Returns:
      only the references that should be part of the diff.