ContextDatabase Class Reference

An interface to a database of disassembly/decompiler context information. More...

#include <globalcontext.hh>

Inheritance diagram for ContextDatabase:

Public Member Functions
virtual	~ContextDatabase ()
	Destructor.
virtual int4	getContextSize (void) const =0
	Retrieve the number of words (uintm) in a context blob. More...
virtual void	registerVariable (const string &nm, int4 sbit, int4 ebit)=0
	Register a new named context variable (as a bit range) with the database. More...
virtual const uintm *	getContext (const Address &addr) const =0
	Get the context blob of values associated with a given address. More...
virtual const uintm *	getContext (const Address &addr, uintb &first, uintb &last) const =0
	Get the context blob of values associated with a given address and its bounding offsets. More...
virtual TrackedSet &	getTrackedDefault (void)=0
	Get the set of default values for all tracked registers. More...
virtual const TrackedSet &	getTrackedSet (const Address &addr) const =0
	Get the set of tracked register values associated with the given address. More...
virtual TrackedSet &	createSet (const Address &addr1, const Address &addr2)=0
	Create a tracked register set that is valid over the given range. More...
virtual void	saveXml (ostream &s) const =0
	Serialize the entire database to an XML stream. More...
virtual void	restoreXml (const Element *el, const AddrSpaceManager *manage)=0
	Restore the state of this database object from a serialized XML stream. More...
virtual void	restoreFromSpec (const Element *el, const AddrSpaceManager *manage)=0
	Add initial context state from XML tags in compiler/processor specifications. More...
void	setVariableDefault (const string &nm, uintm val)
	Provide a default value for a context variable. More...
uintm	getDefaultValue (const string &nm) const
	Retrieve the default value for a context variable. More...
void	setVariable (const string &nm, const Address &addr, uintm value)
	Set a context value at the given address. More...
uintm	getVariable (const string &nm, const Address &addr) const
	Retrieve a context value at the given address. More...
void	setContextChangePoint (const Address &addr, int4 num, uintm mask, uintm value)
	Set a specific context value starting at the given address. More...
void	setContextRegion (const Address &addr1, const Address &addr2, int4 num, uintm mask, uintm value)
	Set a context variable value over a given range of addresses. More...
void	setVariableRegion (const string &nm, const Address &begad, const Address &endad, uintm value)
	Set a context variable by name over a given range of addresses. More...
uintb	getTrackedValue (const VarnodeData &mem, const Address &point) const
	Get the value of a tracked register at a specific address. More...

Protected Member Functions
virtual ContextBitRange &	getVariable (const string &nm)=0
	Retrieve the context variable description object by name. More...
virtual const ContextBitRange &	getVariable (const string &nm) const =0
	Retrieve the context variable description object by name. More...
virtual void	getRegionForSet (vector< uintm *> &res, const Address &addr1, const Address &addr2, int4 num, uintm mask)=0
	Grab the context blob(s) for the given address range, marking bits that will be set. More...
virtual void	getRegionToChangePoint (vector< uintm *> &res, const Address &addr, int4 num, uintm mask)=0
	Grab the context blob(s) starting at the given address up to the first point of change. More...
virtual uintm *	getDefaultValue (void)=0
	Retrieve the memory region holding all default context values. More...
virtual const uintm *	getDefaultValue (void) const =0
	Retrieve the memory region holding all default context values. More...

Static Protected Member Functions
static void	saveTracked (ostream &s, const Address &addr, const TrackedSet &vec)
	Save all tracked register values for a specific address to an XML stream. More...
static void	restoreTracked (const Element *el, const AddrSpaceManager *manage, TrackedSet &vec)
	Restore a sequence of tracked register values from an XML stream. More...

Detailed Description

An interface to a database of disassembly/decompiler context information.

Context information is a set of named variables that hold concrete values at specific addresses in the target executable being analyzed. A variable can hold different values at different addresses, but a specific value at a specific address never changes. Analysis recovers these values over time, populating this database, and querying this database lets analysis provides concrete values for memory locations in context.

