Package ghidra.trace.model.memory

Interface TraceMemoryManager

All Superinterfaces:

TraceMemoryOperations

All Known Implementing Classes:

DBTraceMemoryManager

public interface TraceMemoryManager
extends TraceMemoryOperations

A store of memory observations over time in a trace

The manager is not bound to any particular address space and may be used to access information about any memory address. For register spaces, you must use getMemoryRegisterSpace(TraceThread, int, boolean).

Method Summary

Modifier and Type	Method	Description
default TraceMemoryRegion	addRegion(String path, Lifespan lifespan, AddressRange range, TraceMemoryFlag... flags)
TraceMemoryRegion	addRegion(String path, Lifespan lifespan, AddressRange range, Collection<TraceMemoryFlag> flags)	Add a new region with the given properties
AddressSpace	createOverlayAddressSpace(String name, AddressSpace base)	Create a new address space with the given name based upon the given space
default TraceMemoryRegion	createRegion(String path, long snap, AddressRange range, TraceMemoryFlag... flags)
default TraceMemoryRegion	createRegion(String path, long snap, AddressRange range, Collection<TraceMemoryFlag> flags)	Add a region created at the given snap, with no specified destruction snap
void	deleteOverlayAddressSpace(String name)	Delete an overlay address space
Collection<? extends TraceMemoryRegion>	getAllRegions()	Get all the regions in this space or manager
TraceMemoryRegion	getLiveRegionByPath(long snap, String path)	Get the region with the given path at the given snap
TraceMemorySpace	getMemoryRegisterSpace(TraceStackFrame frame, boolean createIfAbsent)	Obtain a "memory" space bound to the register address space for a stack frame
TraceMemorySpace	getMemoryRegisterSpace(TraceThread thread, boolean createIfAbsent)	Obtain a "memory" space bound to the register address space for frame 0 of a given thread
TraceMemorySpace	getMemoryRegisterSpace(TraceThread thread, int frame, boolean createIfAbsent)	Obtain a "memory" space bound to the register address space for a given thread and stack frame
TraceMemorySpace	getMemorySpace(AddressSpace space, boolean createIfAbsent)	Obtain a memory space bound to a particular address space
AddressSpace	getOrCreateOverlayAddressSpace(String name, AddressSpace base)	Get or create an overlay address space
TraceMemoryRegion	getRegionContaining(long snap, Address address)	Get the region at the given address and snap
AddressSetView	getRegionsAddressSet(long snap)	Get the addresses contained by regions at the given snap
AddressSetView	getRegionsAddressSetWith(long snap, Predicate<TraceMemoryRegion> predicate)	Get the addresses contained by regions at the given snap satisfying the given predicate
Collection<? extends TraceMemoryRegion>	getRegionsAtSnap(long snap)	Collect regions at the given snap
Collection<? extends TraceMemoryRegion>	getRegionsIntersecting(Lifespan lifespan, AddressRange range)	Collect regions intersecting the given lifespan and range
Collection<Map.Entry<TraceAddressSnapRange,TraceMemoryState>>	getStateChanges(long from, long to)	Collect all the state changes between two given snaps

Methods inherited from interface ghidra.trace.model.memory.TraceMemoryOperations

findBytes, getAddressesWithState, getAddressesWithState, getAddressesWithState, getAddressesWithState, getBlockSize, getBufferAt, getBufferAt, getBytes, getBytes, getBytes, getMostRecentStateEntry, getMostRecentStates, getMostRecentStates, getSnapOfMostRecentChangeToBlock, getState, getState, getState, getStates, getStates, getStates, getTrace, getValue, getValue, getViewBytes, getViewMostRecentStateEntry, getViewMostRecentStateEntry, getViewState, getViewValue, getViewValue, isKnown, pack, putBytes, putBytes, putBytes, removeBytes, removeValue, removeValue, setState, setState, setState, setState, setState, setState, setValue, setValue

Method Details

createOverlayAddressSpace

AddressSpace createOverlayAddressSpace(String name,
 AddressSpace base)
                                throws DuplicateNameException

Create a new address space with the given name based upon the given space

The purpose of overlay spaces in traces is often to store bytes for things other than memory or registers. Some targets may expose other byte-based storage, or provide alternative views of memory.

NOTE: This also provides a transitional piece for recording a model (sub)tree directly into a trace, without mapping to a Ghidra language first. As we experiment with that mode, we will likely instantiate traces with the "DATA:BE:64:default" language and generate an overlay space named after the path of each memory being recorded. Of course, the mapping still needs to occur between the trace and parts of the display and during emulation.

NOTE: We are also moving away from (space, thread, frame) triples to uniquely identify register storage. Instead, that will be encoded into the address space itself. Register overlays will overlay register space and be named after the register container object, which subsumes thread and frame when applicable.

Parameters:

name - the name of the new address space

base - the space after which this is modeled

Returns:

the create space

Throws:

DuplicateNameException - if an address space with the name already exists

getOrCreateOverlayAddressSpace

AddressSpace getOrCreateOverlayAddressSpace(String name,
 AddressSpace base)

Get or create an overlay address space

If the space already exists, and it overlays the given base, the existing space is returned. If it overlays a different space, null is returned. If the space does not exist, it is created with the given base space.

Parameters:

name - the name of the address space

base - the expected base space

Returns:

the space, or null

See Also:

• createOverlayAddressSpace(String, AddressSpace)

deleteOverlayAddressSpace

void deleteOverlayAddressSpace(String name)

Delete an overlay address space

TODO: At the moment, this will not destroy manager spaces created for the deleted address space. We should assess this behavior, esp. wrt. re-creating the address space later, and decide whether or not to clean up.

Parameters:

name - the name of the address space to delete

addRegion

