Varnode Class Reference

A low-level variable or contiguous set of bytes described by an Address and a size. More...

#include <varnode.hh>

Collaboration diagram for Varnode:

Public Types
enum	varnode_flags {   mark = 0x01, constant = 0x02, annotation = 0x04, input = 0x08,   written = 0x10, insert = 0x20, implied = 0x40, explict = 0x80,   typelock = 0x100, namelock = 0x200, nolocalalias = 0x400, volatil = 0x800,   spacebase_placeholder = 0x1000, externref = 0x2000, readonly = 0x4000, persist = 0x8000,   addrtied = 0x10000, unaffected = 0x20000, spacebase = 0x40000, indirectonly = 0x80000,   directwrite = 0x100000, addrforce = 0x200000, mapped = 0x400000, indirect_creation = 0x800000,   return_address = 0x1000000, coverdirty = 0x2000000, precislo = 0x4000000, precishi = 0x8000000,   indirectstorage = 0x10000000, hiddenretparm = 0x20000000, incidental_copy = 0x40000000, auto_live = 0x80000000 }
enum	addl_flags {   activeheritage = 0x01, writemask = 0x02, vacconsume = 0x04, lisconsume = 0x08,   ptrcheck = 0x10, ptrflow = 0x20, unsignedprint = 0x40, stack_store = 0x80,   locked_input = 0x100 }
	Additional boolean properties on a Varnode. More...

Public Member Functions
void	setHigh (HighVariable *tv, int2 mg)
	Set the HighVariable owning this Varnode.
const Address &	getAddr (void) const
	Get the storage Address.
AddrSpace *	getSpace (void) const
	Get the AddrSpace storing this Varnode.
uintb	getOffset (void) const
	Get the offset (within its AddrSpace) where this is stored.
int4	getSize (void) const
	Get the number of bytes this Varnode stores.
int2	getMergeGroup (void) const
	Get the forced merge group of this Varnode.
PcodeOp *	getDef (void)
	Get the defining PcodeOp of this Varnode.
const PcodeOp *	getDef (void) const
	Get the defining PcodeOp.
HighVariable *	getHigh (void) const
	Get the high-level variable associated with this Varnode. More...
SymbolEntry *	getSymbolEntry (void) const
	Get symbol and scope information associated with this Varnode.
uint4	getFlags (void) const
	Get all the boolean attributes.
Datatype *	getType (void) const
	Get the Datatype associated with this Varnode.
void	setTempType (Datatype *t) const
	Set the temporary Datatype.
Datatype *	getTempType (void) const
	Get the temporary Datatype (used during type propagation)
void	setValueSet (ValueSet *v) const
	Set the temporary ValueSet record.
ValueSet *	getValueSet (void) const
	Get the temporary ValueSet record.
uint4	getCreateIndex (void) const
	Get the creation index.
Cover *	getCover (void) const
	Get Varnode coverage information.
list< PcodeOp * >::const_iterator	beginDescend (void) const
	Get iterator to list of syntax tree descendants (reads)
list< PcodeOp * >::const_iterator	endDescend (void) const
	Get the end iterator to list of descendants.
uintb	getConsume (void) const
	Get mask of consumed bits.
void	setConsume (uintb val)
	Set the mask of consumed bits (used by dead-code algorithm)
bool	isConsumeList (void) const
	Get marker used by dead-code algorithm.
bool	isConsumeVacuous (void) const
	Get marker used by dead-code algorithm.
void	setConsumeList (void)
	Set marker used by dead-code algorithm.
void	setConsumeVacuous (void)
	Set marker used by dead-code algorithm.
void	clearConsumeList (void)
	Clear marker used by dead-code algorithm.
void	clearConsumeVacuous (void)
	Clear marker used by dead-code algorithm.
PcodeOp *	loneDescend (void) const
	Return unique reading PcodeOp, or null if there are zero or more than 1. More...
Address	getUsePoint (const Funcdata &fd) const
	Get Address when this Varnode first comes into scope. More...
int4	printRawNoMarkup (ostream &s) const
	Print a simple identifier for the Varnode. More...