Context variables come in two flavors:

• Low-level context variables: These can affect instruction decoding. These can be as small as a single bit and need to be defined in the Sleigh specification (so that Sleigh knows how they effect disassembly). These variables are not mapped to normal memory locations with an address space and offset (although they often have a corresponding embedding into a normal memory location). The model to keep in mind is a control register with specialized bit-fields within it.
• High-level tracked variables: These are normal memory locations that are to be treated as constants across some range of code. These are normally registers that are being tracked by the compiler outside the domain of normal local and global variables. They have a specific value established by the compiler coming into a function but are not supposed to be interpreted as a high-level variable. Typical examples are the direction flag (for string instructions) and segment registers. All tracked variables are interpreted as a constant value at the start of a function, although the memory location can be recycled for other calculations later in the function.

Low-level context variables can be queried and set by name – getVariable(), setVariable(), setVariableRegion() – but the disassembler accesses all the variables at an address as a group via getContext(), setContextChangePoint(), setContextRegion(). In this setting, all the values are packed together in an array of words, a context blob (See ContextBitRange).

Tracked variables are also queried as a group via getTrackedSet() and createSet(). These return a list of TrackedContext objects.

Member Function Documentation

createSet()

virtual TrackedSet& ContextDatabase::createSet ( const Address &  addr1, const Address &  addr2  )

pure virtual

Create a tracked register set that is valid over the given range.

This really should be an internal routine. The created set is empty, old values are blown away. If old/default values are to be preserved, they must be copied back in.

Parameters

addr1	is the starting address of the given range
addr2	is (1 past) the ending address of the given range

Returns

the empty set of tracked register values

Implemented in ContextInternal, and ContextGhidra.

getContext() [1/2]

virtual const uintm* ContextDatabase::getContext ( const Address &  addr ) const

pure virtual

Get the context blob of values associated with a given address.

Parameters

addr	is the given address

Returns

the memory region holding the context values for the address

Implemented in ContextInternal, and ContextGhidra.

getContext() [2/2]

virtual const uintm* ContextDatabase::getContext ( const Address &  addr, uintb &  first, uintb &  last  ) const

pure virtual

Get the context blob of values associated with a given address and its bounding offsets.

In addition to the memory region, the range of addresses for which the region is valid is passed back as offsets into the address space.

Parameters

addr	is the given address
first	will hold the starting offset of the valid range
last	will hold the ending offset of the valid range

Returns

the memory region holding the context values for the address

Implemented in ContextInternal, and ContextGhidra.

getContextSize()

virtual int4 ContextDatabase::getContextSize ( void  ) const

pure virtual

Retrieve the number of words (uintm) in a context blob.

Returns

the number of words

Implemented in ContextInternal, and ContextGhidra.

getDefaultValue() [1/3]

virtual uintm* ContextDatabase::getDefaultValue ( void  )

protectedpure virtual

Retrieve the memory region holding all default context values.

This fetches the active memory holding the default context values on top of which all other context values are overlaid.

Returns

the memory region holding all the default context values

getDefaultValue() [2/3]

virtual const uintm* ContextDatabase::getDefaultValue ( void  ) const

protectedpure virtual

Retrieve the memory region holding all default context values.

This fetches the active memory holding the default context values on top of which all other context values are overlaid.

Returns

the memory region holding all the default context values

getDefaultValue() [3/3]

uintm ContextDatabase::getDefaultValue

(

const string &

nm

)

const

Retrieve the default value for a context variable.

This will return the default value used for addresses that have not been overlaid with other values.

Parameters

nm	is the name of the context variable

Returns

the variable's default value

getRegionForSet()

virtual void ContextDatabase::getRegionForSet ( vector< uintm *> &  res, const Address &  addr1, const Address &  addr2, int4  num, uintm  mask  )

