Description

Base class for semantics machine states.

Binary semantic analysis usually progresses one instruction at a time–one starts with an initial state and the act of processing an instruction modifies the state. The State is the base class class for the semantic states of various instruction semantic policies. It contains storage for all the machine registers and memory.

Sometimes it's useful to have a state that contains only registers or only memory. Although this class doesn't allow its register or memory state children to be null pointers, the NullSemantics class provides register and memory states that are mostly no-ops.

States must be copyable objects. Many analyses keep a copy of the machine state for each instruction or each CFG vertex.

State objects are allocated on the heap and reference counted. The BaseSemantics::State is an abstract class that defines the interface. See the Rose::BinaryAnalysis::InstructionSemantics namespace for an overview of how the parts fit together.

Definition at line 41 of file State.h.

#include <Rose/BinaryAnalysis/InstructionSemantics/BaseSemantics/State.h>

Inheritance diagram for Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State:

[legend]

Collaboration diagram for Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State:

[legend]

Classes
class	WithFormatter
	State with formatter. More...

Public Types
using	Ptr = StatePtr
	Shared-ownership pointer.

Public Member Functions
virtual StatePtr	create (const RegisterStatePtr &registers, const MemoryStatePtr &memory) const
	Virtual constructor.

virtual StatePtr	clone () const
	Virtual copy constructor.

SValuePtr	protoval () const
	Return the protoval.

virtual void	clear ()
	Initialize state.

void	zeroRegisters ()
	Initialize all registers to zero.

void	clearMemory ()
	Clear all memory locations.

RegisterStatePtr	registerState () const
	Property: Register state.

MemoryStatePtr	memoryState () const
	Property: Memory state.

bool	hasInterruptState () const
	Tests whether an interrupt state is present.

virtual SValuePtr	readRegister (RegisterDescriptor desc, const SValuePtr &dflt, RiscOperators *ops)
	Read a value from a register.

virtual SValuePtr	peekRegister (RegisterDescriptor desc, const SValuePtr &dflt, RiscOperators *ops)
	Read register without side effects.

virtual void	writeRegister (RegisterDescriptor desc, const SValuePtr &value, RiscOperators *ops)
	Write a value to a register.

virtual SValuePtr	readMemory (const SValuePtr &address, const SValuePtr &dflt, RiscOperators addrOps, RiscOperators valOps)
	Read a value from memory.

virtual SValuePtr	peekMemory (const SValuePtr &address, const SValuePtr &dflt, RiscOperators addrOps, RiscOperators valOps)
	Read from memory without side effects.

virtual void	writeMemory (const SValuePtr &addr, const SValuePtr &value, RiscOperators addrOps, RiscOperators valOps)
	Write a value to memory.

virtual SValuePtr	readInterrupt (unsigned major, unsigned minor, const SValuePtr &dflt, RiscOperators *valOps)
	Read an interrupt state.

virtual SValuePtr	peekInterrupt (unsigned major, unsigned minor, const SValuePtr &dflt, RiscOperators *valOps)
	Read an interrupt state without side effects.

virtual bool	writeInterrupt (unsigned major, unsigned minor, const SValuePtr &value, RiscOperators *valOps)
	Write an interrupt state.

SValuePtr	raiseInterrupt (unsigned major, unsigned minor, RiscOperators *valOps)
	Raise an interrupt.

SValuePtr	clearInterrupt (unsigned major, unsigned minor, RiscOperators *valOps)
	Clear an interrupt.

bool	isInterruptDefinitelyRaised (unsigned major, unsigned minor, RiscOperators *valOps)
	Test an interrupt.

bool	isInterruptDefinitelyClear (unsigned major, unsigned minor, RiscOperators *valOps)
	Test an interrupt.

virtual void	hash (Combinatorics::Hasher &, RiscOperators addrOps, RiscOperators valOps) const
	Compute a hash of the state.

