Package ghidra.program.util

Class ListingDiff

  • public class ListingDiff
extends java.lang.Object
    Determines where instructions couldn't be matched and where they differ between sets of addresses as provided by a ListingAddressCorrelation. Initially this will be byte differences and instruction operand differences for any instructions that were determined to be matched.
    Important: This class is not intended to be used for an entire program. Instead it is for comparing smaller portions such as functions. If the correlation handed to this class associates two large address sets, then the address sets, such as byte differences, that are created by this class could potentially consume large amounts of memory.

    • Constructor Summary

      Constructors 
      Constructor Description
      ListingDiff()
      Creates a ListingDiff to determine where instructions couldn't be matched and where they differ between sets of addresses as provided by a ListingAddressCorrelation.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addListingDiffChangeListener​(ListingDiffChangeListener listener)
      Adds the indicated listener to those that get notified when the ListingDiff's set of differences and unmatched addresses changes.
      boolean doesEntireOperandSetDiffer​(CodeUnit codeUnit1, CodeUnit codeUnit2)
      Determines if the entire set of operands should indicate that it differs.
      AddressSetView getListing1ByteDiffs()
      Gets the addresses in the first listing where byte differences were found based on the current difference settings.
      AddressSetView getListing1CodeUnitDiffs()
      Gets the addresses in the first listing where code unit (mnemonic and/or operand) differences were found based on the current difference settings.
      AddressSetView getListing1Diffs()
      Gets the addresses in the first listing where differences were found based on the current difference settings.
      AddressSetView getListing1UnmatchedCode()
      Gets the addresses in the first listing where matching code couldn't be determined in the second listing.
      AddressSetView getListing2ByteDiffs()
      Gets the addresses in the second listing where byte differences were found based on the current difference settings.
      AddressSetView getListing2CodeUnitDiffs()
      Gets the addresses in the second listing where code unit (mnemonic and/or operand) differences were found based on the current difference settings.
      AddressSetView getListing2Diffs()
      Gets the addresses in the second listing where differences were found based on the current difference settings.
      AddressSetView getListing2UnmatchedCode()
      Gets the addresses in the second listing where matching code couldn't be determined in the first listing.
      Address getMatchingAddress​(Address address, boolean isListing1)
      Gets the matching address from the other listing for the specified address from one of the two listings whose differences this class determines.
      CodeUnit getMatchingCodeUnit​(CodeUnit codeUnit, boolean isListing1)
      Gets the matching code unit from the other listing for the specified code unit from one of the two listings whose differences this class determines.
      int[] getOperandsThatDiffer​(CodeUnit codeUnit1, CodeUnit codeUnit2)
      Gets an array containing the operand indices where the two indicated code units differ.
      boolean hasCorrelation()
      Determines if this ListingDiff currently has an address correlation to use.
      boolean isIgnoringByteDiffs()
      Gets the setting indicating if byte differences are currently being ignored.
      boolean isIgnoringConstants()
      Gets the setting indicating if values of operand constants that differ are currently being ignored when determining code unit differences.
      boolean isIgnoringRegisters()
      Gets the setting indicating if operand registers that differ other than in size are currently being ignored when determining code unit differences.
      void printFunctionComparisonDiffs()
      Outputs an information message, primarily for debugging, that indicates where code was unmatched with the other listing and where various differences, such as bytes and code units, were found.
      void removeListingDiffChangeListener​(ListingDiffChangeListener listener)
      Removes the indicated listener from those that get notified when the ListingDiff's set of differences and unmatched addresses changes.
      void setCorrelation​(ListingAddressCorrelation correlation)
      Sets the address correlation that is used to determine matching addresses between the two listings.
      void setIgnoreByteDiffs​(boolean ignore)
      Changes the setting indicating whether or not byte differences should be ignored.
      void setIgnoreConstants​(boolean ignore)
      Changes the setting indicating if values of operand constants that differ should be ignored when determining code unit differences.
      void setIgnoreRegisters​(boolean ignore)
      Changes the setting indicating if operand registers that differ other than in size should be ignored when determining code unit differences.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • ListingDiff

        public ListingDiff()
        Creates a ListingDiff to determine where instructions couldn't be matched and where they differ between sets of addresses as provided by a ListingAddressCorrelation.

    • Method Detail

      • setCorrelation

        public void setCorrelation​(ListingAddressCorrelation correlation)
                    throws MemoryAccessException
        Sets the address correlation that is used to determine matching addresses between the two listings. Differences can then be determined where a matching address is found.
        Important: This class is not intended to be used for an entire program. Instead it is for comparing smaller portions such as functions. If the correlation handed to this class associates two large address sets, then the address sets, such as byte differences, that are created by this class could potentially consume large amounts of memory.
        Parameters:
        correlation - the address correlation. Otherwise, null to clear the correlation.
        Throws:
        MemoryAccessException - if memory can't be read.

      • hasCorrelation

        public boolean hasCorrelation()
        Determines if this ListingDiff currently has an address correlation to use.
        Returns:
        true if it has an address correlation currently.

      • getOperandsThatDiffer

        public int[] getOperandsThatDiffer​(CodeUnit codeUnit1,
                                   CodeUnit codeUnit2)
        Gets an array containing the operand indices where the two indicated code units differ. These differences are determined based on whether constants and registers are being ignored.
        Parameters:
        codeUnit1 - the first code unit
        codeUnit2 - the second code unit
        Returns:
        an array of operand indices where the operands differ between the two code units based on the current settings that indicate what differences can be ignored.

      • doesEntireOperandSetDiffer

        public boolean doesEntireOperandSetDiffer​(CodeUnit codeUnit1,
                                          CodeUnit codeUnit2)
        Determines if the entire set of operands should indicate that it differs. If the code units aren't the same type then the entire set of operands is considered different. Also if the number of operands differs then as far as we're concerned the entire set differs.
        Parameters:
        codeUnit1 - the first code unit
        codeUnit2 - the second code unit
        Returns:
        true if we should indicate that all operands differ.

      • getListing1UnmatchedCode

        public AddressSetView getListing1UnmatchedCode()
        Gets the addresses in the first listing where matching code couldn't be determined in the second listing.
        Returns:
        the addresses of the unmatched code in the first listing.

      • getListing2UnmatchedCode

        public AddressSetView getListing2UnmatchedCode()
        Gets the addresses in the second listing where matching code couldn't be determined in the first listing.
        Returns:
        the addresses of the unmatched code in the second listing.

      • getListing1Diffs

        public AddressSetView getListing1Diffs()
        Gets the addresses in the first listing where differences were found based on the current difference settings.
        Returns:
        the addresses with differences in the first listing.

      • getListing2Diffs

        public AddressSetView getListing2Diffs()
        Gets the addresses in the second listing where differences were found based on the current difference settings.
        Returns:
        the addresses with differences in the second listing.

      • getListing1CodeUnitDiffs

        public AddressSetView getListing1CodeUnitDiffs()
        Gets the addresses in the first listing where code unit (mnemonic and/or operand) differences were found based on the current difference settings.
        Returns:
        the addresses with code unit differences in the first listing.

      • getListing2CodeUnitDiffs

        public AddressSetView getListing2CodeUnitDiffs()
        Gets the addresses in the second listing where code unit (mnemonic and/or operand) differences were found based on the current difference settings.
        Returns:
        the addresses with code unit differences in the second listing.

      • getListing1ByteDiffs

        public AddressSetView getListing1ByteDiffs()
        Gets the addresses in the first listing where byte differences were found based on the current difference settings.
        Returns:
        the addresses with byte differences in the first listing.

      • getListing2ByteDiffs

        public AddressSetView getListing2ByteDiffs()
        Gets the addresses in the second listing where byte differences were found based on the current difference settings.
        Returns:
        the addresses with byte differences in the second listing.

      • getMatchingAddress

        public Address getMatchingAddress​(Address address,
                                  boolean isListing1)
        Gets the matching address from the other listing for the specified address from one of the two listings whose differences this class determines.
        Parameters:
        address - the address whose matching address this determines.
        isListing1 - true indicates the address is from the first listing. false indicates it is from the second listing.
        Returns:
        the matching address or null

      • printFunctionComparisonDiffs

        public void printFunctionComparisonDiffs()
        Outputs an information message, primarily for debugging, that indicates where code was unmatched with the other listing and where various differences, such as bytes and code units, were found.

      • isIgnoringByteDiffs

        public boolean isIgnoringByteDiffs()
        Gets the setting indicating if byte differences are currently being ignored.
        Returns:
        true if byte differences are being ignored.

      • setIgnoreByteDiffs

        public void setIgnoreByteDiffs​(boolean ignore)
        Changes the setting indicating whether or not byte differences should be ignored.
        Parameters:
        ignore - true indicates to ignore byte differences

      • isIgnoringConstants

        public boolean isIgnoringConstants()
        Gets the setting indicating if values of operand constants that differ are currently being ignored when determining code unit differences.
        Returns:
        true if code unit differences are ignoring differences in values of operand constants.

      • setIgnoreConstants

        public void setIgnoreConstants​(boolean ignore)
        Changes the setting indicating if values of operand constants that differ should be ignored when determining code unit differences.
        Parameters:
        ignore - true means code unit differences should ignore differences in values of operand constants.

      • isIgnoringRegisters

        public boolean isIgnoringRegisters()
        Gets the setting indicating if operand registers that differ other than in size are currently being ignored when determining code unit differences.
        Returns:
        true if code unit differences are ignoring operand register differences other than in size.

      • setIgnoreRegisters

        public void setIgnoreRegisters​(boolean ignore)
        Changes the setting indicating if operand registers that differ other than in size should be ignored when determining code unit differences.
        Parameters:
        ignore - true means code unit differences should ignore operand register differences other than in size.

      • addListingDiffChangeListener

        public void addListingDiffChangeListener​(ListingDiffChangeListener listener)
        Adds the indicated listener to those that get notified when the ListingDiff's set of differences and unmatched addresses changes.
        Parameters:
        listener - the listener to be notified

      • removeListingDiffChangeListener

        public void removeListingDiffChangeListener​(ListingDiffChangeListener listener)
        Removes the indicated listener from those that get notified when the ListingDiff's set of differences and unmatched addresses changes.
        Parameters:
        listener - the listener to be removed

      • getMatchingCodeUnit

        public CodeUnit getMatchingCodeUnit​(CodeUnit codeUnit,
                                    boolean isListing1)
        Gets the matching code unit from the other listing for the specified code unit from one of the two listings whose differences this class determines.
        Parameters:
        codeUnit - the code unit whose match this determines.
        isListing1 - true indicates the code unit is from the first listing. false indicates it is from the second listing.
        Returns:
        the matching code unit or null