Package ghidra.program.model.pcode

Class HighSymbol

java.lang.Object

ghidra.program.model.pcode.HighSymbol

Direct Known Subclasses:

EquateSymbol, HighCodeSymbol, HighExternalSymbol, HighFunctionShellSymbol, HighFunctionSymbol, HighLabelSymbol

public class HighSymbol
extends java.lang.Object

A symbol within the decompiler's model of a particular function. The symbol has a name and a data-type along with other properties. The symbol is mapped to one or more storage locations by attaching a SymbolEntry for each mapping.

Field Summary

Fields

Change	Modifier and Type	Field	Description
NEW	protected int	category
NEW	protected int	categoryIndex
NEW	protected SymbolEntry[]	entryList
	protected HighFunction	function
NEW	static long	ID_BASE
	protected java.lang.String	name
	protected DataType	type
REMOVED		size()	(Removed)
REMOVED		pcaddr()	(Removed)

Constructor Summary

Constructors

Change	Modifier	Constructor	Description
	protected	HighSymbol(long uniqueId, java.lang.String nm, DataType tp, boolean tlock, boolean nlock, PcodeDataTypeManager manage)	Construct a symbol that is not attached to a function model.
	protected	HighSymbol(long uniqueId, java.lang.String nm, DataType tp, HighFunction func)	Construct a base symbol, given a name and data-type.
	protected	HighSymbol(HighFunction func)	Constructor for use with restoreXML

Method Summary

Change	Modifier and Type	Method	Description
NEW	protected void	addMapEntry(SymbolEntry entry)
NEW	static void	buildMapSymXML(java.lang.StringBuilder res, HighSymbol sym)	Write out the given symbol with all its mapping as a <mapsym> tag to the given XML stream.
NEW	int	getCategoryIndex()	For parameters (category=0), this method returns the position of the parameter within the function prototype.
	DataType	getDataType()
NEW	protected int	getFirstUseOffset()	Get the first code Address (expressed as a different in bytes from the starting address of the function) where this symbol's storage actually holds the value of the symbol.
NEW	SymbolEntry	getFirstWholeMap()
	HighFunction	getHighFunction()	Get the function model of which this symbol is a part.
	HighVariable	getHighVariable()	Get the HighVariable associate with this symbol if any.
NEW	long	getId()	Get id associated with this symbol.
	java.lang.String	getName()	Get the base name of this symbol
NEW	Namespace	getNamespace()	Fetch the namespace owning this symbol, if it exists.
	Address	getPCAddress()	Get the first code Address, within the function, where this symbol's storage actually holds the value of the symbol.
NEW	Program	getProgram()	Get the Program object containing the function being modeled.
	int	getSize()
NEW	VariableStorage	getStorage()
NEW	Symbol	getSymbol()	Fetch the corresponding database Symbol if it exists.
NEW	boolean	isGlobal()	Is this symbol in the global scope or some other global namespace
NEW	boolean	isHiddenReturn()
NEW	boolean	isIsolated()	If this returns true, the decompiler will not speculatively merge this with other variables.
	boolean	isNameLocked()	If this returns true, this symbol's name is "locked".
NEW	boolean	isParameter()	Is this symbol a parameter for a function
	boolean	isReadOnly()
NEW	boolean	isThisPointer()
	boolean	isTypeLocked()	If this returns true, this symbol's data-type is "locked", meaning it is considered unchangeable during decompilation.
NEW	static HighSymbol	restoreMapSymXML(XmlPullParser parser, boolean isGlobal, HighFunction high)	Restore a full HighSymbol from the next <mapsym> tag in the given XML stream.
NEW	void	restoreXML(XmlPullParser parser)	Restore this symbol object and its associated mappings from an XML description in the given stream.
NEW	protected void	restoreXMLHeader(XmlElement symel)
NEW	void	saveXML(java.lang.StringBuilder buf)	Save the symbol description as a tag to the XML stream.
NEW	protected void	saveXMLHeader(java.lang.StringBuilder buf)	Write out attributes for the base XML tag
NEW	protected void	setCategory(int cat, int index)	Set the category and associated index for this symbol.
	void	setHighVariable(HighVariable high)	Associate a particular HighVariable with this symbol.
	void	setNameLock(boolean namelock)	Set whether this symbol's name is considered "locked".
	void	setTypeLock(boolean typelock)	Set whether this symbol's data-type is considered "locked".