std::string	toString () const
	Convert the state to a string for debugging.

virtual bool	merge (const StatePtr &other, RiscOperators *ops)
	Merge operation for data flow analysis.


RegisterStatePtr	interruptState () const
	Property: Interrupt state.

void	interruptState (const RegisterStatePtr &)
	Property: Interrupt state.


void	printRegisters (std::ostream &stream, const std::string &prefix="")
	Print the register contents.

virtual void	printRegisters (std::ostream &stream, Formatter &fmt) const
	Print the register contents.


void	printMemory (std::ostream &stream, const std::string &prefix="") const
	Print memory contents.

virtual void	printMemory (std::ostream &stream, Formatter &fmt) const
	Print memory contents.


void	printInterrupts (std::ostream &, const std::string &prefix="")
	Print interrupt states.

virtual void	printInterrupts (std::ostream &stream, Formatter &fmt) const
	Print interrupt states.


void	print (std::ostream &stream, const std::string &prefix="") const
	Print the state.

virtual void	print (std::ostream &, Formatter &) const
	Print the state.


WithFormatter	with_format (Formatter &fmt)
	Used for printing states with formatting.

WithFormatter	operator+ (Formatter &fmt)
	Used for printing states with formatting.

WithFormatter	operator+ (const std::string &linePrefix)
	Used for printing states with formatting.

Static Public Member Functions
static StatePtr	instance (const RegisterStatePtr &registers, const MemoryStatePtr &memory, const RegisterStatePtr &interrupts)
	Instantiate a new state object with specified register, memory, and interrupt states.

static StatePtr	instance (const RegisterStatePtr &registers, const MemoryStatePtr &memory)
	Instantiate a new state object with specified register and memory states.

static StatePtr	instance (const StatePtr &other)
	Instantiate a new copy of an existing state.

static StatePtr	promote (const StatePtr &)

Protected Member Functions
	State (const RegisterStatePtr &registers, const MemoryStatePtr &memory, const RegisterStatePtr &interrupts)

	State (const RegisterStatePtr &registers, const MemoryStatePtr &memory)

	State (const State &other)

Member Typedef Documentation

◆ Ptr

using Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::Ptr = StatePtr

Shared-ownership pointer.

Definition at line 44 of file State.h.

Member Function Documentation

◆ create()

virtual StatePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::create	(	const RegisterStatePtr &	registers,
		const MemoryStatePtr &	memory
	)		const

virtual

Virtual constructor.

The interruptState property will always be null.

Reimplemented in Rose::BinaryAnalysis::InstructionSemantics::PartialSymbolicSemantics::State.

◆ clone()

virtual StatePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::clone ( ) const

virtual

Virtual copy constructor.

Allocates a new state object which is a deep copy of this state. States must be copyable objects because many analyses depend on being able to make a copy of the entire semantic state at each machine instruction, at each CFG vertex, etc.

Reimplemented in Rose::BinaryAnalysis::InstructionSemantics::PartialSymbolicSemantics::State.

◆ protoval()

SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::protoval ( ) const

Return the protoval.

The protoval is used to construct other values via its virtual constructors.

◆ clear()

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::clear ( )

virtual

Initialize state.

The register and memory states are cleared.

◆ zeroRegisters()

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::zeroRegisters ( )

Initialize all registers to zero.

Calls the RegisterState::zero method. Memory is not affected.

◆ clearMemory()

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::clearMemory ( )

Clear all memory locations.

Calls the MemoryState::clear method. Registers are not affected.

◆ registerState()

RegisterStatePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::registerState ( ) const

Property: Register state.

This read-only property is the register substate of this whole state.

◆ memoryState()

MemoryStatePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::memoryState ( ) const

Property: Memory state.

This read-only property is the memory substate of this whole state.

◆ interruptState() [1/2]

RegisterStatePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::interruptState ( ) const

Property: Interrupt state.

