Package ghidra.program.database.references

Class ReferenceDBManager

java.lang.Object
ghidra.program.database.references.ReferenceDBManager
All Implemented Interfaces:
ErrorHandler, ManagerDB, ReferenceManager
public class ReferenceDBManager extends Object implements ReferenceManager, ManagerDB, ErrorHandler
Reference manager implementation for the database.

  • Constructor Details

    • ReferenceDBManager

      public ReferenceDBManager(DBHandle dbHandle, AddressMap addrMap, OpenMode openMode, Lock lock, TaskMonitor monitor) throws CancelledException, 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
      IOException - if a database io error occurs.
      VersionException - if the database version is different from the expected version

  • Method Details

    • 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(OpenMode openMode, int currentRevision, TaskMonitor monitor) throws 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:
      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. 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. Certain reference types may not be specified (e.g., RefType.FALL_THROUGH).
      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
      Returns:
      new memory 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
      Returns:
      new stack 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
      Returns:
      new register reference

    • addOffsetMemReference

      public Reference addOffsetMemReference(Address fromAddr, Address toAddr, boolean toAddrIsBase, long offset, RefType type, SourceType sourceType, int opIndex)
      Description copied from interface: ReferenceManager
      Add an offset memory reference. 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. If toAddr corresponds to the EXTERNAL memory block (see MemoryBlock.EXTERNAL_BLOCK_NAME) the resulting offset reference will report to/base address as the same regardless of specified offset.
      Specified by:
      addOffsetMemReference in interface ReferenceManager
      Parameters:
      fromAddr - address for the "from"
      toAddr - address of the location being referenced.
      toAddrIsBase - if true toAddr is treated as base address, else treated as (base+offet). It is generally preferred to specify as a base address to ensure proper handling of EXTERNAL block case.
      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
      Returns:
      new offset reference

    • 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. 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 - source/from memory address
      toAddr - destination/to memory address computed as some base offset value shifted left by the number of bits specified by shiftValue. The least-significant bits of toAddr offset should be 0's based upon the specified shiftValue since this value is shifted right to calculate the base offset value.
      shiftValue - number of bits to shift
      type - reference type - how the location is being referenced
      sourceType - the source of this reference
      opIndex - the operand index
      Returns:
      new shifted reference

    • 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 memory 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, String libraryName, String extLabel, Address extAddr, SourceType sourceType, int opIndex, RefType type) throws InvalidInputException, DuplicateNameException
      Description copied from interface: ReferenceManager
      Adds an external reference to an external symbol. If a reference already exists at fromAddr and opIndex the existing reference is replaced with a new reference. If the external symbol cannot be found, a new Library and/or ExternalLocation symbol will be created which corresponds to the specified library/file named libraryName and the location within that file identified by extLabel and/or its memory address extAddr. Either or both extLabel or extAddr must be specified.
      Specified by:
      addExternalReference in interface ReferenceManager
      Parameters:
      fromAddr - from memory 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 - memory 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
      Returns:
      new external space reference
      Throws:
      InvalidInputException - if libraryName is invalid or null, or an invalid extlabel is specified. Names with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.
      DuplicateNameException - if another non-Library namespace has the same name

    • addExternalReference

      public Reference addExternalReference(Address fromAddr, Namespace extNamespace, 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 memory 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
      Returns:
      new external space reference
      Throws:
      InvalidInputException - if an invalid extlabel is specified. Names with spaces or the empty string are not permitted. Neither extLabel nor extAddr was specified properly.
      DuplicateNameException - if another non-Library namespace has the same name

    • 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
      Parameters:
      reference - variable reference
      Returns:
      function variable or null if variable not found
      See Also:

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

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

    • getFlowReferencesFrom

      public Reference[] getFlowReferencesFrom(Address addr)
      Description copied from interface: ReferenceManager
      Get all flow references from the given address.
      Specified by:
      getFlowReferencesFrom in interface ReferenceManager
      Parameters:
      addr - the address of the codeunit to get all flows from.
      Returns:
      get all flow references from the given address.

    • 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.
      Returns:
      reference which satisfies the specified criteria or null

    • getReferenceCountFrom

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

    • getReferenceCountTo

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

    • getReferenceDestinationCount

      public int getReferenceDestinationCount()
      Description copied from interface: ReferenceManager
      Return the number of references for "to" addresses.
      Specified by:
      getReferenceDestinationCount in interface ReferenceManager

    • getReferenceSourceCount

      public int getReferenceSourceCount()
      Description copied from interface: ReferenceManager
      Return the number of references for "from" addresses.
      Specified by:
      getReferenceSourceCount in interface ReferenceManager

    • getPrimaryReferenceFrom

      public Reference getPrimaryReferenceFrom(Address addr, int opIndex)
      Description copied from interface: ReferenceManager
      Get the primary reference from the given address.
      Specified by:
      getPrimaryReferenceFrom in interface ReferenceManager
      Parameters:
      addr - from address
      opIndex - operand index
      Returns:
      the primary reference from the specified address and opindex if it exists, else null

    • 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 address iterator where references to exist
      Returns:
      address iterator where references to exist

    • 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
      Returns:
      address iterator where references to exist constrained by addrSet

    • 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
      Returns:
      address iterator where references from exist

    • 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 address iterator where references from exist
      Returns:
      address iterator where references from exist constrained by addrSet

    • hasFlowReferencesFrom

      public boolean hasFlowReferencesFrom(Address addr)
      Description copied from interface: ReferenceManager
      Return whether the given address has flow references from it.
      Specified by:
      hasFlowReferencesFrom in interface ReferenceManager
      Parameters:
      addr - the address to test for flow references.
      Returns:
      true if the given address has flow references from it, else false

    • 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
      Returns:
      true if one or more reference from the specified address are defined, else false

    • 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.
      Returns:
      true if one or more reference from the specified address and opindex are defined, else false

    • 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.
      Returns:
      true if specified toAddr has one or more references to it, else false.

    • 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. Applies to memory references only where a specified label symbol must have an address which matches the reference to-address. Stack and register reference associations to variable symbols are always inferred.
      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.

    • updateRefType

      public Reference updateRefType(Reference ref, RefType refType)
      Description copied from interface: ReferenceManager
      Uodate the reference type on a memory reference.
      Specified by:
      updateRefType in interface ReferenceManager
      Parameters:
      ref - reference to be updated
      refType - new reference type
      Returns:
      updated reference

    • 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.
      Returns:
      reference iterator over all references to the specified address.

    • 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, 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
      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. The specified start and end addresses must form a valid range within a single AddressSpace.
      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
      Returns:
      reference level for specified to address.

    • 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) throws IllegalArgumentException
      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
      Throws:
      IllegalArgumentException - if a non-memory address is specified

    • 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(IOException e)
      Description copied from interface: ErrorHandler
      Notification that an IO exception occurred.
      Specified by:
      dbError in interface ErrorHandler
      Parameters:
      e - IOException which was cause of error

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

    • getExternalReferences

      public ReferenceIterator getExternalReferences()
      Description copied from interface: ReferenceManager
      Returns an iterator over all external space references
      Specified by:
      getExternalReferences in interface ReferenceManager
      Returns:
      reference iterator over all external space references

    • addReference

      public Reference addReference(Reference ref)
      Description copied from interface: ReferenceManager
      Add a memory, stack, register or external reference
      Specified by:
      addReference in interface ReferenceManager
      Parameters:
      ref - reference to be added
      Returns:
      new reference

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