Description

Describes one function.

A function consists of one or more basic blocks. Exactly one block is special in that it serves as the entry point when this function is invoked from elsewhere; the only incoming inter-function edges are to this entry block. This function may have outgoing inter-function edges that represent invocations of other functions, and the targets of all such edges will be the entry block of another function. A function may also own zero or more data blocks consisting of a base address and size (type).

A function may exist as part of the partitioner's control flow graph, or in a detached state. When a function is represented by the control flow graph then it is in a frozen state, meaning that its basic blocks and data blocks cannot be adjusted adjusted; one must use the partitioner interface to do so.

Definition at line 41 of file Function.h.

#include <Rose/BinaryAnalysis/Partitioner2/Function.h>

Inheritance diagram for Rose::BinaryAnalysis::Partitioner2::Function:

[legend]

Collaboration diagram for Rose::BinaryAnalysis::Partitioner2::Function:

[legend]

Public Types
enum	Ownership { OWN_UNOWNED =0 , OWN_EXPLICIT , OWN_PROVISIONAL }
	Manner in which a function owns a block. More...

typedef FunctionPtr	Ptr
	Shared-ownership pointer for function.

Public Types inherited from Sawyer::Attribute::Storage< SyncTag >
typedef SynchronizationTraits< SyncTag >	Sync

Public Member Functions
rose_addr_t	address () const
	Read-only property: Entry address.

void	insertReasons (unsigned reasons)
	Insert additional function reason bits.

void	eraseReasons (unsigned reasons)
	Remove function reason bits.

const std::set< rose_addr_t > &	basicBlockAddresses () const
	Returns basic block addresses.

bool	ownsBasicBlock (rose_addr_t bblockVa) const
	Predicate to test whether a function owns a basic block address.

bool	insertBasicBlock (rose_addr_t bblockVa)
	Add a basic block to this function.

void	eraseBasicBlock (rose_addr_t bblockVa)
	Remove a basic block from this function.

const std::vector< DataBlockPtr > &	dataBlocks () const
	Returns data blocks owned by this function.

bool	insertDataBlock (const DataBlockPtr &)
	Add a data block to this function.

DataBlockPtr	eraseDataBlock (const DataBlockPtr &)
	Remove specified or equivalent data block from this function.

DataBlockPtr	dataBlockExists (const DataBlockPtr &) const
	Determine if this function contains the specified data block, or equivalent.

AddressIntervalSet	dataAddresses () const
	Addresses that are part of static data.

bool	isFrozen () const
	Determines whether a function is frozen.

bool	isThunk () const
	True if function is a thunk.

size_t	nBasicBlocks () const
	Number of basic blocks in the function.

size_t	nDataBlocks () const
	Number of data blocks in the function.

std::string	printableName () const
	A printable name for the function.

const Sawyer::Cached< bool > &	isNoop () const
	Cached results of function no-op analysis.


const std::string &	name () const
	Property: Optional function name.

void	name (const std::string &)
	Property: Optional function name.


const std::string &	demangledName () const
	Property: Optional demangled name.

void	demangledName (const std::string &)
	Property: Optional demangled name.


const std::string &	comment () const
	Property: Optional function comment.

void	comment (const std::string &)
	Property: Optional function comment.


const SourceLocation &	sourceLocation () const
	Property: Location of function definition in source code, if known.

void	sourceLocation (const SourceLocation &)
	Property: Location of function definition in source code, if known.


unsigned	reasons () const
	Property: Bit vector of function reasons.

void	reasons (unsigned)
	Property: Bit vector of function reasons.


const std::string &	reasonComment () const
	Property: Additional comment for why function was detected.

void	reasonComment (const std::string &)
	Property: Additional comment for why function was detected.


InstructionSemantics::BaseSemantics::SValuePtr	stackDelta () const
	Property: Stack delta.

int64_t	stackDeltaConcrete () const
	Property: Stack delta.


InstructionSemantics::BaseSemantics::SValuePtr	stackDeltaOverride () const
	Property: Stack delta override.

void	stackDeltaOverride (const InstructionSemantics::BaseSemantics::SValuePtr &delta)
	Property: Stack delta override.


const StackDelta::Analysis &	stackDeltaAnalysis () const
	Property: Stack delta analysis results.

StackDelta::Analysis &	stackDeltaAnalysis ()
	Property: Stack delta analysis results.