protectedpure virtual

Grab the context blob(s) for the given address range, marking bits that will be set.

This is an internal routine for obtaining the actual memory regions holding context values for the address range. This also informs the system which bits are getting set. A split is forced at the first address, and at least one memory region is passed back. The second address can be invalid in which case the memory region passed back is valid from the first address to whatever the next split point is.

Parameters

res	will hold pointers to memory regions for the given range
addr1	is the starting address of the range
addr2	is (1 past) the last address of the range or is invalid
num	is the word index for the context value that will be set
mask	is a mask of the value being set (within its word)

getRegionToChangePoint()

virtual void ContextDatabase::getRegionToChangePoint ( vector< uintm *> &  res, const Address &  addr, int4  num, uintm  mask  )

protectedpure virtual

Grab the context blob(s) starting at the given address up to the first point of change.

This is an internal routine for obtaining the actual memory regions holding context values starting at the given address. A specific context value is specified, and all memory regions are returned up to the first address where that particular context value changes.

Parameters

res	will hold pointers to memory regions being passed back
addr	is the starting address of the regions to fetch
num	is the word index for the specific context value being set
mask	is a mask of the context value being set (within its word)

getTrackedDefault()

virtual TrackedSet& ContextDatabase::getTrackedDefault ( void  )

pure virtual

Get the set of default values for all tracked registers.

Returns

the list of TrackedContext objects

Implemented in ContextInternal, and ContextGhidra.

getTrackedSet()

virtual const TrackedSet& ContextDatabase::getTrackedSet ( const Address &  addr ) const

pure virtual

Get the set of tracked register values associated with the given address.

Parameters

addr	is the given address

Returns

the list of TrackedContext objects

Implemented in ContextInternal, and ContextGhidra.

getTrackedValue()

uintb ContextDatabase::getTrackedValue	(	const VarnodeData &	mem,
		const Address &	point
	)		const

Get the value of a tracked register at a specific address.

A specific storage region and code address is given. If the region is tracked the value at the address is retrieved. If the specified storage region is contained in the tracked region, the retrieved value is trimmed to match the containment before returning it. If the region is not tracked, a value of 0 is returned.

Parameters

mem	is the specified storage region
point	is the code address

Returns

the tracked value or zero

getVariable() [1/3]

virtual ContextBitRange& ContextDatabase::getVariable ( const string &  nm )

protectedpure virtual

Retrieve the context variable description object by name.

If the variable doesn't exist an exception is thrown.

Parameters

nm	is the name of the context value

Returns

the ContextBitRange object matching the name

getVariable() [2/3]

virtual const ContextBitRange& ContextDatabase::getVariable ( const string &  nm ) const

protectedpure virtual

Retrieve the context variable description object by name.

If the variable doesn't exist an exception is thrown.

Parameters

nm	is the name of the context value

Returns

the ContextBitRange object matching the name

getVariable() [3/3]

uintm ContextDatabase::getVariable	(	const string &	nm,
		const Address &	addr
	)		const

Retrieve a context value at the given address.

If a value has not been explicit set for an address range containing the given address, the default value for the variable is returned

Parameters

nm	is the name of the context variable
addr	is the address for which the specific value is needed

Returns

the context variable value for the address

registerVariable()

virtual void ContextDatabase::registerVariable ( const string &  nm, int4  sbit, int4  ebit  )

pure virtual

Register a new named context variable (as a bit range) with the database.

A new variable is registered by providing a name and the range of bits the value will occupy within the context blob. The full blob size is automatically increased if necessary. The variable must be contained within a single word, and all variables must be registered before any values can be set.

Parameters

nm	is the name of the new variable
sbit	is the position of the variable's most significant bit within the blob
ebit	is the position of the variable's least significant bit within the blob

Implemented in ContextInternal, and ContextGhidra.

restoreFromSpec()

virtual void ContextDatabase::restoreFromSpec ( const Element *  el, const AddrSpaceManager *  manage  )

