Ghidra Decompiler Analysis Engine
Public Member Functions | List of all members
Database Class Reference

A manager for symbol scopes for a whole executable. More...

#include <database.hh>

Public Member Functions

 Database (Architecture *g, bool idByName)
 Constructor. More...
 
 ~Database (void)
 Destructor.
 
void adjustCaches (void)
 Let scopes adjust after configuration is finished. More...
 
void attachScope (Scope *newscope, Scope *parent)
 Register a new Scope. More...
 
void deleteScope (Scope *scope)
 Delete the given Scope and all its sub-scopes. More...
 
void deleteSubScopes (Scope *scope)
 Delete all sub-scopes of the given Scope. More...
 
void clearUnlocked (Scope *scope)
 Clear unlocked Symbols owned by the given Scope. More...
 
void setRange (Scope *scope, const RangeList &rlist)
 Set the ownership range for a Scope. More...
 
void addRange (Scope *scope, AddrSpace *spc, uintb first, uintb last)
 Add an address range to the ownership of a Scope. More...
 
void removeRange (Scope *scope, AddrSpace *spc, uintb first, uintb last)
 Remove an address range from ownership of a Scope. More...
 
ScoperesolveScope (uint8 id) const
 Look-up a Scope by id. More...
 
ScoperesolveScopeFromSymbolName (const string &fullname, const string &delim, string &basename, Scope *start) const
 Get the Scope (and base name) associated with a qualified Symbol name. More...
 
ScopefindCreateScope (uint8, const string &nm, Scope *parent)
 
ScopefindCreateScopeFromSymbolName (const string &fullname, const string &delim, string &basename, Scope *start)
 Find (and if not found create) a specific subscope. More...
 
const ScopemapScope (const Scope *qpoint, const Address &addr, const Address &usepoint) const
 Determine the lowest-level Scope which might contain the given address as a Symbol. More...
 
ScopemapScope (Scope *qpoint, const Address &addr, const Address &usepoint)
 A non-constant version of mapScope() More...
 
void setPropertyRange (uint4 flags, const Range &range)
 Set boolean properties over a given memory range. More...
 
void saveXml (ostream &s) const
 Save the whole Database to an XML stream. More...
 
void restoreXml (const Element *el)
 Recover the whole database from XML. More...
 
void restoreXmlScope (const Element *el, Scope *newScope)
 Register and fill out a single Scope from an XML <scope> tag. More...
 

Detailed Description

A manager for symbol scopes for a whole executable.

This is the highest level container for anything related to Scope and Symbol objects, it indirectly holds the Funcdata objects as well, through the FunctionSymbol. It acts as the formal symbol table for the decompiler. The API is mostly concerned with the management of Scope objects.

A Scope object is initially registered via attachScope(), then it can looked up by name. This class maintains the cross Scope search by address capability, implemented as a map from an Address to the Scope that owns it. For efficiency, this map is really only applied to namespace Scopes, the global Scope and function Scopes are not entered in the map. This class also maintains a set of boolean properties that label memory ranges. This allows important properties like read-only and volatile to be put down even if the Symbols aren't yet known.

Constructor & Destructor Documentation

◆ Database()

Database::Database ( Architecture g,
bool  idByName 
)

Constructor.

Initialize a new symbol table, with no initial scopes or symbols.

Parameters
gis the Architecture that owns the symbol table
idByNameis true if scope ids are calculated as a hash of the scope name.

Member Function Documentation

◆ addRange()

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

Add an address range to the ownership of a Scope.

The new range will be merged with the existing ownership. The address to Scope map is updated

Parameters
scopeis the given Scope
spcis the address space of the memory range being added
firstis the offset of the first byte in the array
lastis the offset of the last byte

◆ adjustCaches()

void Database::adjustCaches ( void  )

Let scopes adjust after configuration is finished.

Give this database the chance to inform existing scopes of any change to the configuration, which may have changed since the initial scopes were created.

◆ attachScope()

void Database::attachScope ( Scope newscope,
Scope parent 
)

Register a new Scope.

The new Scope must be initially empty and this Database takes over ownership. Practically, this is just setting up the new Scope as a sub-scope of its parent. The parent Scope should already be registered with this Database, or NULL can be passed to register the global Scope.

Parameters
newscopeis the new Scope being registered
parentis the parent Scope or NULL

◆ clearUnlocked()

void Database::clearUnlocked ( Scope scope)

Clear unlocked Symbols owned by the given Scope.

All unlocked symbols in this Scope, and recursively into its sub-scopes, are removed.

Parameters
scopeis the given Scope

◆ deleteScope()

void Database::deleteScope ( Scope scope)

Delete the given Scope and all its sub-scopes.

Parameters
scopeis the given Scope

◆ deleteSubScopes()

void Database::deleteSubScopes ( Scope scope)

Delete all sub-scopes of the given Scope.

The given Scope is not deleted, only its children.

Parameters
scopeis the given Scope

◆ findCreateScope()

Scope * Database::findCreateScope ( uint8  id,
const string &  nm,
Scope parent 
)