TraceMemoryRegion addRegion(String path,
 Lifespan lifespan,
 AddressRange range,
 Collection<TraceMemoryFlag> flags)
                     throws TraceOverlappedRegionException

Add a new region with the given properties

Regions model the memory mappings of a debugging target. As such, they are never allowed to overlap. Additionally, to ensure getLiveRegionByPath(long, String) returns a unique region, duplicate paths cannot exist in the same snap.

Regions have a "full name" (path) as well as a short name. The path is immutable and can be used to reliably retrieve the same region later. The short name should be something suitable for display on the screen. Short names are mutable and can be -- but probbaly shouldn't be -- duplicated.

Parameters:

path - the "full name" of the region

lifespan - the lifespan of the region

range - the address range of the region

flags - the flags, e.g., permissions, of the region

Returns:

the newly-added region

Throws:

TraceOverlappedRegionException - if the specified region would overlap an existing one

addRegion

default TraceMemoryRegion addRegion(String path,
 Lifespan lifespan,
 AddressRange range,
 TraceMemoryFlag... flags)
                             throws TraceOverlappedRegionException

Throws:

TraceOverlappedRegionException

See Also:

• addRegion(String, Lifespan, AddressRange, Collection)

createRegion

default TraceMemoryRegion createRegion(String path,
 long snap,
 AddressRange range,
 Collection<TraceMemoryFlag> flags)
                                throws TraceOverlappedRegionException,
DuplicateNameException

Add a region created at the given snap, with no specified destruction snap

Throws:

TraceOverlappedRegionException

DuplicateNameException

See Also:

• addRegion(String, Lifespan, AddressRange, Collection)

createRegion

default TraceMemoryRegion createRegion(String path,
 long snap,
 AddressRange range,
 TraceMemoryFlag... flags)
                                throws TraceOverlappedRegionException,
DuplicateNameException

Throws:

TraceOverlappedRegionException

DuplicateNameException

See Also:

• createRegion(String, long, AddressRange, Collection)

getAllRegions

Collection<? extends TraceMemoryRegion> getAllRegions()

Get all the regions in this space or manager

Returns:

the collection of all regions

getLiveRegionByPath

TraceMemoryRegion getLiveRegionByPath(long snap,
 String path)

Get the region with the given path at the given snap

Parameters:

snap - the snap which must be within the region's lifespan

path - the "full name" of the region

Returns:

the region, or null if no region matches

getRegionContaining

TraceMemoryRegion getRegionContaining(long snap,
 Address address)

Get the region at the given address and snap

Parameters:

snap - the snap which must be within the region's lifespan

address - the address which must be within the region's range

Returns:

the region, or null if no region matches

getRegionsIntersecting

Collection<? extends TraceMemoryRegion> getRegionsIntersecting(Lifespan lifespan,
 AddressRange range)

Collect regions intersecting the given lifespan and range

Parameters:

lifespan - the lifespan

range - the range

Returns:

the collection of matching regions

getRegionsAtSnap

Collection<? extends TraceMemoryRegion> getRegionsAtSnap(long snap)

Collect regions at the given snap

Parameters:

snap - the snap which must be within the regions' lifespans

Returns:

the collection of matching regions

getRegionsAddressSet

AddressSetView getRegionsAddressSet(long snap)

Get the addresses contained by regions at the given snap

The implementation may provide a view that updates with changes.

Parameters:

snap - the snap which must be within the regions' lifespans

Returns:

the union of ranges of matching regions

getRegionsAddressSetWith

AddressSetView getRegionsAddressSetWith(long snap,
 Predicate<TraceMemoryRegion> predicate)

Get the addresses contained by regions at the given snap satisfying the given predicate

The implementation may provide a view that updates with changes.

Parameters:

snap - the snap which must be within the region's lifespans

predicate - a predicate on regions to search for

Returns:

the address set

getMemorySpace

TraceMemorySpace getMemorySpace(AddressSpace space,
 boolean createIfAbsent)

Obtain a memory space bound to a particular address space

Parameters:

space - the address space

createIfAbsent - true to create the space if it's not already present

Returns:

the space, or null if absent and not created

getMemoryRegisterSpace

TraceMemorySpace getMemoryRegisterSpace(TraceThread thread,
 int frame,
 boolean createIfAbsent)

Obtain a "memory" space bound to the register address space for a given thread and stack frame

Parameters:

thread - the given thread

frame - the "level" of the given stack frame. 0 is the innermost frame.

createIfAbsent - true to create the space if it's not already present

Returns:

the space, or null if absent and not created

getMemoryRegisterSpace

TraceMemorySpace getMemoryRegisterSpace(TraceThread thread,
 boolean createIfAbsent)

Obtain a "memory" space bound to the register address space for frame 0 of a given thread

Parameters:

thread - the given thread

createIfAbsent - true to create the space if it's not already present

Returns:

the space, or null if absent and not created

See Also:

• getMemoryRegisterSpace(TraceThread, int, boolean)

getMemoryRegisterSpace

TraceMemorySpace getMemoryRegisterSpace(TraceStackFrame frame,
 boolean createIfAbsent)

Obtain a "memory" space bound to the register address space for a stack frame

Note this is simply a convenience, and does not in any way bind the space to the lifespan of the given frame. Nor, if the frame is moved, will this space move with it.

Parameters:

frame - the stack frame

createIfAbsent - true to create the space if it's not already present

Returns:

the space, or null if absent and not created

See Also:

• getMemoryRegisterSpace(TraceThread, int, boolean)

getStateChanges

Collection<Map.Entry<TraceAddressSnapRange,TraceMemoryState>> getStateChanges(long from,
 long to)

Collect all the state changes between two given snaps

Parameters:

from - the earlier snap

to - the later snap

Returns:

the collection of state changes