The interrupt state is modeled as bit flags specifying whether the interrupt has been raised. Interrupts have concrete major and minor numbers that correspond to the RegisterDescriptor major and minor properties. It is permissible for this state to have a null interrupt state, in which case the BaseSemantics::RiscOperators do something else (such as throw an exception).

◆ interruptState() [2/2]

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::interruptState ( const RegisterStatePtr & )

Property: Interrupt state.

The interrupt state is modeled as bit flags specifying whether the interrupt has been raised. Interrupts have concrete major and minor numbers that correspond to the RegisterDescriptor major and minor properties. It is permissible for this state to have a null interrupt state, in which case the BaseSemantics::RiscOperators do something else (such as throw an exception).

◆ hasInterruptState()

bool Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::hasInterruptState ( ) const

Tests whether an interrupt state is present.

A state may have an interrupt state (similar to the register and memory states). This function returns true if and only if the interrupt state is present.

◆ readRegister()

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::readRegister	(	RegisterDescriptor	desc,
		const SValuePtr &	dflt,
		RiscOperators *	ops
	)

virtual

Read a value from a register.

The BaseSemantics::State::readRegister implementation simply delegates to the register state member of this state. See BaseSemantics::RiscOperators::readRegister for details.

◆ peekRegister()

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::peekRegister	(	RegisterDescriptor	desc,
		const SValuePtr &	dflt,
		RiscOperators *	ops
	)

virtual

Read register without side effects.

The BaseSemantics::State::peekRegister implementation simply delegates to the register state member of this state. See BaseSemantics::RiscOperators::peekRegister for details.

◆ writeRegister()

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::writeRegister	(	RegisterDescriptor	desc,
		const SValuePtr &	value,
		RiscOperators *	ops
	)

virtual

Write a value to a register.

The BaseSemantics::State::writeRegister implementation simply delegates to the register state member of this state. See BaseSemantics::RiscOperators::writeRegister for details.

◆ readMemory()

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::readMemory	(	const SValuePtr &	address,
		const SValuePtr &	dflt,
		RiscOperators *	addrOps,
		RiscOperators *	valOps
	)

virtual

Read a value from memory.

The BaseSemantics::readMemory() implementation simply delegates to the memory state member of this state. See BaseSemantics::RiscOperators::readMemory() for details.

◆ peekMemory()

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::peekMemory	(	const SValuePtr &	address,
		const SValuePtr &	dflt,
		RiscOperators *	addrOps,
		RiscOperators *	valOps
	)

virtual

Read from memory without side effects.

The BaseSemantics::peekMemory() implementation simply delegates to the memory state member of this state. See BaseSemantics::RiscOperators::peekMemory() for details.

◆ writeMemory()

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::writeMemory	(	const SValuePtr &	addr,
		const SValuePtr &	value,
		RiscOperators *	addrOps,
		RiscOperators *	valOps
	)

virtual

Write a value to memory.

The BaseSemantics::writeMemory() implementation simply delegates to the memory state member of this state. See BaseSemantics::RiscOperators::writeMemory() for details.

◆ readInterrupt()

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::readInterrupt	(	unsigned	major,
		unsigned	minor,
		const SValuePtr &	dflt,
		RiscOperators *	valOps
	)

virtual

Read an interrupt state.

The BaseSemantics::State::readInterrupt implementation delegates to the interrupt state member of this state if interrupts are present, otherwise it returns a null pointer. The default value dflt value will be written to the interrupt state if that interrupt has no previous value. The default value and the return value (when non-null) are always Boolean values (single bits) to indicate whether that interrupt is raised.

◆ peekInterrupt()

virtual SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::peekInterrupt	(	unsigned	major,
		unsigned	minor,
		const SValuePtr &	dflt,
		RiscOperators *	valOps
	)

virtual

Read an interrupt state without side effects.

