A collection of Symbol objects within a single (namespace or functional) scope. More...

#include <database.hh>

Inheritance diagram for Scope:

Public Member Functions
	Scope (uint8 id, const string &nm, Architecture g, Scope own)
	Construct an empty scope, given a name and Architecture.

virtual	~Scope (void)
	Destructor.

virtual MapIterator	begin (void) const =0
	Beginning iterator to mapped SymbolEntrys.

virtual MapIterator	end (void) const =0
	Ending iterator to mapped SymbolEntrys.

virtual list< SymbolEntry >::const_iterator	beginDynamic (void) const =0
	Beginning iterator to dynamic SymbolEntrys.

virtual list< SymbolEntry >::const_iterator	endDynamic (void) const =0
	Ending iterator to dynamic SymbolEntrys.

virtual list< SymbolEntry >::iterator	beginDynamic (void)=0
	Beginning iterator to dynamic SymbolEntrys.

virtual list< SymbolEntry >::iterator	endDynamic (void)=0
	Ending iterator to dynamic SymbolEntrys.

virtual void	clear (void)=0
	Clear all symbols from this scope.

virtual void	clearCategory (int4 cat)=0
	Clear all symbols of the given category from this scope.

virtual void	clearUnlocked (void)=0
	Clear all unlocked symbols from this scope.

virtual void	clearUnlockedCategory (int4 cat)=0
	Clear unlocked symbols of the given category from this scope.

virtual void	adjustCaches (void)=0
	Let scopes internally adjust any caches. More...

virtual bool	inScope (const Address &addr, int4 size, const Address &usepoint) const
	Query if the given range is owned by this Scope. More...

virtual void	removeSymbolMappings (Symbol *symbol)=0
	Remove all SymbolEntrys from the given Symbol.

virtual void	removeSymbol (Symbol *symbol)=0
	Remove the given Symbol from this Scope.

virtual void	renameSymbol (Symbol *sym, const string &newname)=0
	Rename a Symbol within this Scope.

virtual void	retypeSymbol (Symbol sym, Datatype ct)=0
	Change the data-type of a Symbol within this Scope. More...

virtual void	setAttribute (Symbol *sym, uint4 attr)=0
	Set boolean Varnode properties on a Symbol.

virtual void	clearAttribute (Symbol *sym, uint4 attr)=0
	Clear boolean Varnode properties on a Symbol.

virtual void	setDisplayFormat (Symbol *sym, uint4 attr)=0
	Set the display format for a Symbol.

virtual SymbolEntry *	findAddr (const Address &addr, const Address &usepoint) const =0
	Find a Symbol at a given address and usepoint. More...

virtual SymbolEntry *	findContainer (const Address &addr, int4 size, const Address &usepoint) const =0
	Find the smallest Symbol containing the given memory range. More...

virtual SymbolEntry *	findClosestFit (const Address &addr, int4 size, const Address &usepoint) const =0
	Find Symbol which is the closest fit to the given memory range. More...

virtual Funcdata *	findFunction (const Address &addr) const =0
	Find the function starting at the given address. More...

virtual ExternRefSymbol *	findExternalRef (const Address &addr) const =0
	Find an external reference at the given address. More...

virtual LabSymbol *	findCodeLabel (const Address &addr) const =0
	Find a label Symbol at the given address. More...

virtual SymbolEntry *	findOverlap (const Address &addr, int4 size) const =0
	Find first Symbol overlapping the given memory range. More...

virtual void	findByName (const string &name, vector< Symbol * > &res) const =0
	Find a Symbol by name within this Scope. More...

virtual bool	isNameUsed (const string &nm, const Scope *op2) const =0
	Check if the given name is occurs within the given scope path. More...

virtual Funcdata *	resolveExternalRefFunction (ExternRefSymbol *sym) const =0
	Convert an external reference to the referenced function. More...

virtual string	buildVariableName (const Address &addr, const Address &pc, Datatype *ct, int4 &index, uint4 flags) const =0
	Given an address and data-type, build a suitable generic symbol name. More...

virtual string	buildUndefinedName (void) const =0
	Build a formal undefined name, used internally when a Symbol is not given a name. More...

virtual string	makeNameUnique (const string &nm) const =0
	Produce a version of the given symbol name that won't collide with other names in this Scope. More...

virtual void	saveXml (ostream &s) const =0
	Write out this as a <scope> XML tag.

virtual void	restoreXml (const Element *el)=0
	Restore this Scope from a <scope> XML tag.

virtual void	printEntries (ostream &s) const =0
	Dump a description of all SymbolEntry objects to a stream.

virtual int4	getCategorySize (int4 cat) const =0
	Get the number of Symbols in the given category. More...

virtual Symbol *	getCategorySymbol (int4 cat, int4 ind) const =0
	Retrieve a Symbol by index within a specific category. More...

virtual void	setCategory (Symbol *sym, int4 cat, int4 ind)=0
	Set the category and index for the given Symbol. More...

virtual SymbolEntry *	addSymbol (const string &name, Datatype *ct, const Address &addr, const Address &usepoint)
	Add a new Symbol to this Scope, given a name, data-type, and a single mapping. More...

const string &	getName (void) const
	Get the name of the Scope.

uint8	getId (void) const
	Get the globally unique id.

bool	isGlobal (void) const
	Return true if this scope is global.

void	queryByName (const string &name, vector< Symbol * > &res) const
	Look-up symbols by name. More...

Funcdata *	queryFunction (const string &name) const
	Look-up a function by name. More...

SymbolEntry *	queryByAddr (const Address &addr, const Address &usepoint) const
	Get Symbol with matching address. More...