void	printRaw (ostream &s) const
	Print a simple identifier plus additional info identifying Varnode with SSA form. More...
void	printCover (ostream &s) const
	Print raw coverage info about the Varnode. More...
void	printInfo (ostream &s) const
	Print raw attribute info about the Varnode. More...
	Varnode (int4 s, const Address &m, Datatype *dt)
	Construct a free Varnode. More...
bool	operator< (const Varnode &op2) const
	Comparison operator on Varnode. More...
bool	operator== (const Varnode &op2) const
	Equality operator. More...
bool	operator!= (const Varnode &op2) const
	Inequality operator.
	~Varnode (void)
	Destructor. More...
bool	intersects (const Varnode &op) const
	Return true if the storage locations intersect. More...
bool	intersects (const Address &op2loc, int4 op2size) const
	Check intersection against an Address range. More...
int4	contains (const Varnode &op) const
	Return info about the containment of op in this. More...
int4	characterizeOverlap (const Varnode &op) const
	Return 0, 1, or 2 for "no overlap", "partial overlap", "identical storage".
int4	overlap (const Varnode &op) const
	Return relative point of overlap between two Varnodes. More...
int4	overlap (const Address &op2loc, int4 op2size) const
	Return relative point of overlap with Address range. More...
uintb	getNZMask (void) const
	Get the mask of bits within this that are known to be zero.
int4	termOrder (const Varnode *op) const
	Compare two Varnodes based on their term order. More...
void	printRawHeritage (ostream &s, int4 depth) const
	Print a simple SSA subtree rooted at this. More...
bool	isAnnotation (void) const
	Is this an annotation?
bool	isImplied (void) const
	Is this an implied variable?
bool	isExplicit (void) const
	Is this an explicitly printed variable?
bool	isConstant (void) const
	Is this a constant?
bool	isFree (void) const
	Is this free, not in SSA form?
bool	isInput (void) const
	Is this an SSA input node?
bool	isIllegalInput (void) const
	Is this an abnormal input to the function?
bool	isIndirectOnly (void) const
	Is this read only by INDIRECT operations?
bool	isExternalRef (void) const
	Is this storage location mapped by the loader to an external location?
bool	hasActionProperty (void) const
	Will this Varnode be replaced dynamically?
bool	isReadOnly (void) const
	Is this a read-only storage location?
bool	isVolatile (void) const
	Is this a volatile storage location?
bool	isPersist (void) const
	Does this storage location persist beyond the end of the function?
bool	isDirectWrite (void) const
	Is this value affected by a legitimate function input.
bool	isAddrTied (void) const
	Are all Varnodes at this storage location components of the same high-level variable?
bool	isAddrForce (void) const
	Is this value forced into a particular storage location?
bool	isAutoLive (void) const
	Is this varnode exempt from dead-code removal?
bool	isMapped (void) const
	Is there or should be formal symbol information associated with this?
bool	isUnaffected (void) const
	Is this a value that is supposed to be preserved across the function?
bool	isSpacebase (void) const
	Is this location used to store the base point for a virtual address space?
bool	isReturnAddress (void) const
	Is this storage for a calls return address?
bool	isPtrCheck (void) const
	Has this been checked as a constant pointer to a mapped symbol?
bool	isPtrFlow (void) const
	Does this varnode flow to or from a known pointer.
bool	isSpacebasePlaceholder (void) const
	Is this used specifically to track stackpointer values?
bool	hasNoLocalAlias (void) const
	Are there (not) any local pointers that might affect this?
bool	isMark (void) const
	Has this been visited by the current algorithm?
bool	isActiveHeritage (void) const
	Is this currently being traced by the Heritage algorithm?
bool	isStackStore (void) const
	Was this originally produced by an explicit STORE.
bool	isLockedInput (void) const
	Is always an input, even if unused.
bool	isIndirectZero (void) const
	Is this just a special placeholder representing INDIRECT creation?
bool	isExtraOut (void) const
	Is this Varnode created indirectly by a CALL operation?
bool	isPrecisLo (void) const
	Is this the low portion of a double precision value?
bool	isPrecisHi (void) const
	Is this the high portion of a double precision value?
