Package ghidra.trace.database.symbol

# Class DBTraceReferenceManager

java.lang.Object
ghidra.trace.database.space.AbstractDBTraceSpaceBasedManager<DBTraceReferenceSpace>
ghidra.trace.database.symbol.DBTraceReferenceManager

All Implemented Interfaces:
  `ErrorHandler`, `DBTraceManager`, `DBTraceDelegatingManager<DBTraceReferenceSpace>`, `TraceReferenceManager`, `TraceReferenceOperations`

public class DBTraceReferenceManager extends AbstractDBTraceSpaceBasedManager<DBTraceReferenceSpace> implements TraceReferenceManager, DBTraceDelegatingManager<DBTraceReferenceSpace>

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class ghidra.trace.database.space.AbstractDBTraceSpaceBasedManager

  `AbstractDBTraceSpaceBasedManager.DBTraceSpaceEntry`

  ## Nested classes/interfaces inherited from interface ghidra.trace.database.space.DBTraceDelegatingManager

  `DBTraceDelegatingManager.ExcConsumer<T,E extends Throwable>, DBTraceDelegatingManager.ExcFunction<T,R,E extends Throwable>, DBTraceDelegatingManager.ExcPredicate<T,E extends Throwable>, DBTraceDelegatingManager.ExcSupplier<T,E extends Throwable>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `NAME`
  `protected final DBTraceOverlaySpaceAdapter`
  `overlayAdapter`

  ### Fields inherited from class ghidra.trace.database.space.AbstractDBTraceSpaceBasedManager

  `baseLanguage, dbh, lock, name, NO_ADDRESS_SPACE, regSpacesByContainer, spaces, spaceStore, spacesView, threadManager, trace`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DBTraceReferenceManager(DBHandle dbh, OpenMode openMode, ReadWriteLock lock, TaskMonitor monitor, Language baseLanguage, DBTrace trace, DBTraceThreadManager threadManager, DBTraceOverlaySpaceAdapter overlayAdapter)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `DBTraceReference`
  `addMemoryReference(Lifespan lifespan, Address fromAddress, AddressRange toRange, RefType refType, SourceType source, int operandIndex)`
  Add a memory reference
  `DBTraceOffsetReference`
  `addOffsetReference(Lifespan lifespan, Address fromAddress, Address toAddress, boolean toAddrIsBase, long offset, RefType refType, SourceType source, int operandIndex)`
  Add an offset memory reference
  `DBTraceReference`
  `addReference(Lifespan lifespan, Reference reference)`
  A (a copy of) the given reference to this manager
  `DBTraceReference`
  `addReference(TraceReference reference)`
  A (a copy of) the given reference to this manager
  `DBTraceReference`
  `addRegisterReference(Lifespan lifespan, Address fromAddress, Register toRegister, RefType refType, SourceType source, int operandIndex)`
  Add a register reference
  `DBTraceShiftedReference`
  `addShiftedReference(Lifespan lifespan, Address fromAddress, Address toAddress, int shift, RefType refType, SourceType source, int operandIndex)`
  Add a shifted memory reference
  `DBTraceReference`
  `addStackReference(Lifespan lifespan, Address fromAddress, int toStackOffset, RefType refType, SourceType source, int operandIndex)`
  Add a (static) stack reference
  `DBTraceReference`
  `assertIsMine(Reference ref)`
  `void`
  `checkIsInMemory(AddressSpace space)`
  Ensures that a "from" address is in memory
  `void`
  `clearReferencesFrom(Lifespan span, AddressRange range)`
  Clear all references from the given lifespan and address range
  `void`
  `clearReferencesTo(Lifespan span, AddressRange range)`
  Clear all references to the given lifespan and address range
  `protected DBTraceReferenceSpace`
  `createSpace(AddressSpace space, AbstractDBTraceSpaceBasedManager.DBTraceSpaceEntry ent)`
  `protected void`
  `doAddXRef(DBTraceReferenceSpace.DBTraceReferenceEntry entry)`
  `protected void`
  `doDelXRef(DBTraceReferenceSpace.DBTraceReferenceEntry entry)`
  `protected void`
  `doSetXRefLifespan(DBTraceReferenceSpace.DBTraceReferenceEntry entry)`
  `Collection<? extends DBTraceReference>`
  `getFlowReferencesFrom(long snap, Address fromAddress)`
  Get all flow references from the given snapshot and address
  `DBTraceReferenceSpace`
  `getForSpace(AddressSpace space, boolean createIfAbsent)`
  `DBTraceReference`
  `getPrimaryReferenceFrom(long snap, Address fromAddress, int operandIndex)`
  Get the primary reference matching from the given snapshot, address, and operand index
  `DBTraceReference`
  `getReference(long snap, Address fromAddress, AddressRange toRange, int operandIndex)`
  Find the reference that matches the given parameters
  `int`
  `getReferenceCountFrom(long snap, Address fromAddress)`
  Count the number of references from the given snapshot and address
  `int`
  `getReferenceCountTo(long snap, Address toAddress)`
  Count the number of references to the given snapshot and address
  `AddressSetView`
  `getReferenceDestinations(Lifespan span)`
  Get an address set of all "to" addresses in any reference intersecting the given lifespan
  `DBTraceReferenceSpace`
  `getReferenceRegisterSpace(TraceStackFrame frame, boolean createIfAbsent)`
  `DBTraceReferenceSpace`
  `getReferenceRegisterSpace(TraceThread thread, boolean createIfAbsent)`
  `protected Collection<? extends DBTraceReference>`
  `getReferencesBySymbolId(long id)`
  `Collection<? extends DBTraceReference>`
  `getReferencesFrom(long snap, Address fromAddress)`
  Find all references from the given snapshot and address
  `Collection<? extends DBTraceReference>`
  `getReferencesFrom(long snap, Address fromAddress, int operandIndex)`
  Find all references from the given snapshot, address, and operand index
  `Collection<? extends DBTraceReference>`
  `getReferencesFromRange(Lifespan span, AddressRange range)`
  Find all references with from addresses contained in the given lifespan and address range
  `AddressSetView`
  `getReferenceSources(Lifespan span)`
  Get an address set of all "from" addresses in any reference intersecting the given lifespan
  `DBTraceReferenceSpace`
  `getReferenceSpace(AddressSpace space, boolean createIfAbsent)`
  `Collection<? extends DBTraceReference>`
  `getReferencesTo(long snap, Address toAddress)`
  Get all references whose to address (or range) contains the given snapshot and address
  `Collection<? extends DBTraceReference>`
  `getReferencesToRange(Lifespan span, AddressRange range, Rectangle2DDirection order)`
  Get all references whose to address range intersects the given lifespan and address range
  `Lock`
  `readLock()`
  `Lock`
  `writeLock()`

  ### Methods inherited from class ghidra.trace.database.space.AbstractDBTraceSpaceBasedManager

  `dbError, get, getActiveSpaces, getBaseLanguage, getForRegisterSpace, getForRegisterSpace, getForRegisterSpace, getLock, getSpaceByName, getTabledSpaces, getTrace, invalidateCache, loadSpaces, tableName`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface ghidra.trace.database.space.DBTraceDelegatingManager

  `delegateAddressSet, delegateAny, delegateCollection, delegateDeleteB, delegateDeleteV, delegateFirst, delegateHashSet, delegateRead, delegateRead, delegateReadB, delegateReadI, delegateReadI, delegateReadOr, delegateWrite, delegateWriteAll, delegateWriteI, delegateWriteV`

  ### Methods inherited from interface ghidra.trace.model.symbol.TraceReferenceOperations

  `addMemoryReference, getReference, getReferencesToRange, hasFlowReferencesFrom, hasReferencesFrom, hasReferencesFrom, hasReferencesTo`

- ## Field Details

  - ### NAME

    public static final String NAME
    See Also:
      - Constant Field Values

  - ### overlayAdapter

    protected final DBTraceOverlaySpaceAdapter overlayAdapter

- ## Constructor Details

  - ### DBTraceReferenceManager

    public DBTraceReferenceManager(DBHandle dbh, OpenMode openMode, ReadWriteLock lock, TaskMonitor monitor, Language baseLanguage, DBTrace trace, DBTraceThreadManager threadManager, DBTraceOverlaySpaceAdapter overlayAdapter) throws VersionException, IOException
    Throws:
      `VersionException`
      `IOException`

- ## Method Details

  - ### createSpace

    protected DBTraceReferenceSpace createSpace(AddressSpace space, AbstractDBTraceSpaceBasedManager.DBTraceSpaceEntry ent) throws VersionException, IOException
    Specified by:
      `createSpace` in class `AbstractDBTraceSpaceBasedManager<DBTraceReferenceSpace>`
    Throws:
      `VersionException`
      `IOException`

  - ### checkIsInMemory

    public void checkIsInMemory(AddressSpace space)
    Ensures that a "from" address is in memory

    NOTE: To manage references from registers, you must use `getReferenceRegisterSpace(TraceThread, boolean)`, which requires a thread.

    Specified by:
      `checkIsInMemory` in interface `DBTraceDelegatingManager<DBTraceReferenceSpace>`
    Parameters:
      `space` - the space of the address to check

  - ### getForSpace

    public DBTraceReferenceSpace getForSpace(AddressSpace space, boolean createIfAbsent)
    Specified by:
      `getForSpace` in interface `DBTraceDelegatingManager<DBTraceReferenceSpace>`
    Overrides:
      `getForSpace` in class `AbstractDBTraceSpaceBasedManager<DBTraceReferenceSpace>`

  - ### readLock

    public Lock readLock()
    Specified by:
      `readLock` in interface `DBTraceDelegatingManager<DBTraceReferenceSpace>`

  - ### writeLock

    public Lock writeLock()
    Specified by:
      `writeLock` in interface `DBTraceDelegatingManager<DBTraceReferenceSpace>`

  - ### doAddXRef

    protected void doAddXRef(DBTraceReferenceSpace.DBTraceReferenceEntry entry)

  - ### doDelXRef

    protected void doDelXRef(DBTraceReferenceSpace.DBTraceReferenceEntry entry)

  - ### doSetXRefLifespan

    protected void doSetXRefLifespan(DBTraceReferenceSpace.DBTraceReferenceEntry entry)

  - ### assertIsMine

    public DBTraceReference assertIsMine(Reference ref)

  - ### getReferenceSpace

    public DBTraceReferenceSpace getReferenceSpace(AddressSpace space, boolean createIfAbsent)
    Specified by:
      `getReferenceSpace` in interface `TraceReferenceManager`

  - ### getReferenceRegisterSpace

    public DBTraceReferenceSpace getReferenceRegisterSpace(TraceThread thread, boolean createIfAbsent)
    Specified by:
      `getReferenceRegisterSpace` in interface `TraceReferenceManager`

  - ### getReferenceRegisterSpace

    public DBTraceReferenceSpace getReferenceRegisterSpace(TraceStackFrame frame, boolean createIfAbsent)
    Specified by:
      `getReferenceRegisterSpace` in interface `TraceReferenceManager`

  - ### addReference

    public DBTraceReference addReference(TraceReference reference)
    Description copied from interface: `TraceReferenceOperations`
    A (a copy of) the given reference to this manager
    Specified by:
      `addReference` in interface `TraceReferenceOperations`
    Parameters:
      `reference` - the reference to add
    Returns:
      the resulting reference

  - ### addReference

    public DBTraceReference addReference(Lifespan lifespan, Reference reference)
    Description copied from interface: `TraceReferenceOperations`
    A (a copy of) the given reference to this manager
    Specified by:
      `addReference` in interface `TraceReferenceOperations`
    Parameters:
      `lifespan` - the span of time where this reference applies
      `reference` - the reference
    Returns:
      the resulting reference

  - ### addMemoryReference

    public DBTraceReference addMemoryReference(Lifespan lifespan, Address fromAddress, AddressRange toRange, RefType refType, SourceType source, int operandIndex)
    Description copied from interface: `TraceReferenceOperations`
    Add a memory reference
    Specified by:
      `addMemoryReference` in interface `TraceReferenceOperations`
    Parameters:
      `lifespan` - the span of time where this reference applies
      `fromAddress` - the from address of the reference
      `toRange` - the to addresses of the reference
      `refType` - the type of reference
      `source` - how this reference was derived
      `operandIndex` - the operand index for the "from" end, or -1
    Returns:
      the resulting reference

  - ### addOffsetReference

    public DBTraceOffsetReference addOffsetReference(Lifespan lifespan, Address fromAddress, Address toAddress, boolean toAddrIsBase, long offset, RefType refType, SourceType source, int operandIndex)
    Description copied from interface: `TraceReferenceOperations`
    Add an offset memory reference
    Specified by:
      `addOffsetReference` in interface `TraceReferenceOperations`
    Parameters:
      `lifespan` - the span of time where this reference applies
      `fromAddress` - the from address of the reference
      `toAddress` - the to address of the reference
      `toAddrIsBase` - indicate whether or not toAddress incorporates the offset. False means toAddress=base+offset. True means toAddress=base.
      `offset` - value added to the base address
      `refType` - the type of reference
      `source` - how this reference was derived
      `operandIndex` - the operand index for the "from" end, or -1
    Returns:
      the resulting reference

  - ### addShiftedReference

    public DBTraceShiftedReference addShiftedReference(Lifespan lifespan, Address fromAddress, Address toAddress, int shift, RefType refType, SourceType source, int operandIndex)
    Description copied from interface: `TraceReferenceOperations`
    Add a shifted memory reference
    Specified by:
      `addShiftedReference` in interface `TraceReferenceOperations`
    Parameters:
      `lifespan` - the span of time where this reference applies
      `fromAddress` - the from address of the reference
      `toAddress` - the to address of the reference
      `shift` - the number of bits to shift left
      `refType` - the type of reference
      `source` - how this reference was derived
      `operandIndex` - the operand index for the "from" end, or -1
    Returns:
      the resulting reference

  - ### addRegisterReference

    public DBTraceReference addRegisterReference(Lifespan lifespan, Address fromAddress, Register toRegister, RefType refType, SourceType source, int operandIndex)
    Description copied from interface: `TraceReferenceOperations`
    Add a register reference
    Specified by:
      `addRegisterReference` in interface `TraceReferenceOperations`
    Parameters:
      `lifespan` - the span of time where this reference applies
      `fromAddress` - the from address of the reference
      `toRegister` - the to register of the reference
      `refType` - the type of reference
      `source` - how this reference was derived
      `operandIndex` - the operand index for the "from" end, or -1
    Returns:
      the resulting reference

  - ### addStackReference

    public DBTraceReference addStackReference(Lifespan lifespan, Address fromAddress, int toStackOffset, RefType refType, SourceType source, int operandIndex)
    Description copied from interface: `TraceReferenceOperations`
    Add a (static) stack reference
    Specified by:
      `addStackReference` in interface `TraceReferenceOperations`
    Parameters:
      `lifespan` - the span of time where this reference applies
      `fromAddress` - the from address of the reference
      `toStackOffset` - the to offset of the reference
      `refType` - the type of reference
      `source` - how this reference was derived
      `operandIndex` - the operand index for the "from" end, or -1
    Returns:
      the resulting reference

  - ### getReference

    public DBTraceReference getReference(long snap, Address fromAddress, AddressRange toRange, int operandIndex)
    Description copied from interface: `TraceReferenceOperations`
    Find the reference that matches the given parameters

    NOTE: It is not sufficient to intersect the to range. It must exactly match that given.

    Specified by:
      `getReference` in interface `TraceReferenceOperations`
    Parameters:
      `snap` - the snapshot key
      `fromAddress` - the from address
      `toRange` - the to address range
      `operandIndex` - the operand index for the "from" end, or -1
    Returns:
      the found reference or null

  - ### getReferencesFrom

    public Collection<? extends DBTraceReference> getReferencesFrom(long snap, Address fromAddress)
    Description copied from interface: `TraceReferenceOperations`
    Find all references from the given snapshot and address
    Specified by:
      `getReferencesFrom` in interface `TraceReferenceOperations`
    Parameters:
      `snap` - the snapshot key
      `fromAddress` - the from address
    Returns:
      the collection of results

  - ### getReferencesFrom

    public Collection<? extends DBTraceReference> getReferencesFrom(long snap, Address fromAddress, int operandIndex)
    Description copied from interface: `TraceReferenceOperations`
    Find all references from the given snapshot, address, and operand index
    Specified by:
      `getReferencesFrom` in interface `TraceReferenceOperations`
    Parameters:
      `snap` - the snapshot key
      `fromAddress` - the from address
      `operandIndex` - the operand index for the "from" end, or -1
    Returns:
      the collection of results

  - ### getReferencesFromRange

    public Collection<? extends DBTraceReference> getReferencesFromRange(Lifespan span, AddressRange range)
    Description copied from interface: `TraceReferenceOperations`
    Find all references with from addresses contained in the given lifespan and address range
    Specified by:
      `getReferencesFromRange` in interface `TraceReferenceOperations`
    Parameters:
      `span` - the lifespan to examine
      `range` - the range to examine
    Returns:
      the collection of results

  - ### getFlowReferencesFrom

    public Collection<? extends DBTraceReference> getFlowReferencesFrom(long snap, Address fromAddress)
    Description copied from interface: `TraceReferenceOperations`
    Get all flow references from the given snapshot and address
    Specified by:
      `getFlowReferencesFrom` in interface `TraceReferenceOperations`
    Parameters:
      `snap` - the snapshot key
      `fromAddress` - the from address
    Returns:
      the collection of results

  - ### getPrimaryReferenceFrom

    public DBTraceReference getPrimaryReferenceFrom(long snap, Address fromAddress, int operandIndex)
    Description copied from interface: `TraceReferenceOperations`
    Get the primary reference matching from the given snapshot, address, and operand index
    Specified by:
      `getPrimaryReferenceFrom` in interface `TraceReferenceOperations`
    Parameters:
      `snap` - the snapshot key
      `fromAddress` - the from address
      `operandIndex` - the operand index for the "from" end, or -1
    Returns:
      the found reference or null

  - ### clearReferencesFrom

    public void clearReferencesFrom(Lifespan span, AddressRange range)
    Description copied from interface: `TraceReferenceOperations`
    Clear all references from the given lifespan and address range

    Any reference intersecting the given "from" parameters will have its lifespan truncated to the start of the given lifespan.

    Specified by:
      `clearReferencesFrom` in interface `TraceReferenceOperations`
    Parameters:
      `span` - the lifespan to remove
      `range` - the range to clear

  - ### getReferencesTo

    public Collection<? extends DBTraceReference> getReferencesTo(long snap, Address toAddress)
    Description copied from interface: `TraceReferenceOperations`
    Get all references whose to address (or range) contains the given snapshot and address
    Specified by:
      `getReferencesTo` in interface `TraceReferenceOperations`
    Parameters:
      `snap` - the snapshot key
      `toAddress` - the to address
    Returns:
      the collection of results

  - ### getReferencesToRange

    public Collection<? extends DBTraceReference> getReferencesToRange(Lifespan span, AddressRange range, Rectangle2DDirection order)
    Description copied from interface: `TraceReferenceOperations`
    Get all references whose to address range intersects the given lifespan and address range

    The following iteration orders may be specified for the resulting (lazy) collection:

    - `null` - no particular order. This spares the cost of sorting.
    - `Rectangle2DDirection.TOPMOST` - most-recent (latest snapshot) first.
    - `Rectangle2DDirection.BOTTOMMOST` - least-recent (earliest including scratch snapshot first).
    - `Rectangle2DDirection.LEFTMOST` - smallest address first.
    - `Rectangle2DDirection.RIGHTMOST` - largest address first.

    "Secondary" sorting is not supported.

    Specified by:
      `getReferencesToRange` in interface `TraceReferenceOperations`
    Parameters:
      `span` - the lifespan to examine
      `range` - the range to examine
      `order` - the order of items in the collection.
    Returns:
      the collection of results

  - ### clearReferencesTo

    public void clearReferencesTo(Lifespan span, AddressRange range)
    Description copied from interface: `TraceReferenceOperations`
    Clear all references to the given lifespan and address range

    Any reference intersecting the given "to" parameters will have its lifespan truncated to the start of the given lifespan.

    Specified by:
      `clearReferencesTo` in interface `TraceReferenceOperations`
    Parameters:
      `span` - the lifespan to remove
      `range` - the range of clear

  - ### getReferenceSources

    public AddressSetView getReferenceSources(Lifespan span)
    Description copied from interface: `TraceReferenceOperations`
    Get an address set of all "from" addresses in any reference intersecting the given lifespan
    Specified by:
      `getReferenceSources` in interface `TraceReferenceOperations`
    Parameters:
      `span` - the lifespan to examine
    Returns:
      a (lazily-computed) address set view of all "from" addresses

  - ### getReferenceDestinations

    public AddressSetView getReferenceDestinations(Lifespan span)
    Description copied from interface: `TraceReferenceOperations`
    Get an address set of all "to" addresses in any reference intersecting the given lifespan
    Specified by:
      `getReferenceDestinations` in interface `TraceReferenceOperations`
    Parameters:
      `span` - the lifespan to examine
    Returns:
      a (lazily-computed) address set view of all "to" addresses

  - ### getReferenceCountFrom

    public int getReferenceCountFrom(long snap, Address fromAddress)
    Description copied from interface: `TraceReferenceOperations`
    Count the number of references from the given snapshot and address
    Specified by:
      `getReferenceCountFrom` in interface `TraceReferenceOperations`
    Parameters:
      `snap` - the snapshot key
      `fromAddress` - the from address
    Returns:
      the number of references

  - ### getReferenceCountTo

    public int getReferenceCountTo(long snap, Address toAddress)
    Description copied from interface: `TraceReferenceOperations`
    Count the number of references to the given snapshot and address
    Specified by:
      `getReferenceCountTo` in interface `TraceReferenceOperations`
    Parameters:
      `snap` - the snapshot key
      `toAddress` - the to address
    Returns:
      the number of references

  - ### getReferencesBySymbolId

    protected Collection<? extends DBTraceReference> getReferencesBySymbolId(long id)