const CallingConvention::Analysis &	callingConventionAnalysis () const
	Property: Calling convention analysis results.

CallingConvention::Analysis &	callingConventionAnalysis ()
	Property: Calling convention analysis results.


CallingConvention::DefinitionPtr	callingConventionDefinition ()
	Property: Best calling convention definition.

void	callingConventionDefinition (const CallingConvention::DefinitionPtr &)
	Property: Best calling convention definition.

Public Member Functions inherited from Sawyer::SharedObject
	SharedObject ()
	Default constructor.

	SharedObject (const SharedObject &)
	Copy constructor.

virtual	~SharedObject ()
	Virtual destructor.

SharedObject &	operator= (const SharedObject &)
	Assignment.

Public Member Functions inherited from Sawyer::Attribute::Storage< SyncTag >
	Storage ()
	Default constructor.

	Storage (const Storage &other)
	Copy constructor.

Storage &	operator= (const Storage &other)
	Assignment operator.

bool	attributeExists (Id id) const
	Check attribute existence.

void	eraseAttribute (Id id)
	Erase an attribute.

void	clearAttributes ()
	Erase all attributes.

template<typename T >
void	setAttribute (Id id, const T &value)
	Store an attribute.

template<typename T >
bool	setAttributeMaybe (Id id, const T &value)
	Store an attribute if not already present.

template<typename T >
T	getAttribute (Id id) const
	Get an attribute that is known to exist.

template<typename T >
Sawyer::Optional< T >	getAttributeMaybe (const Id id) const
	Return an attribute if it exists, or else nothing.

template<typename T >
T	attributeOrElse (Id id, const T &dflt) const
	Return an attribute or a specified value.

template<typename T >
T	attributeOrDefault (Id id) const
	Return an attribute or a default-constructed value.

template<typename T >
Sawyer::Optional< T >	optionalAttribute (Id id) const
	Return the attribute as an optional value.

size_t	nAttributes () const
	Number of attributes stored.

std::vector< Id >	attributeIds () const
	Returns ID numbers for all IDs stored in this container.

Static Public Member Functions

static Ptr	instance (rose_addr_t entryVa, const std::string &name="", unsigned reasons=0)
	Static allocating constructor.

static Ptr	instance (rose_addr_t entryVa, unsigned reasons)
	Static allocating constructor.

Protected Member Functions
	Function (rose_addr_t entryVa, const std::string &name, unsigned reasons)

Member Typedef Documentation

◆ Ptr

typedef FunctionPtr Rose::BinaryAnalysis::Partitioner2::Function::Ptr

Shared-ownership pointer for function.

Definition at line 50 of file Function.h.

Member Enumeration Documentation

◆ Ownership

enum Rose::BinaryAnalysis::Partitioner2::Function::Ownership

Manner in which a function owns a block.

Enumerator
OWN_UNOWNED	Function does not own the block.
OWN_EXPLICIT	Function owns the block explicitly, the normal ownership.
OWN_PROVISIONAL	Function might own the block in the future.

Definition at line 44 of file Function.h.

Member Function Documentation

◆ instance() [1/2]

static Ptr Rose::BinaryAnalysis::Partitioner2::Function::instance	(	rose_addr_t	entryVa,
		const std::string &	name = `""`,
		unsigned	reasons = `0`
	)

static

Static allocating constructor.

Creates a new function having the specified characteristics.

◆ instance() [2/2]

static Ptr Rose::BinaryAnalysis::Partitioner2::Function::instance	(	rose_addr_t	entryVa,
		unsigned	reasons
	)

static

Static allocating constructor.

Creates a new function having the specified characteristics.

◆ address()

rose_addr_t Rose::BinaryAnalysis::Partitioner2::Function::address ( ) const

Read-only property: Entry address.

The entry address also serves as an identifier for the function since the CFG can only hold one function per entry address. Detached functions need not have unique entry addresses.

◆ name() [1/2]

const std::string & Rose::BinaryAnalysis::Partitioner2::Function::name ( ) const

Property: Optional function name.

This is the official name. See also demangledName, which can also return the value of this Naming tips property.

◆ name() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Function::name ( const std::string & )

Property: Optional function name.

This is the official name. See also demangledName, which can also return the value of this Naming tips property.

◆ demangledName() [1/2]

const std::string & Rose::BinaryAnalysis::Partitioner2::Function::demangledName ( ) const

Property: Optional demangled name.