bool	isIncidentalCopy (void) const
	Does this varnode get copied as a side-effect.
bool	isWriteMask (void) const
	Is this (not) considered a true write location when calculating SSA form?
bool	isUnsignedPrint (void) const
	Must this be printed as unsigned.
bool	isWritten (void) const
	Does this have a defining write operation?
bool	hasCover (void) const
	Does this have Cover information?
bool	hasNoDescend (void) const
	Return true if nothing reads this Varnode.
bool	constantMatch (uintb val) const
	Return true if this is a constant with value val.
int4	isConstantExtended (uintb &val) const
bool	isHeritageKnown (void) const
	Return true if this Varnode is linked into the SSA tree.
bool	isTypeLock (void) const
	Does this have a locked Datatype?
bool	isNameLock (void) const
	Does this have a locked name?
void	setActiveHeritage (void)
	Mark this as currently being linked into the SSA tree.
void	clearActiveHeritage (void)
	Mark this as not (actively) being linked into the SSA tree.
void	setMark (void) const
	Mark this Varnode for breadcrumb algorithms.
void	clearMark (void) const
	Clear the mark on this Varnode.
void	setDirectWrite (void)
	Mark this as directly affected by a legal input.
void	clearDirectWrite (void)
	Mark this as not directly affected by a legal input.
void	setAddrForce (void)
	Mark as forcing a value into this particular storage location.
void	clearAddrForce (void)
	Clear the forcing attribute.
void	setAutoLive (void)
	Mark varnode as exempt from dead-code removal.
void	clearAutoLive (void)
	Clear exemption for dead-code removal.
void	setImplied (void)
	Mark this as an implied variable in the final C source.
void	clearImplied (void)
	Clear the implied mark on this Varnode.
void	setExplicit (void)
	Mark this as an explicit variable in the final C source.
void	clearExplicit (void)
	Clear the explicit mark on this Varnode.
void	setReturnAddress (void)
	Mark as storage location for a return address.
void	clearReturnAddress (void)
	Clear return address attribute.
void	setPtrCheck (void)
	Set this as checked for a constant symbol reference.
void	clearPtrCheck (void)
	Clear the pointer check mark on this Varnode.
void	setPtrFlow (void)
	Set this as flowing to or from pointer.
void	clearPtrFlow (void)
	Indicate that this varnode is not flowing to or from pointer.
void	setSpacebasePlaceholder (void)
	Mark this as a special Varnode for tracking stackpointer values.
void	clearSpacebasePlaceholder (void)
	Clear the stackpointer tracking mark.
void	setPrecisLo (void)
	Mark this as the low portion of a double precision value.
void	clearPrecisLo (void)
	Clear the mark indicating a double precision portion.
void	setPrecisHi (void)
	Mark this as the high portion of a double precision value.
void	clearPrecisHi (void)
	Clear the mark indicating a double precision portion.
void	setWriteMask (void)
	Mark this as not a true write when computing SSA form.
void	clearWriteMask (void)
	Clear the mark indicating this is not a true write.
void	setUnsignedPrint (void)
	Force this to be printed as unsigned.
bool	updateType (Datatype *ct, bool lock, bool override)
	(Possibly) set the Datatype given various restrictions More...
void	setStackStore (void)
	Mark as produced by explicit CPUI_STORE.
void	setLockedInput (void)
	Mark as existing input, even if unused.
void	copySymbol (const Varnode *vn)
	Copy symbol info from vn. More...
void	copySymbolIfValid (const Varnode *vn)
	Copy symbol info from vn if constant value matches. More...
Datatype *	getLocalType (void) const
	Calculate type of Varnode based on local information. More...
bool	copyShadow (const Varnode *op2) const
	Are this and op2 copied from the same source? More...
void	saveXml (ostream &s) const
	Save a description of this as an XML tag. More...

Static Public Member Functions
static bool	comparePointers (const Varnode *a, const Varnode *b)
	Compare Varnodes as pointers.

Friends
class	VarnodeBank
class	Merge
class	Funcdata

Detailed Description

A low-level variable or contiguous set of bytes described by an Address and a size.