pure virtual

Add initial context state from XML tags in compiler/processor specifications.

The database can be configured with a consistent initial state by providing <context_data> tags in either the compiler or processor specification file for the architecture

Parameters

el	is a <context_data> tag
manage	is used to resolve address space references

Implemented in ContextInternal, and ContextGhidra.

restoreTracked()

void ContextDatabase::restoreTracked ( const Element *  el, const AddrSpaceManager *  manage, TrackedSet &  vec  )

staticprotected

Restore a sequence of tracked register values from an XML stream.

Given a root <tracked_pointset> tag, decode each child in turn populating a list of TrackedContext objects.

Parameters

el	is the root tag
manage	is used to resolve address space references
vec	is the container that will hold the new TrackedContext objects

restoreXml()

virtual void ContextDatabase::restoreXml ( const Element *  el, const AddrSpaceManager *  manage  )

pure virtual

Restore the state of this database object from a serialized XML stream.

Parameters

el	is the root element of the XML describing the database state
manage	is used to resolve address space references

Implemented in ContextInternal, and ContextGhidra.

saveTracked()

void ContextDatabase::saveTracked ( ostream &  s, const Address &  addr, const TrackedSet &  vec  )

staticprotected

Save all tracked register values for a specific address to an XML stream.

Encode all the tracked register values associated with a specific target address as a <tracked_pointset> tag.

Parameters

s	is the output stream
addr	is the specific address we have tracked values for
vec	is the list of tracked values

saveXml()

virtual void ContextDatabase::saveXml ( ostream &  s ) const

pure virtual

Serialize the entire database to an XML stream.

Parameters

s	is the output stream

Implemented in ContextInternal, and ContextGhidra.

setContextChangePoint()

void ContextDatabase::setContextChangePoint	(	const Address &	addr,
		int4	num,
		uintm	mask,
		uintm	value
	)

Set a specific context value starting at the given address.

The new value is painted across an address range starting, starting with the given address up to the point where another change for the variable was specified. No other context variable is changed, inside (or outside) the range.

Parameters

addr	is the given starting address
num	is the index of the word (within the context blob) of the context variable
mask	is the mask delimiting the context variable (within its word)
value	is the (already shifted) value being set

setContextRegion()

void ContextDatabase::setContextRegion	(	const Address &	addr1,
		const Address &	addr2,
		int4	num,
		uintm	mask,
		uintm	value
	)

Set a context variable value over a given range of addresses.

The new value is painted over an explicit range of addresses. No other context variable is changed inside (or outside) the range.

Parameters

addr1	is the starting address of the given range
addr2	is the ending address of the given range
num	is the index of the word (within the context blob) of the context variable
mask	is the mask delimiting the context variable (within its word)
value	is the (already shifted) value being set

setVariable()

void ContextDatabase::setVariable	(	const string &	nm,
		const Address &	addr,
		uintm	value
	)

Set a context value at the given address.

The variable will be changed to the new value, starting at the given address up to the next point of change.

Parameters

nm	is the name of the context variable
addr	is the given address
value	is the new value to set

setVariableDefault()

void ContextDatabase::setVariableDefault	(	const string &	nm,
		uintm	val
	)

Provide a default value for a context variable.

The default value is returned for addresses that have not been overlaid with other values.

Parameters

nm	is the name of the context variable
val	is the default value to establish

setVariableRegion()

void ContextDatabase::setVariableRegion	(	const string &	nm,
		const Address &	begad,
		const Address &	endad,
		uintm	value
	)

Set a context variable by name over a given range of addresses.

The new value is painted over an explicit range of addresses. No other context variable is changed inside (or outside) the range.

Parameters

nm	is the name of the context variable to set
begad	is the starting address of the given range
endad	is the ending address of the given range
value	is the new value to set

---

The documentation for this class was generated from the following files:

• globalcontext.hh
• globalcontext.cc