This property holds the override string to use as the demangled name. If set to the empty string, then reading this property returns the true Naming tips instead.

◆ demangledName() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Function::demangledName ( const std::string & )

Property: Optional demangled name.

This property holds the override string to use as the demangled name. If set to the empty string, then reading this property returns the true Naming tips instead.

◆ comment() [1/2]

const std::string & Rose::BinaryAnalysis::Partitioner2::Function::comment ( ) const

Property: Optional function comment.

Comments are multi-line, plain-text (not HTML), ASCII.

◆ comment() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Function::comment ( const std::string & )

Property: Optional function comment.

Comments are multi-line, plain-text (not HTML), ASCII.

◆ reasons() [1/2]

unsigned Rose::BinaryAnalysis::Partitioner2::Function::reasons ( ) const

Property: Bit vector of function reasons.

These are SgAsmFunction::FunctionReason bits.

◆ reasons() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Function::reasons ( unsigned )

Property: Bit vector of function reasons.

These are SgAsmFunction::FunctionReason bits.

◆ insertReasons()

void Rose::BinaryAnalysis::Partitioner2::Function::insertReasons ( unsigned reasons )

Insert additional function reason bits.

The high-order bits 16 bits are OR'd into the reasons property, while the low-order 16 bits given in the argument replace the low-order 16 bits stored in the reasons property.

◆ eraseReasons()

void Rose::BinaryAnalysis::Partitioner2::Function::eraseReasons ( unsigned reasons )

Remove function reason bits.

Removes the high-order 16 bits that appear in the argument from the reasons property. The low-order 16 bits are all cleared if any of the low-order 16 bits of the argument are set.

◆ basicBlockAddresses()

const std::set< rose_addr_t > & Rose::BinaryAnalysis::Partitioner2::Function::basicBlockAddresses ( ) const

Returns basic block addresses.

Because functions can exist in a detatched state, a function stores basic block addresses rather than basic blocks. This allows a function to indicate which blocks will be ultimately part of its definition without requiring that the blocks actually exist. When a detached function is inserted into the CFG then basic block placeholders will be created for any basic blocks that don't exist in the CFG (see Partitioner::attachFunction).

◆ insertBasicBlock()

bool Rose::BinaryAnalysis::Partitioner2::Function::insertBasicBlock ( rose_addr_t bblockVa )

Add a basic block to this function.

This method does not adjust the partitioner CFG. Basic blocks cannot be added by this method when this function is attached to the CFG since it would cause the CFG to become outdated with respect to this function, but as long as the function is detached blocks can be inserted and removed arbitrarily. If the specified address is already part of the function then it is not added a second time.

Returns true if the block is inserted, false if the block was already part of this function.

◆ eraseBasicBlock()

void Rose::BinaryAnalysis::Partitioner2::Function::eraseBasicBlock ( rose_addr_t bblockVa )

Remove a basic block from this function.

This method does not adjust the partitioner CFG. Basic blocks cannot be removed by this method when this function is attached to the CFG since it would cause the CFG to become outdated with respect to this function, but as long as the function is detached blocks can be inserted and removed arbitrarily. If the specified address is not a basic block address for this function then this is a no-op. Removing the function's entry address is never permitted.

◆ dataBlocks()

const std::vector< DataBlockPtr > & Rose::BinaryAnalysis::Partitioner2::Function::dataBlocks ( ) const

Returns data blocks owned by this function.

Returns the data blocks that are owned by this function in order of their starting address.

◆ insertDataBlock()

bool Rose::BinaryAnalysis::Partitioner2::Function::insertDataBlock ( const DataBlockPtr & )

Add a data block to this function.

This method does not adjust the partitioner CFG. Data blocks cannot be added by this method when this function is attached to the CFG since it would cause the CFG to become outdated with respect to this function, but as long as the function is detached blocks can be inserted and removed arbitrarily. The specified data block cannot be a null pointer. If the data block is already owned by this function then nothing happens and this method returns false; otherwise the data block is inserted and the method returns true.

◆ eraseDataBlock()

DataBlockPtr Rose::BinaryAnalysis::Partitioner2::Function::eraseDataBlock ( const DataBlockPtr & )

Remove specified or equivalent data block from this function.

If this function is in a detached state (i.e., not part of the CFG/AUM) then the specified data block or equivalent data block is removed from this function. Returns the data block that was erased, or null if none was erased.