A Varnode is the fundemental variable in the p-code language model. A Varnode represents anything that holds data, including registers, stack locations, global RAM locations, and constants. It is described most simply as a storage location for some number of bytes, and is identified by

• an Address (an AddrSpace and an offset into that space) and
• a size in bytes

In its raw form, the Varnode is referred to as free, and this pair uniquely identifies the Varnode, as determined by its comparison operators. In terms of the Static Single Assignment (SSA) form for the decompiler analysis, the Varnode class also represents a node in the tree. In this case the Varnode is not free, and each individual write to a storage location, as per SSA form, creates a unique Varnode, which is represented by a separate instance, so there may be multiple Varnode instances with the same Address and size.

Member Enumeration Documentation

addl_flags

enum Varnode::addl_flags

Additional boolean properties on a Varnode.

Enumerator
activeheritage	The varnode is actively being heritaged.
writemask	Should not be considered a write in heritage calculation.
vacconsume	Vacuous consume.
lisconsume	In consume worklist.
ptrcheck	The Varnode value is NOT a pointer.
ptrflow	If this varnode flows to or from a pointer.
unsignedprint	Constant that must be explicitly printed as unsigned.
stack_store	Created by an explicit STORE.
locked_input	Input that exists even if its unused.

varnode_flags

enum Varnode::varnode_flags

There are a large number of boolean attributes that can be placed on a Varnode. Some are calculated and maintained by the friend classes Funcdata and VarnodeBank, and others can be set and cleared publicly by separate subsystems.

Enumerator
mark	Prevents infinite loops.
constant	The varnode is constant.
annotation	This varnode is an annotation and has no dataflow.
input	This varnode has no ancestor.
written	This varnode has a defining op (def is nonzero)
insert	This varnode has been inserted in a tree This means the varnode is the output of an op or The output is a constant or the output is an input
implied	This varnode is a temporary variable.
explict	This varnode CANNOT be a temporary variable.
typelock	The Dataype of the Varnode is locked.
namelock	The Name of the Varnode is locked.
nolocalalias	There are no aliases pointing to this varnode.
volatil	This varnode's value is volatile.
spacebase_placeholder	This varnode is inserted artificially to track a register value at a specific point in the code
externref	Varnode address is specially mapped by the loader.
readonly	Varnode is stored at a readonly location.
persist	Persists after (and before) function.
addrtied	High-level variable is tied to address.
unaffected	Input which is unaffected by the function.
spacebase	This is a base register for an address space.
indirectonly	If all uses of illegalinput varnode are inputs to INDIRECT.
directwrite	(could be) Directly affected by a valid input
addrforce	Varnode is used to force variable into an address.
mapped	Varnode has a database entry associated with it.
indirect_creation	The value in this Varnode is created indirectly.
return_address	Is the varnode storage for a return address.
coverdirty	Cover is not upto date.
precislo	Is this Varnode the low part of a double precision value.
precishi	Is this Varnode the high part of a double precision value.
indirectstorage	Is this Varnode storing a pointer to the actual symbol.
hiddenretparm	Does this varnode point to the return value storage location.
incidental_copy	Do copies of this varnode happen as a side-effect.
auto_live	Is this varnode automatically considered live, never removed as dead-code.

Constructor & Destructor Documentation

Varnode()

Varnode::Varnode	(	int4	s,
		const Address &	m,
		Datatype *	dt
	)

Construct a free Varnode.

This is the constructor for making an unmanaged Varnode It creates a free Varnode with possibly a Datatype attribute. Most applications create Varnodes through the Funcdata interface

Parameters

s	is the size of the new Varnode
m	is the starting storage Address
dt	is the Datatype

~Varnode()

Varnode::~Varnode

(

void

)

Destructor.

Delete the Varnode object. This routine assumes all other cross-references have been removed.

Member Function Documentation

contains()

int4 Varnode::contains

(

const Varnode &

op

)

const

Return info about the containment of op in this.

Return various values depending on the containment of another Varnode within this. Return

• -1 if op.loc starts before -this-
• 0 if op is contained in -this-
• 1 if op.start is contained in -this-
• 2 if op.loc comes after -this- or
• 3 if op and -this- are in non-comparable spaces

  Parameters

  op	is the Varnode to test for containment

  Returns

  the integer containment code