SymbolEntry *	queryContainer (const Address &addr, int4 size, const Address &usepoint) const
	Find the smallest containing Symbol. More...

SymbolEntry *	queryProperties (const Address &addr, int4 size, const Address &usepoint, uint4 &flags) const
	Find a Symbol or properties at the given address. More...

Funcdata *	queryFunction (const Address &addr) const
	Look-up a function by address. More...

Funcdata *	queryExternalRefFunction (const Address &addr) const
	Look-up a function thru an external reference. More...

LabSymbol *	queryCodeLabel (const Address &addr) const
	Look-up a code label by address. More...

Scope *	resolveScope (const string &name, bool strategy) const
	Find a child Scope of this. More...

Scope *	discoverScope (const Address &addr, int4 sz, const Address &usepoint)
	Find the owning Scope of a given memory range. More...

ScopeMap::const_iterator	childrenBegin () const
	Beginning iterator of child scopes.

ScopeMap::const_iterator	childrenEnd () const
	Ending iterator of child scopes.

void	saveXmlRecursive (ostream &s, bool onlyGlobal) const
	Save all contained scopes as an XML stream. More...

void	overrideSizeLockType (Symbol sym, Datatype ct)
	Change the data-type of a Symbol that is sizelocked. More...

void	resetSizeLockType (Symbol *sym)
	Clear a Symbol's size-locked data-type. More...

void	setThisPointer (Symbol *sym, bool val)
	Toggle the given Symbol as the "this" pointer.

bool	isSubScope (const Scope *scp) const
	Is this a sub-scope of the given Scope. More...

string	getFullName (void) const
	Get the full name of this Scope.

void	getScopePath (vector< const Scope * > &vec) const
	Get the ordered list of scopes up to this. More...

const Scope *	findDistinguishingScope (const Scope *op2) const
	Find first ancestor of this not shared by given scope. More...

Architecture *	getArch (void) const
	Get the Architecture associated with this.

Scope *	getParent (void) const
	Get the parent Scope (or NULL if this is the global Scope)

Symbol *	addSymbol (const string &name, Datatype *ct)
	Add a new Symbol without mapping it to an address. More...

SymbolEntry *	addMapPoint (Symbol *sym, const Address &addr, const Address &usepoint)
	Map a Symbol to a specific address. More...

Symbol *	addMapSym (const Element *el)
	Add a mapped Symbol from a <mapsym> XML tag. More...

FunctionSymbol *	addFunction (const Address &addr, const string &nm)
	Create a function Symbol at the given address in this Scope. More...

ExternRefSymbol *	addExternalRef (const Address &addr, const Address &refaddr, const string &nm)

LabSymbol *	addCodeLabel (const Address &addr, const string &nm)
	Create a code label at the given address in this Scope. More...

Symbol *	addDynamicSymbol (const string &nm, Datatype *ct, const Address &caddr, uint8 hash)
	Create a dynamically mapped Symbol attached to a specific data-flow. More...

string	buildDefaultName (Symbol sym, int4 &base, Varnode vn) const
	Create a default name for the given Symbol. More...

bool	isReadOnly (const Address &addr, int4 size, const Address &usepoint) const
	Is the given memory range marked as read-only. More...

void	printBounds (ostream &s) const
	Print a description of this Scope's owned memory ranges.

Protected Member Functions
const RangeList &	getRangeTree (void) const
	Access the address ranges owned by this Scope.

virtual Scope *	buildSubScope (uint8 id, const string &nm)=0
	Build an unattached Scope to be associated as a sub-scope of this. More...

virtual void	restrictScope (Funcdata *f)
	Convert this to a local Scope. More...

virtual void	addRange (AddrSpace *spc, uintb first, uintb last)
	Add a memory range to the ownership of this Scope. More...

virtual void	removeRange (AddrSpace *spc, uintb first, uintb last)
	Remove a memory range from the ownership of this Scope. More...

virtual void	addSymbolInternal (Symbol *sym)=0
	Put a Symbol into the name map. More...

virtual SymbolEntry *	addMapInternal (Symbol *sym, uint4 exfl, const Address &addr, int4 off, int4 sz, const RangeList &uselim)=0
	Create a new SymbolEntry for a Symbol given a memory range. More...

virtual SymbolEntry *	addDynamicMapInternal (Symbol *sym, uint4 exfl, uint8 hash, int4 off, int4 sz, const RangeList &uselim)=0
	Create a new SymbolEntry for a Symbol given a dynamic hash. More...

SymbolEntry *	addMap (SymbolEntry &entry)
	Integrate a SymbolEntry into the range maps. More...

void	setSymbolId (Symbol *sym, uint8 id) const
	Adjust the id associated with a symbol.

Static Protected Member Functions
static const Scope *	stackAddr (const Scope scope1, const Scope scope2, const Address &addr, const Address &usepoint, SymbolEntry **addrmatch)
	Query for Symbols starting at a given address, which match a given usepoint. More...

static const Scope *	stackContainer (const Scope scope1, const Scope scope2, const Address &addr, int4 size, const Address &usepoint, SymbolEntry **addrmatch)

static const Scope *	stackClosestFit (const Scope scope1, const Scope scope2, const Address &addr, int4 size, const Address &usepoint, SymbolEntry **addrmatch)

static const Scope *	stackFunction (const Scope scope1, const Scope scope2, const Address &addr, Funcdata **addrmatch)

static const Scope *	stackExternalRef (const Scope scope1, const Scope scope2, const Address &addr, ExternRefSymbol **addrmatch)