The BaseSemantics::State::peekInterrupt implementation delegates to the interrupt state member of this state if interrupts are present, otherwise it returns a null pointer. The default value dflt value will be written to the interrupt state if that interrupt has no previous value. The default value and the return value (when non-null) are always Boolean values (single bits) to indicate whether that interrupt is raised.

◆ writeInterrupt()

virtual bool Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::writeInterrupt	(	unsigned	major,
		unsigned	minor,
		const SValuePtr &	value,
		RiscOperators *	valOps
	)

virtual

Write an interrupt state.

The BaseSemantics::State::writeInterrupt implementation delegates to the interrupt state member of this state if interrupts are present and then returns true; otherwise it returns false. The value argument is Boolean (single bit) to indicate whether the interrupt has been raised.

◆ raiseInterrupt()

SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::raiseInterrupt	(	unsigned	major,
		unsigned	minor,
		RiscOperators *	valOps
	)

Raise an interrupt.

Raises an interrupt by writing a concrete true value to the interrupt state. If this state has an interrupt sub-state then the return value is the old Boolean value for that interrupt; otherwise this function returns a null pointer.

◆ clearInterrupt()

SValuePtr Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::clearInterrupt	(	unsigned	major,
		unsigned	minor,
		RiscOperators *	valOps
	)

Clear an interrupt.

Clears an interrupt by writing a concrete false value to the interrupt state. If this state has an interrupt sub-state then the return value is the old Boolean value for that interrupt; otherwise this function returns a null pointer.

◆ isInterruptDefinitelyRaised()

bool Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::isInterruptDefinitelyRaised	(	unsigned	major,
		unsigned	minor,
		RiscOperators *	valOps
	)

Test an interrupt.

Returns true if this state has an interrupt sub-state and the specified interrupt in that substate has a concrete true value. Returns false in all other cases.

If the caller needs to handle values other than concrete true and false (such as unknown states) then use readInterrupt or peekInterrupt instead.

◆ isInterruptDefinitelyClear()

bool Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::isInterruptDefinitelyClear	(	unsigned	major,
		unsigned	minor,
		RiscOperators *	valOps
	)

Test an interrupt.

Returns true if this state has an interrupt sub-state and the specified interrupt in that substate has a concrete false value. Returns false in all other cases.

If the caller needs to handle values other than concrete true and false (such as unknown states) then use readInterrupt or peekInterrupt instead.

◆ hash()

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::hash	(	Combinatorics::Hasher &	,
		RiscOperators *	addrOps,
		RiscOperators *	valOps
	)		const

virtual

Compute a hash of the state.

The state hash is computed by combining the memory hash, register hash, and interrupt hash.

◆ printRegisters() [1/2]

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::printRegisters	(	std::ostream &	stream,
		const std::string &	prefix = `""`
	)

Print the register contents.

This method emits one line per register and contains the register name and its value.

◆ printRegisters() [2/2]

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::printRegisters	(	std::ostream &	stream,
		Formatter &	fmt
	)		const

virtual

Print the register contents.

This method emits one line per register and contains the register name and its value.

◆ printMemory() [1/2]

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::printMemory	(	std::ostream &	stream,
		const std::string &	prefix = `""`
	)		const

Print memory contents.

This simply calls the MemoryState::print method.

◆ printMemory() [2/2]

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::printMemory	(	std::ostream &	stream,
		Formatter &	fmt
	)		const

virtual

Print memory contents.

This simply calls the MemoryState::print method.

◆ printInterrupts() [1/2]

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::printInterrupts	(	std::ostream &	,
		const std::string &	prefix = `""`
	)

Print interrupt states.

This method emits one line per interrupt and contains the interrupt major and minor numbers and a Boolean expression indicating whether the interrupt is currently raised.

◆ printInterrupts() [2/2]

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::printInterrupts	(	std::ostream &	stream,
		Formatter &	fmt
	)		const

virtual

Print interrupt states.