copyShadow()

bool Varnode::copyShadow

(

const Varnode *

op2

)

const

Are this and op2 copied from the same source?

Make a local determination if this and op2 hold the same value. We check if there is a common ancester for which both this and op2 are created from a direct sequence of COPY operations. NOTE: This is a transitive relationship

Parameters

op2	is the Varnode to compare to this

Returns

true if the Varnodes are copied from a common ancestor

copySymbol()

void Varnode::copySymbol

(

const Varnode *

vn

)

Copy symbol info from vn.

Copy any symbol and type information from -vn- into this

Parameters

vn	is the Varnode to copy from

copySymbolIfValid()

void Varnode::copySymbolIfValid

(

const Varnode *

vn

)

Copy symbol info from vn if constant value matches.

Symbol information (if present) is copied from the given constant Varnode into this, which also must be constant, but only if the two constants are close in the sense of an equate.

Parameters

vn	is the given constant Varnode

getHigh()

HighVariable * Varnode::getHigh

(

void

)

const

Get the high-level variable associated with this Varnode.

During the course of analysis Varnodes are merged into high-level variables that are intended to be closer to the concept of variables in C source code. For a large portion of the decompiler analysis this concept hasn't been built yet, and this routine will return null. But after a certain point, every Varnode managed by the Funcdata object, with the exception of ones that are marked as annotations, is associated with some HighVariable and will return a non-null result.

Returns

the associated HighVariable

getLocalType()

Datatype * Varnode::getLocalType

(

void

)

const

Calculate type of Varnode based on local information.

Make an initial determination of the Datatype of this Varnode. If a Datatype is already set and locked return it. Otherwise look through all the read PcodeOps and the write PcodeOp to determine if the Varnode is getting used as an int, float, or pointer, etc. Throw an exception if no Datatype can be found at all.

Returns

the determined Datatype

getUsePoint()

Address Varnode::getUsePoint

(

const Funcdata &

fd

)

const

Get Address when this Varnode first comes into scope.

A Varnode can be defined as "coming into scope" at the Address of the first PcodeOp that writes to that storage location. Within SSA form this first-use address always exists and is unique if we consider inputs to come into scope at the start Address of the function they are in

Parameters

fd	is the Funcdata containing the tree

Returns

the first-use Address

intersects() [1/2]

bool Varnode::intersects

(

const Varnode &

op

)

const

Return true if the storage locations intersect.

Check whether the storage locations of two varnodes intersect

Parameters

op	is the Varnode to compare with this

Returns

true if the locations intersect

intersects() [2/2]

bool Varnode::intersects	(	const Address &	op2loc,
		int4	op2size
	)		const

Check intersection against an Address range.

Check if this intersects the given Address range

Parameters

op2loc	is the start of the range
op2size	is the size of the range in bytes

Returns

true if this intersects the range

isConstantExtended()

int4 Varnode::isConstantExtended

(

uintb &

val

)

const

Is this an (extended) constant

If this is a constant, or is extended (INT_ZEXT,INT_SEXT) from a constant, the value of the constant is passed back and a non-negative integer is returned, either:

• 0 for a normal constant Varnode
• 1 for a zero extension (INT_ZEXT) of a normal constant
• 2 for a sign extension (INT_SEXT) of a normal constant

  Parameters

  val	is a reference to the constant value that is passed back

  Returns

  the extension code (or -1 if this cannot be interpreted as a constant)

loneDescend()

PcodeOp * Varnode::loneDescend

(

void

)

const

Return unique reading PcodeOp, or null if there are zero or more than 1.

This is a convenience method for quickly finding the unique PcodeOp that reads this Varnode

Returns

only descendant (if there is 1 and ONLY 1) or null otherwise

operator<()

bool Varnode::operator<

(

const Varnode &

op2

)

const

Comparison operator on Varnode.

Compare two Varnodes

• First by storage location
• Second by size
• Then by defining PcodeOp SeqNum if appropriate

Input Varnodes come before written Varnodes Free Varnodes come after everything else

Parameters

op2	is the Varnode to compare this to