static const Scope *	stackCodeLabel (const Scope scope1, const Scope scope2, const Address &addr, LabSymbol **addrmatch)

Protected Attributes
Architecture *	glb
	Architecture of this scope.

string	name
	Name of this scope.

Funcdata *	fd
	(If non-null) the function which this is the local Scope for

uint8	uniqueId
	Unique id for the scope, for deduping scope names, assigning symbol ids.

Private Member Functions
void	attachScope (Scope *child)
	Attach a new child Scope to this. More...

void	detachScope (ScopeMap::iterator iter)
	Detach a child Scope from this. More...

Static Private Member Functions
static uint8	hashScopeName (uint8 baseId, const string &nm)
	Create a Scope id based on the scope's name and its parent's id. More...

Private Attributes
RangeList	rangetree
	Range of data addresses owned by this scope.

Scope *	parent
	The parent scope.

Scope *	owner
	Scope using this as a cache.

ScopeMap	children
	Sorted list of child scopes.

Friends
class	Database

class	ScopeCompare

Detailed Description

A collection of Symbol objects within a single (namespace or functional) scope.

This acts as a traditional Symbol container, allowing them to be accessed by name, but it also keeps track of how a Symbol is mapped into memory. It allows a Symbol to be looked up by its location in memory, which is sensitive to the address of the code accessing the Symbol.

Capabilities include:

Search for Symbols
- By name
- By storage address
- By type of Symbol
- Containing a range
- Overlapping a range
Insert or remove a Symbol
Add or remove SymbolEntry objects which associate Symbols with storage and the code that accesses it
Modify properties of a Symbol

A scope also supports the idea of ownership of memory. In theory, for a Symbol in the scope, at the code locations where the Symbol storage is valid, the scope owns the storage memory. In practice, a Scope object knows about memory ranges where a Symbol might be discovered. For instance, the global Scope usually owns all memory in the ram address space.

Member Function Documentation

LabSymbol * Scope::addCodeLabel	(	const Address &	addr,
		const string &	nm
	)

Create a code label at the given address in this Scope.

A LabSymbol is created and mapped to the given address.

Parameters

addr	is the given address to map to
nm	is the name of the symbol/label

Returns: the new LabSymbol

References Symbol::getName(), and SymbolEntry::getSymbol().

Referenced by ScopeGhidra::findCodeLabel().

virtual SymbolEntry* Scope::addDynamicMapInternal	(	Symbol *	sym,
		uint4	exfl,
		uint8	hash,
		int4	off,
		int4	sz,
		const RangeList &	uselim
	)

protectedpure virtual

Create a new SymbolEntry for a Symbol given a dynamic hash.

The SymbolEntry is specified in terms of a hash and usepoint, which describe how to find the temporary Varnode holding the symbol value.

Parameters

sym	is the given Symbol being mapped
exfl	are any boolean Varnode properties
hash	is the given dynamic hash
off	is the byte offset of the new SymbolEntry (relative to the whole Symbol)
sz	is the number of bytes occupied by the Varnode
uselim	is the given usepoint

Returns: the newly created SymbolEntry

Implemented in ScopeInternal, and ScopeGhidra.

Symbol * Scope::addDynamicSymbol	(	const string &	nm,
		Datatype *	ct,
		const Address &	caddr,
		uint8	hash
	)

Create a dynamically mapped Symbol attached to a specific data-flow.

The Symbol is created and mapped to a dynamic hash and a code address where the Symbol is being used.

Parameters

nm	is the name of the Symbol
ct	is the data-type of the Symbol
caddr	is the code address where the Symbol is being used
hash	is the dynamic hash

Returns: the new Symbol

References Address::getOffset(), Datatype::getSize(), Address::getSpace(), RangeList::insertRange(), Address::isInvalid(), Varnode::mapped, and Symbol::Symbol().

Referenced by Funcdata::buildDynamicSymbol().

ExternRefSymbol * Scope::addExternalRef	(	const Address &	addr,
		const Address &	refaddr,
		const string &	nm
	)

Create an external reference at the given address in this Scope

An ExternRefSymbol is created and mapped to the given address and stores a reference address to the actual function.

Parameters

addr	is the given address to map the Symbol to
refaddr	is the reference address
nm	is the name of the symbol/function

Returns: the new ExternRefSymbol

References ExternRefSymbol::ExternRefSymbol(), Symbol::flags, Varnode::readonly, and SymbolEntry::symbol.

FunctionSymbol * Scope::addFunction	(	const Address &	addr,
		const string &	nm
	)

Create a function Symbol at the given address in this Scope.

The FunctionSymbol is created and mapped to the given address. A Funcdata object is only created once FunctionSymbol::getFunction() is called.

Parameters

addr	is the entry address of the function
nm	is the name of the function, within this Scope

Returns: the new FunctionSymbol object

References Symbol::getName(), SymbolEntry::getSymbol(), and Symbol::name.

Referenced by Architecture::readLoaderSymbols().

SymbolEntry * Scope::addMap ( SymbolEntry & entry )

protected

Integrate a SymbolEntry into the range maps.

The mapping is given as an unintegrated SymbolEntry object. Memory may be specified in terms of join addresses, which this method must unravel. The offset, size, and extraflags fields of the SymbolEntry are not used. In particular, the SymbolEntry is assumed to map the entire Symbol.

Parameters

entry is the given SymbolEntry

Returns: a SymbolEntry which has been fully integrated