REMOVED	void	setReadOnly(boolean readOnly)	(Removed)
REMOVED	String	buildXML()	(Removed)
REMOVED	int	restoreXML(XmlPullParser parser, HighFunction func)	(Removed)
REMOVED	int	restoreSymbolXML(XmlElement symel, HighFunction func)	(Removed)
REMOVED	Address	parseRangeList(XmlPullParser parser)	(Removed)
REMOVED	void	buildMapSymXML(StringBuilder res, String addrHashRes, Address pc, String sym)	(Removed)
REMOVED	void	buildRangelistXML(StringBuilder res, Address pc)	(Removed)

Methods inherited from class java.lang.Object

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

Field Detail

ID_BASE NEW

public static final long ID_BASE

See Also:

Constant Field Values

name

protected java.lang.String name

type

protected DataType type

function

protected HighFunction function

category NEW

protected int category

categoryIndex NEW

protected int categoryIndex

entryList NEW

protected SymbolEntry[] entryList

Constructor Detail

HighSymbol

protected HighSymbol(HighFunction func)

Constructor for use with restoreXML

Parameters:

func - is the HighFunction using the symbol

HighSymbol

protected HighSymbol(long uniqueId,
                     java.lang.String nm,
                     DataType tp,
                     HighFunction func)

Construct a base symbol, given a name and data-type. Mappings must be attached separately.

Parameters:

uniqueId - is the id to associate with the new symbol

nm - is the given name

tp - is the given data-type

func - is the function model owning the new symbol

HighSymbol

protected HighSymbol(long uniqueId,
                     java.lang.String nm,
                     DataType tp,
                     boolean tlock,
                     boolean nlock,
                     PcodeDataTypeManager manage)

Construct a symbol that is not attached to a function model. The symbol is given a name, data-type, and other basic attributes. Mappings must be attached separately.

Parameters:

uniqueId - is the id to associate with the new symbol

nm - is the given name

tp - is the given data-type

tlock - is true if the symbol is type locked

nlock - is true if the symbol is name locked

manage - is a PcodeDataTypeManager to facilitate XML marshaling

Method Detail

addMapEntry NEW

protected void addMapEntry(SymbolEntry entry)

getId NEW

public long getId()

Get id associated with this symbol.

Returns:

the id

getSymbol NEW

public Symbol getSymbol()

Fetch the corresponding database Symbol if it exists.

Returns:

the matching Symbol object or null

getNamespace NEW

public Namespace getNamespace()

Fetch the namespace owning this symbol, if it exists.

Returns:

the Namespace object or null

setHighVariable

public void setHighVariable(HighVariable high)

Associate a particular HighVariable with this symbol. This is used to link the symbol into the decompiler's description of how a function manipulates a particular symbol.

Parameters:

high - is the associated HighVariable

getHighVariable

public HighVariable getHighVariable()

Get the HighVariable associate with this symbol if any. This allows the user to go straight into the decompiler's function to see how the symbol gets manipulated.

Returns:

the associated HighVariable or null

getName

public java.lang.String getName()

Get the base name of this symbol

Returns:

the name

getProgram NEW

public Program getProgram()

Get the Program object containing the function being modeled.

Returns:

the Program

getDataType

public DataType getDataType()

Returns:

the data-type associate with this symbol

getSize

public int getSize()

Returns:

the number of bytes consumed by the storage for this symbol

getPCAddress

public Address getPCAddress()

Get the first code Address, within the function, where this symbol's storage actually holds the value of the symbol. If there is more than one mapping for the symbol, this returns the code Address for the first mapping. A null value indicates that the storage is valid over the whole function (at least). If the value is non-null, the symbol storage may be used for other purposes at prior locations.

Returns:

the first use code Address or null

getFirstUseOffset NEW

protected int getFirstUseOffset()

Get the first code Address (expressed as a different in bytes from the starting address of the function) where this symbol's storage actually holds the value of the symbol. A value of 0 indicates that the storage is valid across the entire function. A negative value indicates the storage is an input to the function.

Returns:

the first-use offset of this symbol's storage

getHighFunction

public HighFunction getHighFunction()