It is an error to invoke this method on function that is attached to the CFG/AUM, for which isFrozen returns true. This method is a no-op if the specified data block is a null pointer.

◆ dataBlockExists()

DataBlockPtr Rose::BinaryAnalysis::Partitioner2::Function::dataBlockExists ( const DataBlockPtr & ) const

Determine if this function contains the specified data block, or equivalent.

If this function owns the specified data block or an equivalent data block then this method returns a pointer to the existing data block, otherwise it returns the null pointer.

Thread safety: This method is not thread safe.

◆ dataAddresses()

AddressIntervalSet Rose::BinaryAnalysis::Partitioner2::Function::dataAddresses ( ) const

Addresses that are part of static data.

Returns all addresses that are part of static data.

Thread safety: This method is not thread safe.

◆ isFrozen()

bool Rose::BinaryAnalysis::Partitioner2::Function::isFrozen ( ) const

Determines whether a function is frozen.

The ownership relations (instructions, basic blocks, and data blocks) cannot be adjusted while a function is in a frozen state. All functions that are represented in the control flow graph are in a frozen state; detaching a function from the CFG thaws it.

◆ isThunk()

bool Rose::BinaryAnalysis::Partitioner2::Function::isThunk ( ) const

True if function is a thunk.

This function is a thunk if it is marked as such in its reason codes via SgAsmFunction::FUNC_THUNK and it has exactly one basic block.

See also, Partitioner::functionIsThunk that is a stronger predicate and also returns the address of the thunk target.

◆ stackDelta()

InstructionSemantics::BaseSemantics::SValuePtr Rose::BinaryAnalysis::Partitioner2::Function::stackDelta ( ) const

Property: Stack delta.

The set or computed stack delta. If a stack delta override has been set (stackDeltaOverride) then that value is returned. Otherwise, if the stack delta analysis has been run and a stack delta is known, it is returned. Otherwise a null pointer is returned. Calling this method returns previously computed values rather than running a potentially expensive analysis.

◆ stackDeltaConcrete()

int64_t Rose::BinaryAnalysis::Partitioner2::Function::stackDeltaConcrete ( ) const

Property: Stack delta.

The set or computed stack delta. If a stack delta override has been set (stackDeltaOverride) then that value is returned. Otherwise, if the stack delta analysis has been run and a stack delta is known, it is returned. Otherwise a null pointer is returned. Calling this method returns previously computed values rather than running a potentially expensive analysis.

◆ stackDeltaOverride() [1/2]

InstructionSemantics::BaseSemantics::SValuePtr Rose::BinaryAnalysis::Partitioner2::Function::stackDeltaOverride ( ) const

Property: Stack delta override.

This is the value returned by stackDelta in preference to using the stack delta analysis results. It allows a user to override the stack delta analysis. The partitioner will not run stack delta analysis if an override value is set.

◆ stackDeltaOverride() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Function::stackDeltaOverride ( const InstructionSemantics::BaseSemantics::SValuePtr & delta )

Property: Stack delta override.

This is the value returned by stackDelta in preference to using the stack delta analysis results. It allows a user to override the stack delta analysis. The partitioner will not run stack delta analysis if an override value is set.

◆ stackDeltaAnalysis() [1/2]

const StackDelta::Analysis & Rose::BinaryAnalysis::Partitioner2::Function::stackDeltaAnalysis ( ) const

Property: Stack delta analysis results.

This property holds the results from stack delta analysis. It contains the stack entry and exit values for each basic block computed from data flow, and the overall stack delta for the function. The analysis is not updated by this class; objects of this class only store the results provided by something else.

The hasResults and didConverge methods invoked on the return value will tell you whether an analysis has run and whether the results are valid, respectively.

◆ stackDeltaAnalysis() [2/2]

StackDelta::Analysis & Rose::BinaryAnalysis::Partitioner2::Function::stackDeltaAnalysis ( )

Property: Stack delta analysis results.

This property holds the results from stack delta analysis. It contains the stack entry and exit values for each basic block computed from data flow, and the overall stack delta for the function. The analysis is not updated by this class; objects of this class only store the results provided by something else.

The hasResults and didConverge methods invoked on the return value will tell you whether an analysis has run and whether the results are valid, respectively.

◆ callingConventionAnalysis() [1/2]

const CallingConvention::Analysis & Rose::BinaryAnalysis::Partitioner2::Function::callingConventionAnalysis ( ) const