This method emits one line per interrupt and contains the interrupt major and minor numbers and a Boolean expression indicating whether the interrupt is currently raised.

◆ print() [1/2]

void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::print	(	std::ostream &	stream,
		const std::string &	prefix = `""`
	)		const

Print the state.

This emits a multi-line string containing the registers and all known memory locations.

◆ print() [2/2]

virtual void Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::print	(	std::ostream &	,
		Formatter &
	)		const

virtual

Print the state.

This emits a multi-line string containing the registers and all known memory locations.

◆ toString()

std::string Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::toString ( ) const

Convert the state to a string for debugging.

This is intended mainly for debugging so that you can easily print the state from within a debugger.

◆ with_format()

WithFormatter Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::with_format ( Formatter & fmt )

inline

Used for printing states with formatting.

The usual way to use this is:

StatePtr obj = ...;
Formatter fmt = ...;
std::cout <<"The value is: " <<(*obj+fmt) <<"\n";

Since specifying a line prefix string for indentation purposes is such a common use case, the indentation can be given instead of a format, as in the following code that indents the prefixes each line of the expression with four spaces.

std::cout <<"Current state:\n" <<*(obj + " ");

Definition at line 320 of file State.h.

Referenced by operator+().

◆ operator+() [1/2]

WithFormatter Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::operator+ ( Formatter & fmt )

inline

Used for printing states with formatting.

The usual way to use this is:

StatePtr obj = ...;
Formatter fmt = ...;
std::cout <<"The value is: " <<(*obj+fmt) <<"\n";

Since specifying a line prefix string for indentation purposes is such a common use case, the indentation can be given instead of a format, as in the following code that indents the prefixes each line of the expression with four spaces.

std::cout <<"Current state:\n" <<*(obj + " ");

Definition at line 321 of file State.h.

References with_format().

◆ operator+() [2/2]

WithFormatter Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::operator+ ( const std::string & linePrefix )

Used for printing states with formatting.

The usual way to use this is:

StatePtr obj = ...;
Formatter fmt = ...;
std::cout <<"The value is: " <<(*obj+fmt) <<"\n";

Since specifying a line prefix string for indentation purposes is such a common use case, the indentation can be given instead of a format, as in the following code that indents the prefixes each line of the expression with four spaces.

std::cout <<"Current state:\n" <<*(obj + " ");

◆ merge()

virtual bool Rose::BinaryAnalysis::InstructionSemantics::BaseSemantics::State::merge	(	const StatePtr &	other,
		RiscOperators *	ops
	)

virtual

Merge operation for data flow analysis.

Merges the other state into this state. Returns true if this state changed, false otherwise. This method usually isn't overridden in subclasses since all the base implementation does is invoke the merge operation on the memory state and register state.

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

State.h

Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Member Typedef Documentation

◆ Ptr

Member Function Documentation

◆ create()

◆ clone()

◆ protoval()

◆ clear()

◆ zeroRegisters()

◆ clearMemory()

◆ registerState()

◆ memoryState()

◆ interruptState() [1/2]

◆ interruptState() [2/2]

◆ hasInterruptState()

◆ readRegister()

◆ peekRegister()

◆ writeRegister()

◆ readMemory()

◆ peekMemory()

◆ writeMemory()

◆ readInterrupt()

◆ peekInterrupt()

◆ writeInterrupt()

◆ raiseInterrupt()

◆ clearInterrupt()

◆ isInterruptDefinitelyRaised()

◆ isInterruptDefinitelyClear()

◆ hash()

◆ printRegisters() [1/2]

◆ printRegisters() [2/2]

◆ printMemory() [1/2]

◆ printMemory() [2/2]

◆ printInterrupts() [1/2]

◆ printInterrupts() [2/2]

◆ print() [1/2]

◆ print() [2/2]

◆ toString()

◆ with_format()

◆ operator+() [1/2]

◆ operator+() [2/2]

◆ merge()