References SymbolEntry::addr, Varnode::addrtied, RangeList::clear(), RangeList::empty(), Symbol::flags, Symbol::getBytesConsumed(), Address::getOffset(), JoinRecord::getPiece(), SymbolEntry::hash, inScope(), Address::isBigEndian(), Address::isInvalid(), Address::isJoin(), Varnode::mapped, JoinRecord::numPieces(), Varnode::persist, Varnode::precishi, Varnode::precislo, SymbolEntry::symbol, and SymbolEntry::uselimit.

virtual SymbolEntry* Scope::addMapInternal	(	Symbol *	sym,
		uint4	exfl,
		const Address &	addr,
		int4	off,
		int4	sz,
		const RangeList &	uselim
	)

protectedpure virtual

Create a new SymbolEntry for a Symbol given a memory range.

The SymbolEntry is specified in terms of a memory range and usepoint

Parameters

sym	is the given Symbol being mapped
exfl	are any boolean Varnode properties specific to the memory range
addr	is the starting address of the given memory range
off	is the byte offset of the new SymbolEntry (relative to the whole Symbol)
sz	is the number of bytes in the range
uselim	is the given usepoint (which may be invalid)

Returns: the newly created SymbolEntry

Implemented in ScopeInternal, ScopeGhidraNamespace, and ScopeGhidra.

SymbolEntry * Scope::addMapPoint	(	Symbol *	sym,
		const Address &	addr,
		const Address &	usepoint
	)

Map a Symbol to a specific address.

Create a new SymbolEntry that maps the whole Symbol to the given address

Parameters

sym	is the Symbol
addr	is the given address to map to
usepoint	is a point at which the Symbol is accessed at that address

Returns: the SymbolEntry representing the new mapping

References SymbolEntry::addr, Address::getOffset(), Address::getSpace(), RangeList::insertRange(), Address::isInvalid(), and SymbolEntry::uselimit.

Referenced by ScopeInternal::retypeSymbol().

Symbol * Scope::addMapSym ( const Element * el )

Add a mapped Symbol from a <mapsym> XML tag.

A tag describing the Symbol is parsed first, followed by sequences of <addr> or <hash> and <rangelist> which define 1 or more mappings of the Symbol The new Symbol and SymbolEntry mappings are integrated into this Scope

Parameters

el	is the <mapsym> XML element

Returns: the new Symbol

References ExternRefSymbol::ExternRefSymbol(), Element::getChildren(), Element::getName(), SymbolEntry::isInvalid(), SymbolEntry::restoreXml(), Symbol::restoreXml(), and Symbol::Symbol().

Referenced by ScopeGhidra::dump2Cache(), and ScopeInternal::restoreXml().

void Scope::addRange	(	AddrSpace *	spc,
		uintb	first,
		uintb	last
	)

protectedvirtual

Add a memory range to the ownership of this Scope.

Parameters

spc	is the address space of the range
first	is the offset of the first byte in the range
last	is the offset of the last byte in the range

Reimplemented in ScopeGhidra.

Referenced by ScopeGhidra::addRange(), and Database::addRange().

SymbolEntry * Scope::addSymbol	(	const string &	name,
		Datatype *	ct,
		const Address &	addr,
		const Address &	usepoint
	)

virtual

Add a new Symbol to this Scope, given a name, data-type, and a single mapping.

The Symbol object will be created with the given name and data-type. A single mapping (SymbolEntry) will be created for the Symbol based on a given storage address for the symbol and an address for code that accesses the Symbol at that storage location.

Parameters

name	is the new name of the Symbol
ct	is the data-type of the new Symbol
addr	is the starting address of the Symbol storage
usepoint	is the point accessing that storage (may be invalid)

Returns: the SymbolEntry matching the new mapping

Reimplemented in ScopeGhidra.

References Symbol::Symbol().

Referenced by ScopeGhidra::addSymbol(), Funcdata::coverVarnodes(), ScopeLocal::createEntry(), Funcdata::linkSymbol(), Funcdata::mapGlobals(), and ScopeInternal::processCollision().

Symbol * Scope::addSymbol	(	const string &	name,
		Datatype *	ct
	)

Add a new Symbol without mapping it to an address.

The Symbol is created and added to any name map, but no SymbolEntry objects are created for it.

Parameters

name	is the name of the new Symbol
ct	is a data-type to assign to the new Symbol

Returns: the new Symbol object

References Symbol::Symbol().

virtual void Scope::addSymbolInternal ( Symbol * sym )

protectedpure virtual

Put a Symbol into the name map.

Parameters

sym	is the preconstructed Symbol

Implemented in ScopeInternal, and ScopeGhidra.

virtual void Scope::adjustCaches ( void )

pure virtual

Let scopes internally adjust any caches.

This is called once after Architecture configuration is complete.

Implemented in ScopeInternal, and ScopeGhidra.

void Scope::attachScope ( Scope * child )

private

Attach a new child Scope to this.

Attach the child as an immediate sub-scope of this. Take responsibility of the child's memory: the child will be freed when this is freed.

Parameters

child is the Scope to make a child

References parent, and uniqueId.

Referenced by Database::attachScope(), Database::findCreateScope(), and Database::restoreXmlScope().

string Scope::buildDefaultName	(	Symbol *	sym,
		int4 &	base,
		Varnode *	vn
	)		const

Create a default name for the given Symbol.

Create default name given information in the Symbol and possibly a representative Varnode. This method extracts the crucial properties and then uses the buildVariableName method to construct the actual name.

Parameters

sym	is the given Symbol to name
base	is an index (which may get updated) used to uniquify the name
vn	is an optional (may be null) Varnode representative of the Symbol

Returns: the default name

