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:
  • 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 the 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.