Class ProgramDiff


  • public class ProgramDiff
    extends java.lang.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 Detail

      • ProgramDiff

        public ProgramDiff​(Program program1,
                           Program program2)
                    throws ProgramConflictException,
                           java.lang.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.

        java.lang.IllegalArgumentException - if one of the programs is null.
      • ProgramDiff

        public ProgramDiff​(Program program1,
                           Program program2,
                           AddressSetView checkAddressSet)
                    throws ProgramConflictException,
                           java.lang.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.

        java.lang.IllegalArgumentException - if one of the programs is null.
    • Method Detail

      • memoryMatches

        public boolean memoryMatches()
        Return true if the programs to compare have matching memory maps.
      • clone

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

        public java.lang.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​(java.lang.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:
        CancelledException - if the user cancelled the Diff.
        ProgramConflictException
      • 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.
      • 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.
      • 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.
      • 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.