References Varnode::addrtied, Symbol::flags, SymbolEntry::getAddr(), Varnode::getAddr(), Symbol::getCategory(), Symbol::getCategoryIndex(), SymbolEntry::getFirstUseAddress(), Varnode::getFlags(), Varnode::getHigh(), Symbol::getMapEntry(), Symbol::getType(), Varnode::getUsePoint(), Varnode::input, Varnode::isAddrTied(), Varnode::isConstant(), HighVariable::isInput(), Address::isInvalid(), and Symbol::numEntries().

Referenced by ActionNameVars::apply(), and ScopeInternal::assignDefaultNames().

virtual Scope* Scope::buildSubScope	(	uint8	id,
		const string &	nm
	)

protectedpure virtual

Build an unattached Scope to be associated as a sub-scope of this.

This is a Scope object factory, intended to be called off of the global scope for building global namespace scopes. Function scopes are handled differently.

Parameters

id	is the globally unique id associated with the scope
nm	is the name of the new scope

Returns: the new Scope object

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by Database::findCreateScope().

virtual string Scope::buildUndefinedName ( void ) const

pure virtual

Build a formal undefined name, used internally when a Symbol is not given a name.

Returns: a special internal name that won't collide with other names in this Scope

Implemented in ScopeInternal, and ScopeGhidra.

virtual string Scope::buildVariableName	(	const Address &	addr,
		const Address &	pc,
		Datatype *	ct,
		int4 &	index,
		uint4	flags
	)		const

pure virtual

Given an address and data-type, build a suitable generic symbol name.

Parameters

addr	is the given address
pc	is the address at which the name is getting used
ct	is a data-type used to inform the name
index	is a reference to an index used to make the name unique, which will be updated
flags	are boolean properties of the variable we need the name for

Returns: the new variable name

Implemented in ScopeInternal, ScopeLocal, and ScopeGhidra.

Referenced by Funcdata::mapGlobals().

void Scope::detachScope ( ScopeMap::iterator iter )

private

Detach a child Scope from this.

The indicated child Scope is deleted

Parameters

iter	points to the Scope to delete

Referenced by Database::deleteScope(), and Database::deleteSubScopes().

Scope * Scope::discoverScope	(	const Address &	addr,
		int4	sz,
		const Address &	usepoint
	)

Find the owning Scope of a given memory range.

Discover a sub-scope or containing Scope of this, that owns the given memory range at a specific usepoint. Note that ownership does not necessarily mean there is a known symbol there.

Parameters

addr	is the starting address of the memory range
sz	is the number of bytes in the range
usepoint	is a point at which the memory is getting accesses

References getParent(), inScope(), and Address::isConstant().

Referenced by Funcdata::mapGlobals().

virtual SymbolEntry* Scope::findAddr	(	const Address &	addr,
		const Address &	usepoint
	)		const

pure virtual

Find a Symbol at a given address and usepoint.

Parameters

addr	is the given address
usepoint	is the point at which the Symbol is accessed (may be invalid)

Returns: the matching SymbolEntry or NULL

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by stackAddr().

virtual void Scope::findByName	(	const string &	name,
		vector< Symbol * > &	res
	)		const

pure virtual

Find a Symbol by name within this Scope.

If there are multiple Symbols with the same name, all are passed back.

Parameters

name	is the name to search for
res	will contain any matching Symbols

Implemented in ScopeInternal, and ScopeGhidra.

virtual SymbolEntry* Scope::findClosestFit	(	const Address &	addr,
		int4	size,
		const Address &	usepoint
	)		const

pure virtual

Find Symbol which is the closest fit to the given memory range.

Parameters

addr	is the starting address of the given memory range
size	is the number of bytes in the range
usepoint	is the point at which the Symbol is accessed (may be invalid)

Returns: the matching SymbolEntry or NULL

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by stackClosestFit().

virtual LabSymbol* Scope::findCodeLabel ( const Address & addr ) const

pure virtual

Find a label Symbol at the given address.

Parameters

addr	is the given address

Returns: the matching LabSymbol or NULL

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by stackCodeLabel().

virtual SymbolEntry* Scope::findContainer	(	const Address &	addr,
		int4	size,
		const Address &	usepoint
	)		const

pure virtual

Find the smallest Symbol containing the given memory range.

Parameters

addr	is the starting address of the given memory range
size	is the number of bytes in the range
usepoint	is the point at which the Symbol is accessed (may be invalid)

Returns: the matching SymbolEntry or NULL

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by Funcdata::coverVarnodes(), and stackContainer().

const Scope * Scope::findDistinguishingScope ( const Scope * op2 ) const

Find first ancestor of this not shared by given scope.

Any two scopes share at least the global scope as a common ancestor. We find the first scope that is not in common. The scope returned will always be an ancestor of this. If this is an ancestor of the other given scope, then null is returned.

Parameters

op2	is the other given Scope

Returns: the first ancestor Scope that is not in common or null

References getScopePath(), and parent.

Referenced by Symbol::getResolutionDepth().

virtual ExternRefSymbol* Scope::findExternalRef ( const Address & addr ) const

pure virtual

Find an external reference at the given address.

Parameters

addr	is the given address

Returns: the matching ExternRefSymbol or NULL

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by stackExternalRef().

virtual Funcdata* Scope::findFunction ( const Address & addr ) const

pure virtual

Find the function starting at the given address.

Parameters

addr	is the given starting address

Returns: the matching Funcdata object or NULL

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by stackFunction().

virtual SymbolEntry* Scope::findOverlap	(	const Address &	addr,
		int4	size
	)		const

pure virtual

Find first Symbol overlapping the given memory range.

Parameters

addr	is the starting address of the given range
size	is the number of bytes in the range

Returns: an overlapping SymbolEntry or NULL if none exists