Returns

true if this is less than op2

operator==()

bool Varnode::operator==

(

const Varnode &

op2

)

const

Equality operator.

Determine if two Varnodes are equivalent. They must match

• Storage location
• Size
• Defining PcodeOp if it exists

Parameters

op2	is the Varnode to compare this to

Returns

true if they are equivalent

overlap() [1/2]

int4 Varnode::overlap

(

const Varnode &

op

)

const

Return relative point of overlap between two Varnodes.

Return whether Least Signifigant Byte of this occurs in op I.e. return

• 0 if it overlaps op's lsb
• 1 if it overlaps op's second lsb and so on

  Parameters

  op	is Varnode to test for overlap

  Returns

  the relative overlap point or -1

overlap() [2/2]

int4 Varnode::overlap	(	const Address &	op2loc,
		int4	op2size
	)		const

Return relative point of overlap with Address range.

Return whether Least Signifigant Byte of this occurs in an Address range I.e. return

• 0 if it overlaps op's lsb
• 1 if it overlaps op's second lsb and so on

  Parameters

  op2loc	is the starting Address of the range
  op2size	is the size of the range in bytes

  Returns

  the relative overlap point or -1

printCover()

void Varnode::printCover

(

ostream &

s

)

const

Print raw coverage info about the Varnode.

Print, to a stream, textual information about where this Varnode is in scope within its particular Funcdata. This amounts to a list of address ranges bounding the writes and reads of the Varnode

Parameters

s	is the output stream

printInfo()

void Varnode::printInfo

(

ostream &

s

)

const

Print raw attribute info about the Varnode.

Print boolean attribute information about this as keywords to a stream

Parameters

s	is the output stream

printRaw()

void Varnode::printRaw

(

ostream &

s

)

const

Print a simple identifier plus additional info identifying Varnode with SSA form.

Print textual information about this Varnode including a base identifier along with enough size and attribute information to uniquely identify the Varnode within a text SSA listing In particular, the identifiers have either "i" or defining op SeqNum information appended to them in parantheses.

Parameters

s	is the output stream

printRawHeritage()

void Varnode::printRawHeritage	(	ostream &	s,
		int4	depth
	)		const

Print a simple SSA subtree rooted at this.

Recursively print a terse textual representation of the data-flow (SSA) tree rooted at this Varnode

Parameters

s	is the output stream
depth	is the current depth of the tree we are at

printRawNoMarkup()

int4 Varnode::printRawNoMarkup

(

ostream &

s

)

const

Print a simple identifier for the Varnode.

Print to the stream either the name of the Varnode, such as a register name, if it exists or print a shortcut character representing the AddrSpace and a hex representation of the offset. This function also computes and returns the expected size of the identifier it prints to facilitate the printing of size modifiers by other print routines

Parameters

s	is the output stream

Returns

the expected size

saveXml()

void Varnode::saveXml

(

ostream &

s

)

const

Save a description of this as an XML tag.

Write an XML tag, <addr>, with at least the following attributes:

• space describes the AddrSpace
• offset of the Varnode within the space
• size of the Varnode is bytes

Additionally the tag will contain other optional attributes.

Parameters

s	is the stream to write the tag to

termOrder()

int4 Varnode::termOrder

(

const Varnode *

op

)

const

Compare two Varnodes based on their term order.

Compare term order of two Varnodes. Used in Term Rewriting strategies to order operands of commutative ops

Parameters

op	is the Varnode to order against this

Returns

-1 if this comes before op, 1 if op before this, or 0

updateType()

bool Varnode::updateType	(	Datatype *	ct,
		bool	lock,
		bool	override
	)

(Possibly) set the Datatype given various restrictions

Change the Datatype and lock state associated with this Varnode if various conditions are met

• Don't change a previously locked Datatype (unless override flag is true)
• Don't consider an undefined type to be locked
• Don't change to an identical Datatype

  Parameters

  ct	is the Datatype to change to
  lock	is true if the new Datatype should be locked
  override	is true if an old lock should be overridden

  Returns

  true if the Datatype or the lock setting was changed

---

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

• varnode.hh
• varnode.cc