Property: Calling convention analysis results.

This property holds the results from calling convention analysis. It contains information about what registers and stack locations are accessed and whether they serve as inputs or outputs and which registers are used but restored before returning (callee-saved). It also stores a concrete stack delta. The analysis is not updated by this class; objects of this class only store the results provided by something else.

The analysis itself does not fully describe a calling convention since a function might not use all features of the calling convention. For instance, a no-op function could match any number of calling convention definitions.

The hasResults and didConverge methods invoked on the return value will tell you whether an analysis has run and whether the results are valid, respectively.

◆ callingConventionAnalysis() [2/2]

CallingConvention::Analysis & Rose::BinaryAnalysis::Partitioner2::Function::callingConventionAnalysis ( )

Property: Calling convention analysis results.

This property holds the results from calling convention analysis. It contains information about what registers and stack locations are accessed and whether they serve as inputs or outputs and which registers are used but restored before returning (callee-saved). It also stores a concrete stack delta. The analysis is not updated by this class; objects of this class only store the results provided by something else.

The analysis itself does not fully describe a calling convention since a function might not use all features of the calling convention. For instance, a no-op function could match any number of calling convention definitions.

The hasResults and didConverge methods invoked on the return value will tell you whether an analysis has run and whether the results are valid, respectively.

◆ callingConventionDefinition() [1/2]

CallingConvention::DefinitionPtr Rose::BinaryAnalysis::Partitioner2::Function::callingConventionDefinition ( )

Property: Best calling convention definition.

This is the best calling convention definition for this function. Calling conventions have two parts: (1) the behavior of the function such as which locations serve as inputs (read-before-write) and outputs (write-last), and callee-saved locations (read-before-write and write-last and same initial and final value), and (2) a list of well-known calling convention definitions that match the function's behavior. More than one definition can match. This property holds one defintion which is usually the "best" one.

◆ callingConventionDefinition() [2/2]

void Rose::BinaryAnalysis::Partitioner2::Function::callingConventionDefinition ( const CallingConvention::DefinitionPtr & )

Property: Best calling convention definition.

This is the best calling convention definition for this function. Calling conventions have two parts: (1) the behavior of the function such as which locations serve as inputs (read-before-write) and outputs (write-last), and callee-saved locations (read-before-write and write-last and same initial and final value), and (2) a list of well-known calling convention definitions that match the function's behavior. More than one definition can match. This property holds one defintion which is usually the "best" one.

◆ printableName()

std::string Rose::BinaryAnalysis::Partitioner2::Function::printableName ( ) const

A printable name for the function.

Returns a string like 'function 0x10001234 "main"'. The function name is not included if this function has neither a demangled name nor a true name. The demangledName overrides the true Naming tips.

◆ isNoop()

const Sawyer::Cached< bool > & Rose::BinaryAnalysis::Partitioner2::Function::isNoop ( ) const

Cached results of function no-op analysis.

If a value is cached, then the analysis has run and the cached value is true if the analysis proved that the function is a no-op.

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

Function.h

Description

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Typedef Documentation

◆ Ptr

Member Enumeration Documentation

◆ Ownership

Member Function Documentation

◆ instance() [1/2]

◆ instance() [2/2]

◆ address()

◆ name() [1/2]

◆ name() [2/2]

◆ demangledName() [1/2]

◆ demangledName() [2/2]

◆ comment() [1/2]

◆ comment() [2/2]

◆ reasons() [1/2]

◆ reasons() [2/2]

◆ insertReasons()

◆ eraseReasons()

◆ basicBlockAddresses()

◆ insertBasicBlock()

◆ eraseBasicBlock()

◆ dataBlocks()

◆ insertDataBlock()

◆ eraseDataBlock()

◆ dataBlockExists()

◆ dataAddresses()

◆ isFrozen()

◆ isThunk()

◆ stackDelta()

◆ stackDeltaConcrete()

◆ stackDeltaOverride() [1/2]

◆ stackDeltaOverride() [2/2]

◆ stackDeltaAnalysis() [1/2]

◆ stackDeltaAnalysis() [2/2]

◆ callingConventionAnalysis() [1/2]

◆ callingConventionAnalysis() [2/2]

◆ callingConventionDefinition() [1/2]

◆ callingConventionDefinition() [2/2]

◆ printableName()

◆ isNoop()