Implemented in ScopeInternal, and ScopeGhidra.

virtual int4 Scope::getCategorySize ( int4 cat ) const

pure virtual

Get the number of Symbols in the given category.

Parameters

cat	is the Symbol category

Returns: the number in that category

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by PrintC::emitScopeVarDecls().

virtual Symbol* Scope::getCategorySymbol	(	int4	cat,
		int4	ind
	)		const

pure virtual

Retrieve a Symbol by index within a specific category.

Parameters

cat	is the Symbol category
ind	is the index (within the category) of the Symbol

Returns: the indicated Symbol or NULL if no Symbol with that index exists

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by PrintC::emitScopeVarDecls().

void Scope::getScopePath ( vector< const Scope * > & vec ) const

Get the ordered list of scopes up to this.

Put the parent scopes of this into an array in order, starting with the global scope.

Parameters

vec	is storage for the array of scopes

References parent.

Referenced by findDistinguishingScope().

uint8 Scope::hashScopeName	(	uint8	baseId,
		const string &	nm
	)

staticprivate

Create a Scope id based on the scope's name and its parent's id.

Create a globally unique id for a scope simply from its name.

Parameters

baseId	is the scope id of the parent scope
nm	is the name of scope

Returns: the hash of the parent id and name

References crc_update().

Referenced by Database::findCreateScopeFromSymbolName().

virtual bool Scope::inScope	(	const Address &	addr,
		int4	size,
		const Address &	usepoint
	)		const

inlinevirtual

Query if the given range is owned by this Scope.

All bytes in the range must be owned, and ownership can be informed by particular code that is accessing the range.

Parameters

addr	is the starting address of the range
size	is the number of bytes in the range
usepoint	is the code address at which the given range is being accessed (may be invalid)

Returns: true if this Scope owns the memory range

References RangeList::inRange(), SymbolEntry::restoreXml(), SymbolEntry::saveXml(), SymbolEntry::size, and SymbolEntry::EntryInitData::symbol.

Referenced by addMap(), discoverScope(), stackAddr(), stackClosestFit(), stackCodeLabel(), stackContainer(), stackFunction(), and Funcdata::syncVarnodesWithSymbols().

virtual bool Scope::isNameUsed	(	const string &	nm,
		const Scope *	op2
	)		const

pure virtual

Check if the given name is occurs within the given scope path.

Test for the presence of a symbol with the given name in either this scope or an ancestor scope up to but not including the given terminating scope. If the name is used true is returned.

Parameters

nm	is the given name to test
op2	is the terminating ancestor scope (or null)

Implemented in ScopeInternal, ScopeGhidraNamespace, and ScopeGhidra.

Referenced by Symbol::getResolutionDepth(), and ScopeInternal::isNameUsed().

bool Scope::isReadOnly	(	const Address &	addr,
		int4	size,
		const Address &	usepoint
	)		const

Is the given memory range marked as read-only.

Check for Symbols relative to this Scope that are marked as read-only, and look-up properties of the memory in general.

Parameters

addr	is the starting address of the given memory range
size	is the number of bytes in the range
usepoint	is a point where the range is getting accessed

Returns: true if the memory is marked as read-only

References Symbol::flags, and Varnode::readonly.

Referenced by RulePtrsubCharConstant::applyOp(), and PrintC::pushPtrCharConstant().

bool Scope::isSubScope ( const Scope * scp ) const

Is this a sub-scope of the given Scope.

Does the given Scope contain this as a sub-scope.

Parameters

scp	is the given Scope

Returns: true if this is a sub-scope

References parent.

virtual string Scope::makeNameUnique ( const string & nm ) const

pure virtual

Produce a version of the given symbol name that won't collide with other names in this Scope.

Parameters

nm	is the given name

Returns: return a unique version of the name

Implemented in ScopeInternal, and ScopeGhidra.

void Scope::overrideSizeLockType	(	Symbol *	sym,
		Datatype *	ct
	)

Change the data-type of a Symbol that is sizelocked.

Change (override) the data-type of a sizelocked Symbol, while preserving the lock. An exception is thrown if the new data-type doesn't fit the size.

Parameters

sym	is the locked Symbol
ct	is the data-type to change the Symbol to

References Datatype::getSize(), Symbol::isSizeTypeLocked(), and Symbol::type.

Referenced by ActionNameVars::linkSymbols().

SymbolEntry * Scope::queryByAddr	(	const Address &	addr,
		const Address &	usepoint
	)		const

Get Symbol with matching address.

Within a sub-scope or containing Scope of this, find a Symbol that is mapped to the given address, where the mapping is valid at a specific usepoint.

Parameters

addr	is the given address
usepoint	is the point at which code accesses that address (may be invalid)

Returns: the matching SymbolEntry

void Scope::queryByName	(	const string &	name,
		vector< Symbol * > &	res
	)		const

Look-up symbols by name.

Starting from this Scope, look for a Symbol with the given name. If there are no Symbols in this Scope, recurse into the parent Scope. If there are 1 (or more) Symbols matching in this Scope, add them to the result list

Parameters

name	is the name to search for
res	is the result list

Referenced by ScopeGhidra::dump2Cache(), and Funcdata::findHigh().

LabSymbol * Scope::queryCodeLabel ( const Address & addr ) const

Look-up a code label by address.

Within a sub-scope or containing Scope of this, find a label Symbol at the given address.

Parameters

addr	is the given address

Returns: the LabSymbol object, or NULL if it doesn't exist

Referenced by PrintC::emitLabel().

SymbolEntry * Scope::queryContainer	(	const Address &	addr,
		int4	size,
		const Address &	usepoint
	)		const