Look for a Scope by id. If it does not exist, create a new scope with the given name and parent scope.

Parameters
idis the global id of the Scope
nmis the given name of the Scope
parentis the given parent scope to search
Returns
the subscope object either found or created

◆ findCreateScopeFromSymbolName()

Scope * Database::findCreateScopeFromSymbolName ( const string &  fullname,
const string &  delim,
string &  basename,
Scope start 
)

Find (and if not found create) a specific subscope.

Find and/or create Scopes associated with a qualified Symbol name.

The name is parsed using a delimiter that is passed in. The name can be only partially qualified by passing in a starting Scope, which the name is assumed to be relative to. Otherwise the name is assumed to be relative to the global Scope. The unqualified (base) name of the Symbol is passed back to the caller. Any missing scope in the path is created.

Parameters
fullnameis the qualified Symbol name
delimis the delimiter separating names
basenamewill hold the passed back base Symbol name
startis the Scope to start drilling down from, or NULL for the global scope
Returns
the Scope being referred to by the name

◆ mapScope() [1/2]

const Scope * Database::mapScope ( const Scope qpoint,
const Address addr,
const Address usepoint 
) const

Determine the lowest-level Scope which might contain the given address as a Symbol.

As currently implemented, this method can only find a namespace Scope. When searching for a Symbol by Address, the global Scope is always searched because it is the terminating Scope when recursively walking scopes through the parent relationship, so it isn't entered in this map. A function level Scope, also not entered in the map, is only returned as the Scope passed in as a default, when no namespace Scope claims the address.

Parameters
qpointis the default Scope returned if no owner is found
addris the address whose owner should be searched for
usepointis a point in code where the address is being accessed (may be invalid)
Returns
a Scope to act as a starting point for a hierarchical search

◆ mapScope() [2/2]

Scope * Database::mapScope ( Scope qpoint,
const Address addr,
const Address usepoint 
)

A non-constant version of mapScope()

Parameters
qpointis the default Scope returned if no owner is found
addris the address whose owner should be searched for
usepointis a point in code where the address is being accessed (may be invalid)
Returns
a Scope to act as a starting point for a hierarchical search

◆ removeRange()

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

Remove an address range from ownership of a Scope.

Addresses owned by the Scope that are disjoint from the given range are not affected.

Parameters
scopeis the given Scope
spcis the address space of the memory range being removed
firstis the offset of the first byte in the array
lastis the offset of the last byte

◆ resolveScope()

Scope * Database::resolveScope ( uint8  id) const

Look-up a Scope by id.

Find a Scope object, given its global id. Return null if id is not mapped to a Scope.

Parameters
idis the global id
Returns
the matching Scope or null

◆ resolveScopeFromSymbolName()

Scope * Database::resolveScopeFromSymbolName ( const string &  fullname,
const string &  delim,
string &  basename,
Scope start 
) const

Get the Scope (and base name) associated with a qualified Symbol name.

The name is parsed using a delimiter that is passed in. The name can be only partially qualified by passing in a starting Scope, which the name is assumed to be relative to. Otherwise the name is assumed to be relative to the global Scope. The unqualified (base) name of the Symbol is passed back to the caller.

Parameters
fullnameis the qualified Symbol name
delimis the delimiter separating names
basenamewill hold the passed back base Symbol name
startis the Scope to start drilling down from, or NULL for the global scope
Returns
the Scope being referred to by the name

◆ restoreXml()

void Database::restoreXml ( const Element el)

Recover the whole database from XML.

The children of a <db> tag are examined to recover Scope and Symbol objects.

Parameters
elis the <db> element

◆ restoreXmlScope()

void Database::restoreXmlScope ( const Element el,
Scope newScope 
)

Register and fill out a single Scope from an XML <scope> tag.

This allows incremental building of the Database from multiple XML sources. An empty Scope must already be allocated. It is registered with this Database, and then populated with Symbol objects based as the content of a given XML tag. The tag can either be a <scope> itself, or another tag that wraps a <scope> tag as its first child.

Parameters
elis the given <scope> element
newScopeis the empty Scope

◆ saveXml()

void Database::saveXml ( ostream &  s) const

Save the whole Database to an XML stream.

This writes a single <db> tag to the stream, which contains sub-tags for each Scope (which contain Symbol sub-tags in turn).

Parameters
sis the output stream

◆ setPropertyRange()

void Database::setPropertyRange ( uint4  flags,
const Range range 
)

Set boolean properties over a given memory range.

This allows the standard boolean Varnode properties like read-only and volatile to be put an a memory range, independent of whether a Symbol is there or not. These get picked up by the Scope::queryProperties() method in particular.

Parameters
flagsis the set of boolean properties
rangeis the memory range to label

◆ setRange()

void Database::setRange ( Scope scope,
const RangeList rlist 
)

Set the ownership range for a Scope.

Any existing ownership is completely replaced. The address to Scope map is updated.

Parameters
scopeis the given Scope
rlistis the set of addresses to mark as owned

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