Description

Finding and describing source-level variables.

This namespace contains facilities for finding source-level variables in binaries and describing those variables. For instance, it can analyze a function and detect stack locations that are likely to represent variables that appear in the source language from which the binary was compiled.

Binaries generally don't represent source-level variables in a straightforward manner. Some things to watch out for are:

The compiler can elide a source-level variable if it determines that it's not necessary in the binary. I.e., the compiler can completely optimize away a variable that is written to but never read. In GDB one often sees the string "<optimized out>" in this kind of situation.

The compiler can give the same address to two or more source-level variables if one or more of them is read without being initialized. This is undefined behavior (UB) in C and C++ and the compiler is free to do anything it wants in these situations.

The compiler might not allocate stack storage for a local variable. E.g., if enough general purpose registers are available the compiler might use a register to store the local variable.

The scope of the local variable in the source language does not generally match the lifetime of the storage location for that variable in the binary. For instance, the compiler might decide that the same storage location can be used for two or more variables with non-overlapping lifetimes. The binary analysis sees this as a single variable.

Variables that the compiler might initially store in registers (such as function arguments) are often spilled to the stack in order to make those registers available for other purposes within the function.

A source-level variable might exist at more than one location in the binary. A common situation is when the compiler decides to move the variable from a stack location into a register for part of the function and then optionally moves it back to the stack.

Writes to a stack location that are not followed by reads can be elided, in which case the analysis would indicate that there was no subsequent write.

Many other caveats.

Classes
class	BaseVariable
	Base class describing a source-level variable. More...

class	GlobalVariable
	Description of a global variable. More...

class	InstructionAccess
	Information about how an instruction accesses a variable. More...

class	StackFrame
	Information about a stack frame. More...

class	StackVariable
	Description of a local stack variable within a function. More...

class	VariableFinder
	Analysis to find variable locations. More...

Typedefs
using	OffsetToAddress = std::map< int64_t, AddressSet >
	Mapping from stack offsets to address sets.

using	AddressToAddresses = std::map< Address, AddressSet >
	Mapping from addresses to address sets.

using	OffsetInterval = Sawyer::Container::Interval< int64_t >
	Interval of signed offsets.

using	AccessFlags = Sawyer::BitFlags< Access, uint64_t >
	Whether a variable is read and/or written by an instruction.

using	GlobalVariables = Sawyer::Container::IntervalMap< AddressInterval, GlobalVariable >
	Maps virtual addresses to global variables.

using	StackVariables = Sawyer::Container::IntervalMap< OffsetInterval, StackVariable >
	Collection of local variables organized by stack offsets.


using	VariableFinderPtr = std::shared_ptr< VariableFinder >
	Shared ownership pointer to VariableFinder.

using	VariableFinderConstPtr = std::shared_ptr< const VariableFinder >
	Shared ownership pointer to VariableFinder.

Enumerations
enum class	Access { READ = 0x0001 , WRITE = 0x0002 }
	Whether a variable is read or written. More...

Functions
void	initDiagnostics ()
	Initialize diagnostic output.

void	initNamespace ()
	Initialize the namespace.

std::string	offsetStr (int64_t offset)
	Format a stack offset as a string.

std::string	sizeStr (uint64_t size)
	Format size as a string.

void	erase (GlobalVariables &, const AddressInterval &toErase)
	Erase some global variables.

void	print (const GlobalVariables &, const Partitioner2::PartitionerConstPtr &, std::ostream &out, const std::string &prefix="")
	Print info about multiple global variables.

AddressInterval	isInconsistent (const GlobalVariables &, Sawyer::Message::Stream &)
	Check that the map is consistent.

std::ostream &	operator<< (std::ostream &, const InstructionAccess &)

void	print (const StackVariables &, const Partitioner2::PartitionerConstPtr &, std::ostream &out, const std::string &prefix="")
	Print info about multiple local variables.

Variables
Sawyer::Message::Facility	mlog
	Diagnostic facility for variables.

Sawyer::Attribute::Id	ATTR_FRAME_SIZE

Sawyer::Attribute::Id	ATTR_LOCAL_VARS

Sawyer::Attribute::Id	ATTR_GLOBAL_VARS

Typedef Documentation

◆ VariableFinderPtr

using Rose::BinaryAnalysis::Variables::VariableFinderPtr = typedef std::shared_ptr<VariableFinder>

Shared ownership pointer to VariableFinder.

Definition at line 33 of file Rose/BinaryAnalysis/Variables/BasicTypes.h.

◆ VariableFinderConstPtr