Find the smallest containing Symbol.

Within a sub-scope or containing Scope of this, find the smallest Symbol that contains a given memory range and can be accessed at a given usepoint.

Parameters

addr	is the given starting address of the memory range
size	is the number of bytes in the range
usepoint	is a point at which the Symbol is accessed (may be invalid)

Returns: the matching SymbolEntry or NULL

Referenced by ActionConstantPtr::isPointer(), Funcdata::linkSymbolReference(), and PrintC::pushAnnotation().

Funcdata * Scope::queryExternalRefFunction ( const Address & addr ) const

Look-up a function thru an external reference.

Given an address, search for an external reference. If no Symbol is found and this Scope does not own the address, recurse searching in the parent Scope. If an external reference is found, try to resolve the function it refers to and return it.

Parameters

addr	is the given address where an external reference might be

Returns: the referred to Funcdata object or NULL if not found

References resolveExternalRefFunction().

Referenced by ActionDeindirect::apply().

Funcdata * Scope::queryFunction ( const string & name ) const

Look-up a function by name.

Starting with this Scope, find a function with the given name. If there are no Symbols with that name in this Scope at all, recurse into the parent Scope.

Parameters

name	if the name to search for

Returns: the Funcdata object of the matching function, or NULL if it doesn't exist

References FunctionSymbol::getFunction().

Referenced by OptionExtraPop::apply(), OptionInline::apply(), OptionNoReturn::apply(), ActionDeindirect::apply(), PrintC::pushPtrCodeConstant(), FlowInfo::queryCall(), DecompileAt::rawAction(), ScopeInternal::resolveExternalRefFunction(), and Architecture::setPrototype().

Funcdata * Scope::queryFunction ( const Address & addr ) const

Look-up a function by address.

Within a sub-scope or containing Scope of this, find a function starting at the given address.

Parameters

addr	is the starting address of the function

Returns: the Funcdata object of the matching function, or NULL if it doesn't exist

SymbolEntry * Scope::queryProperties	(	const Address &	addr,
		int4	size,
		const Address &	usepoint,
		uint4 &	flags
	)		const

Find a Symbol or properties at the given address.

Similarly to queryContainer(), this searches for the smallest containing Symbol, but whether a known Symbol is found or not, boolean properties associated with the memory range are also search for and passed back.

Parameters

addr	is the starting address of the range
size	is the number of bytes in the range
usepoint	is a point at which the memory range is accessed (may be invalid)
flags	is a reference used to pass back the boolean properties of the memory range

Returns: the smallest SymbolEntry containing the range, or NULL

References Varnode::addrtied, SymbolEntry::getAllFlags(), isGlobal(), Varnode::mapped, and Varnode::persist.

Referenced by TypeOpCallother::getInputLocal(), TypeOpCallother::getOutputLocal(), Funcdata::linkSymbol(), Funcdata::mapGlobals(), Funcdata::newVarnode(), Funcdata::newVarnodeOut(), and Funcdata::setVarnodeProperties().

void Scope::removeRange	(	AddrSpace *	spc,
		uintb	first,
		uintb	last
	)

protectedvirtual

Remove a memory range from the ownership of this Scope.

Parameters

spc	is the address space of the range
first	is the offset of the first byte in the range
last	is the offset of the last byte in the range

Reimplemented in ScopeGhidra.

Referenced by Database::removeRange().

void Scope::resetSizeLockType ( Symbol * sym )

Clear a Symbol's size-locked data-type.

Replace any overriding data-type type with the locked UNKNOWN type of the correct size. The data-type is cleared, but the lock is preserved.

Parameters

sym	is the Symbol to clear

References Datatype::getMetatype(), Datatype::getSize(), Symbol::type, and TYPE_UNKNOWN.

Referenced by ScopeInternal::clearUnlocked(), and ScopeInternal::clearUnlockedCategory().

virtual Funcdata* Scope::resolveExternalRefFunction ( ExternRefSymbol * sym ) const

pure virtual

Convert an external reference to the referenced function.

Parameters

sym	is the Symbol marking the external reference

Returns: the underlying Funcdata object or NULL if none exists

Implemented in ScopeInternal, and ScopeGhidra.

Referenced by queryExternalRefFunction().

Scope * Scope::resolveScope	(	const string &	name,
		bool	strategy
	)		const

Find a child Scope of this.

Look for the immediate child of this with a given name

Parameters

name	is the child's name
strategy	is true if hash of the name determines id

Returns: the child Scope or NULL if there is no child with that name

References name, and Symbol::scope.

Referenced by Database::findCreateScope(), Database::parseParentTag(), and Database::resolveScopeFromSymbolName().

void Scope::restrictScope ( Funcdata * f )

protectedvirtual

Convert this to a local Scope.

Attach this to the given function, which makes this the local scope for the function

Parameters

f	is the given function to attach to

Reimplemented in ScopeGhidra.

Referenced by ScopeLocal::ScopeLocal().

virtual void Scope::retypeSymbol	(	Symbol *	sym,
		Datatype *	ct
	)

pure virtual

Change the data-type of a Symbol within this Scope.

If the size of the Symbol changes, any mapping (SymbolEntry) is adjusted

Parameters

sym	is the given Symbol
ct	is the new data-type

Implemented in ScopeInternal, and ScopeGhidra.

void Scope::saveXmlRecursive	(	ostream &	s,
		bool	onlyGlobal
	)		const

Save all contained scopes as an XML stream.

This Scope and all of its sub-scopes are saved as a sequence of <scope> tags in post order. For each Scope, the saveXml() method is invoked.

