Package ghidra.program.database.references

Class ReferenceDBManager

    • Constructor Detail

      • ReferenceDBManager

        public ReferenceDBManager​(DBHandle dbHandle,
                          AddressMap addrMap,
                          int openMode,
                          Lock lock,
                          TaskMonitor monitor)
                   throws CancelledException,
                          java.io.IOException,
                          VersionException
        Construct a new reference manager.
        Parameters:
        dbHandle - handle to the database
        addrMap - map to convert addresses to longs and longs to addresses
        openMode - one of ProgramDB.CREATE, UPDATE, UPGRADE, or READ_ONLY
        lock - the program synchronization lock
        monitor - Task monitor for upgrading
        Throws:
        CancelledException - if the user cancels the loading of this db
        java.io.IOException - if a database io error occurs.
        VersionException - if the database version is different from the expected version

    • Method Detail

      • setProgram

        public void setProgram​(ProgramDB program)
        Description copied from interface: ManagerDB
        Callback from program used to indicate all manager have been created. When this method is invoked, all managers have been instantiated but may not be fully initialized.
        Specified by:
        setProgram in interface ManagerDB
        Parameters:
        program - the program is set when all the initializations have been completed.

      • programReady

        public void programReady​(int openMode,
                         int currentRevision,
                         TaskMonitor monitor)
                  throws java.io.IOException,
                         CancelledException
        Description copied from interface: ManagerDB
        Callback from program made to each manager after the program has completed initialization. This method may be used by managers to perform additional upgrading which may have been deferred.
        Specified by:
        programReady in interface ManagerDB
        Parameters:
        openMode - the mode that the program is being opened.
        currentRevision - current program revision. If openMode is UPGRADE, this value reflects the pre-upgrade value.
        monitor - the task monitor to use in any upgrade operations.
        Throws:
        java.io.IOException - if a database io error occurs.
        CancelledException - if the user cancelled the operation via the task monitor.

      • addMemoryReference

        public Reference addMemoryReference​(Address fromAddr,
                                    Address toAddr,
                                    RefType type,
                                    SourceType sourceType,
                                    int opIndex)
        Description copied from interface: ReferenceManager
        Adds a memory reference. Only first the first memory reference placed on an operand will be made primary by default. All non-memory references will be removed from the specified operand.
        Specified by:
        addMemoryReference in interface ReferenceManager
        Parameters:
        fromAddr - address of the codeunit where the reference occurs
        toAddr - address of the location being referenced. Memory, stack, and register addresses are all permitted.
        type - reference type - how the location is being referenced.
        sourceType - the source of this reference
        opIndex - the operand index display of the operand making this reference

      • addStackReference

        public Reference addStackReference​(Address fromAddr,
                                   int opIndex,
                                   int stackOffset,
                                   RefType type,
                                   SourceType sourceType)
        Description copied from interface: ReferenceManager
        Add a reference to a stack location. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
        Specified by:
        addStackReference in interface ReferenceManager
        Parameters:
        fromAddr - "from" address within a function
        opIndex - operand index
        stackOffset - stack offset of the reference
        type - reference type - how the location is being referenced.
        sourceType - the source of this reference

      • addRegisterReference

        public Reference addRegisterReference​(Address fromAddr,
                                      int opIndex,
                                      Register register,
                                      RefType type,
                                      SourceType sourceType)
        Description copied from interface: ReferenceManager
        Add a reference to a register. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
        Specified by:
        addRegisterReference in interface ReferenceManager
        Parameters:
        fromAddr - "from" address
        opIndex - operand index
        register - register to add the reference to
        type - reference type - how the location is being referenced.
        sourceType - the source of this reference

      • addOffsetMemReference

        public Reference addOffsetMemReference​(Address fromAddr,
                                       Address toAddr,
                                       long offset,
                                       RefType type,
                                       SourceType sourceType,
                                       int opIndex)
        Description copied from interface: ReferenceManager
        Add an offset memory reference. Only first the first memory reference placed on an operand will be made primary by default. All non-memory references will be removed from the specified operand.
        Specified by:
        addOffsetMemReference in interface ReferenceManager
        Parameters:
        fromAddr - address for the "from"
        toAddr - address of the "to"
        offset - value added to a base address to get the toAddr
        type - reference type - how the location is being referenced
        sourceType - the source of this reference
        opIndex - the operand index

      • addShiftedMemReference

        public Reference addShiftedMemReference​(Address fromAddr,
                                        Address toAddr,
                                        int shiftValue,
                                        RefType type,
                                        SourceType sourceType,
                                        int opIndex)
        Description copied from interface: ReferenceManager
        Add a shifted memory reference; the "to" address is computed as the value at the operand at opIndex shifted by some number of bits, specified in the shiftValue parameter. Only first the first memory reference placed on an operand will be made primary by default. All non-memory references will be removed from the specified operand.
        Specified by:
        addShiftedMemReference in interface ReferenceManager
        Parameters:
        fromAddr - address for the "from"
        toAddr - computed as the value of the operand at opIndex shifted by the number of bits specified by shiftValue
        type - reference type - how the location is being referenced
        sourceType - the source of this reference
        opIndex - the operand index

      • addExternalReference

        public Reference addExternalReference​(Address fromAddr,
                                      int opIndex,
                                      ExternalLocation location,
                                      SourceType sourceType,
                                      RefType type)
                               throws InvalidInputException
        Description copied from interface: ReferenceManager
        Adds an external reference. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
        Specified by:
        addExternalReference in interface ReferenceManager
        Parameters:
        fromAddr - from address (source of the reference)
        opIndex - operand index
        location - external location
        sourceType - the source of this reference
        type - reference type - how the location is being referenced
        Returns:
        external reference
        Throws:
        InvalidInputException

      • addExternalReference

        public Reference addExternalReference​(Address fromAddr,
                                      java.lang.String libraryName,
                                      java.lang.String extLabel,
                                      Address extAddr,
                                      SourceType sourceType,
                                      int opIndex,
                                      RefType type)
                               throws InvalidInputException,
                                      DuplicateNameException
        Description copied from interface: ReferenceManager
        Adds an external reference. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
        Specified by:
        addExternalReference in interface ReferenceManager
        Parameters:
        fromAddr - from address (source of the reference)
        libraryName - name of external program
        extLabel - label within the external program, may be null if extAddr is not null
        extAddr - address within the external program, may be null
        sourceType - the source of this reference
        opIndex - operand index
        type - reference type - how the location is being referenced
        Throws:
        InvalidInputException
        DuplicateNameException

      • addExternalReference

        public Reference addExternalReference​(Address fromAddr,
                                      Namespace extNamespace,
                                      java.lang.String extLabel,
                                      Address extAddr,
                                      SourceType sourceType,
                                      int opIndex,
                                      RefType type)
                               throws InvalidInputException,
                                      DuplicateNameException
        Description copied from interface: ReferenceManager
        Adds an external reference. If a reference already exists for the fromAddr and opIndex, the existing reference is replaced with the new reference.
        Specified by:
        addExternalReference in interface ReferenceManager
        Parameters:
        fromAddr - from address (source of the reference)
        extNamespace - external namespace containing the named external label.
        extLabel - label within the external program, may be null if extAddr is not null
        extAddr - address within the external program, may be null
        sourceType - the source of this reference
        opIndex - operand index
        type - reference type - how the location is being referenced
        Throws:
        InvalidInputException
        DuplicateNameException

      • getReferencedVariable

        public Variable getReferencedVariable​(Reference reference)
        Attempts to determine which if any of the local functions variables are referenced by the specified reference. In utilizing the firstUseOffset scoping model, negative offsets (relative to the functions entry) are shifted beyond the maximum positive offset within the function. While this does not account for the actual instruction flow, it is hopefully accurate enough for most situations.
        Specified by:
        getReferencedVariable in interface ReferenceManager
        Returns:
        function variable or null if variable not found
        See Also:
        ReferenceManager.getReferencedVariable(ghidra.program.model.symbol.Reference)

      • getReferencesTo

        public Reference[] getReferencesTo​(Variable var)
        Attempts to determine the set of references which refer to the specified variable. In utilizing the firstUseOffset scoping model, negative offsets (relative to the functions entry) are shifted beyond the maximum positive offset within the function. While this does not account for the actual instruction flow, it is hopefully accurate enough for most situations.
        Specified by:
        getReferencesTo in interface ReferenceManager
        Parameters:
        var - variable to retrieve references to
        Returns:
        array of variable references, or zero length array if no references exist
        See Also:
        ReferenceManager.getReferencesTo(ghidra.program.model.listing.Variable)

      • setPrimary

        public void setPrimary​(Reference ref,
                       boolean isPrimary)
        Description copied from interface: ReferenceManager
        Set the given reference's primary attribute
        Specified by:
        setPrimary in interface ReferenceManager
        Parameters:
        ref - the reference to make primary.
        isPrimary - true to make the reference primary, false to make it non-primary

      • getReferencesFrom

        public Reference[] getReferencesFrom​(Address addr)
        Description copied from interface: ReferenceManager
        Get all references "from" the specified addr.
        Specified by:
        getReferencesFrom in interface ReferenceManager
        Parameters:
        addr - address of code-unit making the references.
        Returns:
        array of all references "from" the specified addr.

      • getReference

        public Reference getReference​(Address fromAddr,
                              Address toAddr,
                              int opIndex)
        Description copied from interface: ReferenceManager
        Get the reference that has the given from and to address, and operand index.
        Specified by:
        getReference in interface ReferenceManager
        Parameters:
        fromAddr - the address of the codeunit making the reference.
        toAddr - the address being referred to.
        opIndex - the operand index.

      • getReferenceCountFrom

        public int getReferenceCountFrom​(Address fromAddr)
        Description copied from interface: ReferenceManager
        Returns the number of memory References from the specified fromAddr
        Specified by:
        getReferenceCountFrom in interface ReferenceManager
        Parameters:
        fromAddr - the address of the codeunit making the reference.

      • getReferenceCountTo

        public int getReferenceCountTo​(Address toAddr)
        Description copied from interface: ReferenceManager
        Returns the number of memory References to the specified toAddr
        Specified by:
        getReferenceCountTo in interface ReferenceManager
        Parameters:
        toAddr - the address being referenced

      • getReferenceDestinationIterator

        public AddressIterator getReferenceDestinationIterator​(Address startAddr,
                                                       boolean forward)
        Description copied from interface: ReferenceManager
        Returns an iterator over all addresses that are the "To" address in a reference.
        Specified by:
        getReferenceDestinationIterator in interface ReferenceManager
        Parameters:
        startAddr - start of iterator
        forward - true means to iterate in the forward direction

      • getReferenceDestinationIterator

        public AddressIterator getReferenceDestinationIterator​(AddressSetView addrSet,
                                                       boolean forward)
        Description copied from interface: ReferenceManager
        Returns an iterator over all addresses that are the "To" address in a memory reference, restricted by the given address set.
        Specified by:
        getReferenceDestinationIterator in interface ReferenceManager
        Parameters:
        addrSet - the set of address to restrict the iterator or null for all addresses.
        forward - true means to iterate in the forward direction

      • getReferenceSourceIterator

        public AddressIterator getReferenceSourceIterator​(Address startAddr,
                                                  boolean forward)
        Description copied from interface: ReferenceManager
        Returns an iterator over addresses that are the "From" address in a reference
        Specified by:
        getReferenceSourceIterator in interface ReferenceManager
        Parameters:
        startAddr - address to position iterator.
        forward - true means to iterate in the forward direction

      • getReferenceIterator

        public ReferenceIterator getReferenceIterator​(Address startAddr)
        Description copied from interface: ReferenceManager
        Get an iterator over references starting with the specified fromAddr. A forward iterator is returned with references sorted on the from address.
        Specified by:
        getReferenceIterator in interface ReferenceManager
        Parameters:
        startAddr - the first from address to consider.
        Returns:
        a forward memory reference iterator.

      • getReferenceSourceIterator

        public AddressIterator getReferenceSourceIterator​(AddressSetView addrSet,
                                                  boolean forward)
        Description copied from interface: ReferenceManager
        Returns an iterator over all addresses that are the "From" address in a reference, restricted by the given address set.
        Specified by:
        getReferenceSourceIterator in interface ReferenceManager
        Parameters:
        addrSet - the set of address to restrict the iterator or null for all addresses.
        forward - true means to iterate in the forward direction

      • hasFlowReferencesFrom

        public boolean hasFlowReferencesFrom​(Address addr)
        Description copied from interface: ReferenceManager
        Return whether the given address has flow references from this address.
        Specified by:
        hasFlowReferencesFrom in interface ReferenceManager
        Parameters:
        addr - the address to test for flow references.

      • hasReferencesFrom

        public boolean hasReferencesFrom​(Address fromAddr)
        Description copied from interface: ReferenceManager
        Returns true if there are any memory references at the given address.
        Specified by:
        hasReferencesFrom in interface ReferenceManager
        Parameters:
        fromAddr - the address of the codeunit being tested

      • hasReferencesFrom

        public boolean hasReferencesFrom​(Address fromAddr,
                                 int opIndex)
        Description copied from interface: ReferenceManager
        Returns true if there are any memory references at the given address/opIndex. Keep in mind this is a rather inefficient method as it must examine all references from the specified fromAddr.
        Specified by:
        hasReferencesFrom in interface ReferenceManager
        Parameters:
        fromAddr - the address of the codeunit being tested
        opIndex - the index of the operand being tested.

      • hasReferencesTo

        public boolean hasReferencesTo​(Address toAddr)
        Description copied from interface: ReferenceManager
        Return true if a memory reference exists with the given "to" address.
        Specified by:
        hasReferencesTo in interface ReferenceManager
        Parameters:
        toAddr - address being referred to.

      • removeAllReferencesFrom

        public void removeAllReferencesFrom​(Address beginAddr,
                                    Address endAddr)
        Description copied from interface: ReferenceManager
        Removes all references where "From address" is in the given range.
        Specified by:
        removeAllReferencesFrom in interface ReferenceManager
        Parameters:
        beginAddr - the first address in the range.
        endAddr - the last address in the range.

      • removeAllReferencesFrom

        public void removeAllReferencesFrom​(Address fromAddr)
        Description copied from interface: ReferenceManager
        Remove all stack, external, and memory references for the given from address.
        Specified by:
        removeAllReferencesFrom in interface ReferenceManager
        Parameters:
        fromAddr - the address of the codeunit from which to remove all references.

      • removeAllReferencesTo

        public void removeAllReferencesTo​(Address toAddr)
        Description copied from interface: ReferenceManager
        Remove all stack, external, and memory references for the given to address.
        Specified by:
        removeAllReferencesTo in interface ReferenceManager
        Parameters:
        toAddr - the address for which all references to should be removed.

      • symbolRemoved

        public void symbolRemoved​(Symbol symbol)
        Symbol is about to be removed
        Parameters:
        symbol - the symbol that will be removed

      • symbolAdded

        public void symbolAdded​(Symbol sym)
        Symbol has been added
        Parameters:
        sym - new symbol

      • setAssociation

        public void setAssociation​(Symbol s,
                           Reference ref)
        Description copied from interface: ReferenceManager
        Associates the given reference with the given symbol.
        Specified by:
        setAssociation in interface ReferenceManager
        Parameters:
        s - the symbol to associate with the given reference.
        ref - the reference to associate with the given symbol

      • removeAssociation

        public void removeAssociation​(Reference ref)
        Description copied from interface: ReferenceManager
        Removes any symbol associations with the given reference.
        Specified by:
        removeAssociation in interface ReferenceManager
        Parameters:
        ref - the reference for which any symbol association is to be removed.

      • getReferencesTo

        public ReferenceIterator getReferencesTo​(Address addr)
        Description copied from interface: ReferenceManager
        Get an iterator over all references that have the given address as their "To" address.
        Specified by:
        getReferencesTo in interface ReferenceManager
        Parameters:
        addr - the address that all references in the iterator refer to.

      • invalidateCache

        public void invalidateCache​(boolean all)
        Description copied from interface: ManagerDB
        Clears all data caches.
        Specified by:
        invalidateCache in interface ManagerDB
        Parameters:
        all - if false, some managers may not need to update their cache if they can tell that its not necessary. If this flag is true, then all managers should clear their cache no matter what.

      • moveReferencesTo

        public int moveReferencesTo​(Address oldToAddr,
                            Address newToAddr,
                            TaskMonitor monitor)
                     throws CancelledException,
                            java.io.IOException
        Move all references to the specified oldAddr. Any symbol binding will be discarded since these are intended for memory label references only. This method is intended specifically to support upgrading of certain references (i.e., Stack, Register and External addresses). NOTE! After ProgramDB version 12, this method will no longer be useful for upgrading stack and register references since they will not exist within the ReferenceTo-list.
        Parameters:
        oldToAddr - old reference to address
        newToAddr - new reference to address
        monitor - the monitor
        Returns:
        number of references updated
        Throws:
        CancelledException - if the task is cancelled
        java.io.IOException - if a database exception occurs

      • deleteAddressRange

        public void deleteAddressRange​(Address startAddr,
                               Address endAddr,
                               TaskMonitor monitor)
        Description copied from interface: ManagerDB
        Delete all objects which have been applied to the address range startAddr to endAddr and update the database accordingly.
        Specified by:
        deleteAddressRange in interface ManagerDB
        Parameters:
        startAddr - the first address in the range.
        endAddr - the last address in the range.
        monitor - the task monitor to use in any upgrade operations.

      • moveAddressRange

        public void moveAddressRange​(Address fromAddr,
                             Address toAddr,
                             long length,
                             TaskMonitor monitor)
                      throws CancelledException
        Description copied from interface: ManagerDB
        Move all objects within an address range to a new location.
        Specified by:
        moveAddressRange in interface ManagerDB
        Parameters:
        fromAddr - the first address of the range to be moved.
        toAddr - the address where to the range is to be moved.
        length - the number of addresses to move.
        monitor - the task monitor to use in any upgrade operations.
        Throws:
        CancelledException - if the user cancelled the operation via the task monitor.

      • getReferenceLevel

        public byte getReferenceLevel​(Address toAddr)
        Returns the reference level for the references to the given address
        Specified by:
        getReferenceLevel in interface ReferenceManager
        Parameters:
        toAddr - the address at which to find the highest reference level

      • getExternalEntryIterator

        public AddressIterator getExternalEntryIterator()

      • isExternalEntryPoint

        public boolean isExternalEntryPoint​(Address toAddr)
        Return whether the address is an external entry point
        Parameters:
        toAddr - the address to test for external entry point
        Returns:
        true if the address is an external entry point

      • addExternalEntryPointRef

        public void addExternalEntryPointRef​(Address toAddr)
        Create a memory reference to the given address to mark it as an external entry point.
        Parameters:
        toAddr - the address at which to make an external entry point

      • removeExternalEntryPoint

        public void removeExternalEntryPoint​(Address addr)
        Removes the external entry point at the given address
        Parameters:
        addr - that address at which to remove the external entry point attribute.

      • dbError

        public void dbError​(java.io.IOException e)
        Description copied from interface: ErrorHandler
        Notification that an IO exception occurred.
        Specified by:
        dbError in interface ErrorHandler

      • delete

        public void delete​(Reference ref)
        Description copied from interface: ReferenceManager
        Deletes the given reference object
        Specified by:
        delete in interface ReferenceManager
        Parameters:
        ref - the reference to be deleted.

      • getReferencesFrom

        public Reference[] getReferencesFrom​(Address fromAddr,
                                     int opIndex)
        Description copied from interface: ReferenceManager
        Returns all references "from" the given fromAddr and operand (specified by opIndex).
        Specified by:
        getReferencesFrom in interface ReferenceManager
        Parameters:
        fromAddr - the from which to get references
        opIndex - the operand from which to get references
        Returns:
        all references "from" the given fromAddr and operand.