Get the function model of which this symbol is a part.

Returns:

the HighFunction owning this symbol

setCategory NEW

protected void setCategory(int cat,
                           int index)

Set the category and associated index for this symbol. The category indicates a specific sub-class of symbols. Currently -1=none, 0=parameter, 1=equate

Parameters:

cat - is the category

index - is the category index ("slot" for parameters)

setTypeLock

public void setTypeLock(boolean typelock)

Set whether this symbol's data-type is considered "locked". If it is "locked", this symbol's data-type is considered unchangeable during decompilation. The data-type will be forced into the decompiler's model of the function to the extent possible.

Parameters:

typelock - is true if the data-type should be considered "locked".

setNameLock

public void setNameLock(boolean namelock)

Set whether this symbol's name is considered "locked". If it is "locked", the decompiler will use the name when labeling the storage described by this symbol.

Parameters:

namelock - is true if the name should be considered "locked".

isTypeLocked

public boolean isTypeLocked()

If this returns true, this symbol's data-type is "locked", meaning it is considered unchangeable during decompilation. The data-type will be forced into the decompiler's model of the function to the extent possible.

Returns:

true if the data-type is considered "locked".

isNameLocked

public boolean isNameLocked()

If this returns true, this symbol's name is "locked". meaning the decompiler is forced to use the name when labeling the storage described by this symbol.

Returns:

true if the name is considered "locked".

isIsolated NEW

public boolean isIsolated()

If this returns true, the decompiler will not speculatively merge this with other variables. Currently, being isolated is equivalent to being typelocked.

Returns:

true if this will not be merged with other variables

isReadOnly

public boolean isReadOnly()

Returns:

true if the symbol's value is considered read-only (by the decompiler)

isParameter NEW

public boolean isParameter()

Is this symbol a parameter for a function

Returns:

true if this is a parameter

getCategoryIndex NEW

public int getCategoryIndex()

For parameters (category=0), this method returns the position of the parameter within the function prototype.

Returns:

the category index for this symbol

isGlobal NEW

public boolean isGlobal()

Is this symbol in the global scope or some other global namespace

Returns:

true if this is global

isThisPointer NEW

public boolean isThisPointer()

Returns:

true if symbol is a "this" pointer for a class method

isHiddenReturn NEW

public boolean isHiddenReturn()

Returns:

true is symbol holds a pointer to where a function's return value should be stored

getFirstWholeMap NEW

public SymbolEntry getFirstWholeMap()

Returns:

the first mapping object attached to this symbol

getStorage NEW

public VariableStorage getStorage()

Returns:

the storage associated with this symbol (associated with the first mapping)

saveXMLHeader NEW

protected void saveXMLHeader(java.lang.StringBuilder buf)

Write out attributes for the base XML tag

Parameters:

buf - is the XML output stream

saveXML NEW

public void saveXML(java.lang.StringBuilder buf)

Save the symbol description as a tag to the XML stream. This does NOT save the mappings.

Parameters:

buf - is the XML stream

restoreXMLHeader NEW

protected void restoreXMLHeader(XmlElement symel)
                         throws PcodeXMLException

Throws:

PcodeXMLException

restoreXML NEW

public void restoreXML(XmlPullParser parser)
                throws PcodeXMLException

Restore this symbol object and its associated mappings from an XML description in the given stream.

Parameters:

parser - is the given XML stream

Throws:

PcodeXMLException - if the XML description is invalid

restoreMapSymXML NEW

public static HighSymbol restoreMapSymXML(XmlPullParser parser,
                                          boolean isGlobal,
                                          HighFunction high)
                                   throws PcodeXMLException

Restore a full HighSymbol from the next <mapsym> tag in the given XML stream. This method acts as an XML based HighSymbol factory, instantiating the correct class based on the particular tags.

Parameters:

parser - is the given XML stream

isGlobal - is true if this symbol is being read into a global scope

high - is the function model that will own the new symbol

Returns:

the new symbol

Throws:

PcodeXMLException - if the XML description is invalid

buildMapSymXML NEW

public static void buildMapSymXML(java.lang.StringBuilder res,
                                  HighSymbol sym)

Write out the given symbol with all its mapping as a <mapsym> tag to the given XML stream.

Parameters:

res - is the given XML stream

sym - is the given symbol