Parameters

s	is the output stream
onlyGlobal	is true if only non-local Scopes should be saved

References ExternRefSymbol::saveXml().

Referenced by Funcdata::saveXml().

virtual void Scope::setCategory	(	Symbol *	sym,
		int4	cat,
		int4	ind
	)

pure virtual

Set the category and index for the given Symbol.

Parameters

sym	is the given Symbol
cat	is the category to set for the Symbol
ind	is the index position to set (within the category)

Implemented in ScopeInternal, and ScopeGhidra.

const Scope * Scope::stackAddr	(	const Scope *	scope1,
		const Scope *	scope2,
		const Address &	addr,
		const Address &	usepoint,
		SymbolEntry **	addrmatch
	)

staticprotected

Query for Symbols starting at a given address, which match a given usepoint.

Searching starts at a first scope, continuing thru parents up to a second scope, which is not queried. If a Scope controls the memory at that address, the Scope object is returned. Additionally, if a symbol matching the criterion is found, the matching SymbolEntry is passed back.

Parameters

scope1	is the first Scope where searching starts
scope2	is the second Scope where searching ends
addr	is the given address to search for
usepoint	is the given point at which the memory is being accessed (can be an invalid address)
addrmatch	is used to pass-back any matching SymbolEntry

Returns: the Scope owning the address or NULL if none found

References findAddr(), getParent(), inScope(), and Address::isConstant().

const Scope * Scope::stackClosestFit	(	const Scope *	scope1,
		const Scope *	scope2,
		const Address &	addr,
		int4	size,
		const Address &	usepoint,
		SymbolEntry **	addrmatch
	)

staticprotected

Query for a Symbol which most closely matches a given range and usepoint

Searching starts at a first scope, continuing thru parents up to a second scope, which is not queried. If a Scope controls the memory in the given range, the Scope object is returned. Among symbols that overlap the given range, the SymbolEntry which most closely matches the starting address and size is passed back.

Parameters

scope1	is the first Scope where searching starts
scope2	is the second Scope where searching ends
addr	is the starting address of the given range
size	is the number of bytes in the given range
usepoint	is the point at which the memory is being accessed (can be an invalid address)
addrmatch	is used to pass-back any matching SymbolEntry

Returns: the Scope owning the address or NULL if none found

References findClosestFit(), getParent(), inScope(), and Address::isConstant().

const Scope * Scope::stackCodeLabel	(	const Scope *	scope1,
		const Scope *	scope2,
		const Address &	addr,
		LabSymbol **	addrmatch
	)

staticprotected

Query for a label Symbol for a given address.

Searching starts at a first scope, continuing thru parents up to a second scope, which is not queried. If a Scope controls the memory in the given range, the Scope object is returned. If there is a label at that address, pass back the corresponding LabSymbol object

Parameters

scope1	is the first Scope where searching starts
scope2	is the second Scope where searching ends
addr	is the given address
addrmatch	is used to pass-back any matching Symbol

Returns: the Scope owning the address or NULL if none found

References findCodeLabel(), getParent(), inScope(), and Address::isConstant().

const Scope * Scope::stackContainer	(	const Scope *	scope1,
		const Scope *	scope2,
		const Address &	addr,
		int4	size,
		const Address &	usepoint,
		SymbolEntry **	addrmatch
	)

staticprotected

Query for a Symbol containing a given range which is accessed at a given usepoint

Searching starts at a first scope, continuing thru parents up to a second scope, which is not queried. If a Scope controls the memory in the given range, the Scope object is returned. If a known Symbol contains the range, the matching SymbolEntry is passed back.

Parameters

scope1	is the first Scope where searching starts
scope2	is the second Scope where searching ends
addr	is the starting address of the given range
size	is the number of bytes in the given range
usepoint	is the point at which the memory is being accessed (can be an invalid address)
addrmatch	is used to pass-back any matching SymbolEntry

Returns: the Scope owning the address or NULL if none found

References findContainer(), getParent(), inScope(), and Address::isConstant().

const Scope * Scope::stackExternalRef	(	const Scope *	scope1,
		const Scope *	scope2,
		const Address &	addr,
		ExternRefSymbol **	addrmatch
	)

staticprotected

Query for an external reference Symbol starting at the given address

Searching starts at a first scope, continuing thru parents up to a second scope, which is not queried. If a Scope controls the memory in the given range, the Scope object is returned. If an external reference is found at the address, pass back the matching ExternRefSymbol

Parameters

scope1	is the first Scope where searching starts
scope2	is the second Scope where searching ends
addr	is the given address
addrmatch	is used to pass-back any matching Symbol

Returns: the Scope owning the address or NULL if none found

References findExternalRef(), getParent(), and Address::isConstant().

const Scope * Scope::stackFunction	(	const Scope *	scope1,
		const Scope *	scope2,
		const Address &	addr,
		Funcdata **	addrmatch
	)

staticprotected

Query for a function Symbol starting at the given address

Searching starts at a first scope, continuing thru parents up to a second scope, which is not queried. If a Scope controls the memory in the given range, the Scope object is returned. If a FunctionSymbol is found at the given address, the corresponding Funcdata object is passed back.

Parameters

scope1	is the first Scope where searching starts
scope2	is the second Scope where searching ends
addr	is the given address where the function should start
addrmatch	is used to pass-back any matching function

Returns: the Scope owning the address or NULL if none found

References findFunction(), getParent(), inScope(), and Address::isConstant().

Referenced by ScopeGhidra::resolveExternalRefFunction().

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

database.hh
database.cc

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Detailed Description

Member Function Documentation