using Rose::BinaryAnalysis::Variables::VariableFinderConstPtr = typedef std::shared_ptr<const VariableFinder>

Shared ownership pointer to VariableFinder.

Definition at line 34 of file Rose/BinaryAnalysis/Variables/BasicTypes.h.

◆ OffsetToAddress

using Rose::BinaryAnalysis::Variables::OffsetToAddress = typedef std::map<int64_t , AddressSet>

Mapping from stack offsets to address sets.

Definition at line 38 of file Rose/BinaryAnalysis/Variables/BasicTypes.h.

◆ AddressToAddresses

using Rose::BinaryAnalysis::Variables::AddressToAddresses = typedef std::map<Address, AddressSet>

Mapping from addresses to address sets.

Definition at line 41 of file Rose/BinaryAnalysis/Variables/BasicTypes.h.

◆ OffsetInterval

using Rose::BinaryAnalysis::Variables::OffsetInterval = typedef Sawyer::Container::Interval<int64_t>

Interval of signed offsets.

Definition at line 44 of file Rose/BinaryAnalysis/Variables/BasicTypes.h.

◆ AccessFlags

using Rose::BinaryAnalysis::Variables::AccessFlags = typedef Sawyer::BitFlags<Access, uint64_t>

Whether a variable is read and/or written by an instruction.

Definition at line 53 of file Rose/BinaryAnalysis/Variables/BasicTypes.h.

◆ GlobalVariables

using Rose::BinaryAnalysis::Variables::GlobalVariables = typedef Sawyer::Container::IntervalMap<AddressInterval, GlobalVariable>

Maps virtual addresses to global variables.

The global variable will be represented in the map at all addresses that the global variable could occupy. E.g., if global variable "g1" starts at 0x4000 and can be up to 1k 4-byte integers, then a record will exist in the map at all addresses from 0x4000 (inclusive) to 0x4100 (exclusive).

Definition at line 105 of file GlobalVariable.h.

◆ StackVariables

using Rose::BinaryAnalysis::Variables::StackVariables = typedef Sawyer::Container::IntervalMap<OffsetInterval, StackVariable>

Collection of local variables organized by stack offsets.

Definition at line 166 of file StackVariable.h.

Enumeration Type Documentation

◆ Access

enum class Rose::BinaryAnalysis::Variables::Access

strong

Whether a variable is read or written.

Enumerator

READ

Variable is read.

WRITE

Variable is written.

Definition at line 47 of file Rose/BinaryAnalysis/Variables/BasicTypes.h.

Function Documentation

◆ initDiagnostics()

void Rose::BinaryAnalysis::Variables::initDiagnostics ( )

Initialize diagnostic output.

This is called automatically when ROSE is initialized.

◆ initNamespace()

void Rose::BinaryAnalysis::Variables::initNamespace ( )

Initialize the namespace.

This is called automatically when ROSE is initialized.

◆ erase()

void Rose::BinaryAnalysis::Variables::erase	(	GlobalVariables &	,
		const AddressInterval &	toErase
	)

Erase some global variables.

Erases global variables from the specified memory region. It is not sufficient to only remove addresses from the map; the addresses stored in the variables themselves (values in the map) may need to be adjusted so they don't overlap with the erased range.

◆ print() [1/2]

void Rose::BinaryAnalysis::Variables::print	(	const GlobalVariables &	,
		const Partitioner2::PartitionerConstPtr &	,
		std::ostream &	out,
		const std::string &	prefix = `""`
	)

Print info about multiple global variables.

This output includes such things as their addresses, sizes, and the defining instructions. The output is multi-line, intended for debugging.

◆ isInconsistent()

AddressInterval Rose::BinaryAnalysis::Variables::isInconsistent	(	const GlobalVariables &	,
		Sawyer::Message::Stream &
	)

Check that the map is consistent.

Test that the keys of the map match up with the variables contained therein. If a map node is found where the interval key for the node doesn't match the addresses of the global variable stored in that node, then the map contains an inconsistency. When an inconsistency is found, and the output stream is enabled then the map is printed and all inconsistencies are highlighted.

Returns the first address interval (key) where an inconsistency is detected, or an empty interval if there are no inconsistencies.

◆ print() [2/2]

void Rose::BinaryAnalysis::Variables::print	(	const StackVariables &	,
		const Partitioner2::PartitionerConstPtr &	,
		std::ostream &	out,
		const std::string &	prefix = `""`
	)

Print info about multiple local variables.

This output includes such things as the function to which they belong and the defining instructions. The output is multi-line, intended for debugging.