Description

Simple debugger.

This class implements a very simple debugger.

Definition at line 26 of file Debugger.h.

#include <Rose/BinaryAnalysis/Debugger.h>

Inheritance diagram for Rose::BinaryAnalysis::Debugger:

[legend]

Collaboration diagram for Rose::BinaryAnalysis::Debugger:

[legend]

Classes
struct	AllRegisters
	Normal and floating point register values. More...

class	Specimen
	Describes the specimen to be debugged. More...

Public Types
enum	DetachMode { KILL, DETACH, CONTINUE, NOTHING }
	How to detach from a process when the debugger is destroyed. More...

enum	Flag { ATTACH = 0x00000001, REDIRECT_INPUT = 0x00000002, REDIRECT_OUTPUT = 0x00000004, REDIRECT_ERROR = 0x00000008, CLOSE_FILES = 0x00000010, DEFAULT_FLAGS = 0x00000013 }
	Flags controlling operation. More...

enum	FilterActionFlags { REJECT = 0x00000001, STOP = 0x00000002 }
	Action for trace filter callback. More...

using	Ptr = DebuggerPtr
	Shared-ownership pointer. More...

using	RegisterPage = std::array< uint8_t, 512 >
	Opaque collection of register values. More...

typedef BitFlags< FilterActionFlags >	FilterAction
	Return value for tracing. More...

Public Member Functions
void	attach (const Specimen &, Sawyer::Optional< DetachMode > onDelete=Sawyer::Nothing())
	Attach to a specimen. More...

int	isAttached ()
	Returns true if attached to a subordinate. More...

void	detach (Sawyer::Optional< DetachMode > mode=Sawyer::Nothing())
	Detach from the subordinate. More...

void	terminate ()
	Terminate the subordinate. More...

void	executionAddress (rose_addr_t va)
	Set execution address. More...

rose_addr_t	executionAddress ()
	Get execution address. More...

void	setBreakpoint (const AddressInterval &)
	Set breakpoints. More...

void	clearBreakpoint (const AddressInterval &)
	Remove breakpoints. More...

void	clearBreakpoints ()
	Remove all breakpoints. More...

void	singleStep ()
	Execute one instruction. More...

void	stepIntoSyscall ()
	Execute to a system call. More...

void	runToBreakpoint ()
	Run until the next breakpoint is reached. More...

void	runToSyscall ()
	Run until the next system call. More...

Sawyer::Container::Trace< rose_addr_t >	trace ()
	Run the program and return an execution trace. More...

template<class Filter >
Sawyer::Container::Trace< rose_addr_t >	trace (Filter &filter)
	Run the program and return an execution trace. More...

size_t	kernelWordSize ()
	Obtain and cache kernel's word size in bits. More...

Sawyer::Container::BitVector	readRegister (RegisterDescriptor)
	Read subordinate register. More...

AllRegisters	readAllRegisters ()
	Read all registers. More...

void	writeAllRegisters (const AllRegisters &)
	Write all registers. More...

size_t	readMemory (rose_addr_t va, size_t nBytes, uint8_t *buffer)
	Read subordinate memory. More...

std::vector< uint8_t >	readMemory (rose_addr_t va, size_t nBytes)
	Read subordinate memory as an array of bytes. More...

Sawyer::Container::BitVector	readMemory (rose_addr_t va, size_t nBytes, ByteOrder::Endianness order)
	Read subordinate memory as a bit vector. More...

size_t	writeMemory (rose_addr_t va, size_t nBytes, const uint8_t *bytes)
	Writes some bytes to subordinate memory. More...

template<typename T >
void	writeMemory (rose_addr_t va, const T &value)
	Write subordinate memory. More...

std::string	readCString (rose_addr_t va, size_t maxBytes=UNLIMITED)
	Read C-style NUL-terminated string from subordinate. More...

bool	isTerminated ()
	Returns true if the subordinate terminated. More...

std::string	howTerminated ()
	String describing how the subordinate process terminated. More...

RegisterDictionaryPtr	registerDictionary () const
	Available registers. More...

Disassembler::BasePtr	disassembler () const
	Disassembler. More...

int	waitpidStatus () const
	Returns the last status from a call to waitpid. More...

int	remoteOpenFile (const boost::filesystem::path &fileName, unsigned flags, mode_t mode)
	Cause the subordinate to open a file. More...

int	remoteCloseFile (unsigned remoteFd)
	Cause the subordinate to close a file. More...

rose_addr_t	remoteMmap (rose_addr_t va, size_t nBytes, unsigned prot, unsigned flags, const boost::filesystem::path &, off_t offset)
	Map a new memory region in the subordinate. More...


void	writeRegister (RegisterDescriptor, const Sawyer::Container::BitVector &)
	Write subordinate register.

void	writeRegister (RegisterDescriptor, uint64_t value)
	Write subordinate register.


int64_t	remoteSystemCall (int syscallNumber)
	Cause the subordinate to execute a system call.

int64_t	remoteSystemCall (int syscallNumber, uint64_t arg1)
	Cause the subordinate to execute a system call.

int64_t	remoteSystemCall (int syscallNumber, uint64_t arg1, uint64_t arg2)
	Cause the subordinate to execute a system call.

int64_t	remoteSystemCall (int syscallNumber, uint64_t arg1, uint64_t arg2, uint64_t arg3)
	Cause the subordinate to execute a system call.

int64_t	remoteSystemCall (int syscallNumber, uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4)
	Cause the subordinate to execute a system call.

int64_t	remoteSystemCall (int syscallNumber, uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5)
	Cause the subordinate to execute a system call.

int64_t	remoteSystemCall (int syscallNumber, uint64_t arg1, uint64_t arg2, uint64_t arg3, uint64_t arg4, uint64_t arg5, uint64_t arg6)
	Cause the subordinate to execute a system call.

int64_t	remoteSystemCall (int syscallNumber, std::vector< uint64_t > args)
	Cause the subordinate to execute a system call.

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

	SharedObject (const SharedObject &)
	Copy constructor. More...

virtual	~SharedObject ()
	Virtual destructor. More...

SharedObject &	operator= (const SharedObject &)
	Assignment. More...

Static Public Member Functions
static Ptr	instance ()
	Create a debugger object that isn't attached to any subordinate process. More...

static Ptr	instance (const Specimen &specimen)
	Create a debugger and start debugging a specimen. More...

static void	initDiagnostics ()
	Initialize diagnostic output. More...

Static Public Attributes
static Sawyer::Message::Facility	mlog
	Diagnostic facility for debugger. More...

Protected Member Functions
	Debugger (const Specimen &specimen)
	Construct a debugger attached to a specimen. More...

Member Typedef Documentation

using Rose::BinaryAnalysis::Debugger::Ptr = DebuggerPtr

Shared-ownership pointer.

Definition at line 29 of file Debugger.h.

using Rose::BinaryAnalysis::Debugger::RegisterPage = std::array<uint8_t, 512>

Opaque collection of register values.

Definition at line 226 of file Debugger.h.

typedef BitFlags<FilterActionFlags> Rose::BinaryAnalysis::Debugger::FilterAction

Return value for tracing.

The return value from the trace filter indicates whether the current address should be appended to the trace or rejected, and whether the tracing operation should continue or stop. A default constructed FilterAction will append the current address to the trace and continue tracing, which is normally what one wants.

Definition at line 411 of file Debugger.h.

Member Enumeration Documentation

enum Rose::BinaryAnalysis::Debugger::DetachMode

How to detach from a process when the debugger is destroyed.

Enumerator
KILL	Kill the process.
DETACH	Simply detach leaving process in current state.
CONTINUE	Detach from process and cause it to continue running.
NOTHING	Do nothing.

Definition at line 32 of file Debugger.h.

enum Rose::BinaryAnalysis::Debugger::Flag

Flags controlling operation.

Enumerator
ATTACH	Attach to existing process.
REDIRECT_INPUT	Redirect input from /dev/null.
REDIRECT_OUTPUT	Redirect output to /dev/null.
REDIRECT_ERROR	Redirect standard error to /dev/null.
CLOSE_FILES	Close all file descriptors > 2.
DEFAULT_FLAGS	Default flags.

Definition at line 40 of file Debugger.h.

enum Rose::BinaryAnalysis::Debugger::FilterActionFlags

Action for trace filter callback.

Enumerator
REJECT	Reject the current address, not appending it to the trace.
STOP	Abort tracing, either appending or rejecting the current address.

Definition at line 401 of file Debugger.h.

Constructor & Destructor Documentation

Rose::BinaryAnalysis::Debugger::Debugger ( const Specimen & specimen )

explicitprotected

Construct a debugger attached to a specimen.

Member Function Documentation

static Ptr Rose::BinaryAnalysis::Debugger::instance ( )

inlinestatic

Create a debugger object that isn't attached to any subordinate process.

Definition at line 269 of file Debugger.h.

static Ptr Rose::BinaryAnalysis::Debugger::instance ( const Specimen & specimen )

inlinestatic

Create a debugger and start debugging a specimen.

Definition at line 274 of file Debugger.h.

void Rose::BinaryAnalysis::Debugger::attach	(	const Specimen &	,
		Sawyer::Optional< DetachMode >	onDelete = `Sawyer::Nothing()`
	)

Attach to a specimen.

The onDelete argument specifies what to do with the subordinate process if this debugger object is deleted while the subordinate is still attached. If onDelete is not specified, then a reasonable value is chosen: for subordinates that existed prior to attaching (e.g., Linux process ID), the default detach mechanism is either DETACH or NOTHING depending on whether the Specimen ATTACH flag was set or clear. For subordniates that are created by this attach method (such as ELF executables), the detach mechanism is KILL.

int Rose::BinaryAnalysis::Debugger::isAttached ( )

inline

Returns true if attached to a subordinate.

Return value is the subordinate process ID.

Definition at line 293 of file Debugger.h.

void Rose::BinaryAnalysis::Debugger::detach ( Sawyer::Optional< DetachMode > mode = Sawyer::Nothing() )

Detach from the subordinate.

If a detach mode is specified then use that mechanism to detatch. Otherwise use whatever mechanism was chosen as the default during the attach operation.

void Rose::BinaryAnalysis::Debugger::terminate ( )

Terminate the subordinate.

void Rose::BinaryAnalysis::Debugger::executionAddress ( rose_addr_t va )

Set execution address.

rose_addr_t Rose::BinaryAnalysis::Debugger::executionAddress ( )

Get execution address.

Referenced by trace().

void Rose::BinaryAnalysis::Debugger::setBreakpoint ( const AddressInterval & )

Set breakpoints.

void Rose::BinaryAnalysis::Debugger::clearBreakpoint ( const AddressInterval & )

Remove breakpoints.

void Rose::BinaryAnalysis::Debugger::clearBreakpoints ( )

inline

Remove all breakpoints.

Definition at line 321 of file Debugger.h.

References Sawyer::Container::IntervalSet< I >::clear().

void Rose::BinaryAnalysis::Debugger::singleStep ( )

Execute one instruction.

Referenced by trace().

void Rose::BinaryAnalysis::Debugger::stepIntoSyscall ( )

Execute to a system call.

void Rose::BinaryAnalysis::Debugger::runToBreakpoint ( )

Run until the next breakpoint is reached.

void Rose::BinaryAnalysis::Debugger::runToSyscall ( )

Run until the next system call.

The subordinate is run until it is about to make a system call or has just returned from a system call, or it has encountered a signal or terminated. Execution does not stop at break points.

Sawyer::Container::Trace<rose_addr_t> Rose::BinaryAnalysis::Debugger::trace ( )

Run the program and return an execution trace.

template<class Filter >

Sawyer::Container::Trace<rose_addr_t> Rose::BinaryAnalysis::Debugger::trace ( Filter & filter )

inline

Run the program and return an execution trace.

At each step along the execution, the filter functor is invoked and passed the current execution address. The return value of type FilterAction from the filter functor controls whether the address is appended to the trace and whether the tracing should continue.

Definition at line 419 of file Debugger.h.

References Sawyer::Container::Trace< T, IndexTag >::append(), executionAddress(), Sawyer::BitFlags< E, V >::isClear(), Sawyer::BitFlags< E, V >::isSet(), isTerminated(), REJECT, singleStep(), and STOP.

size_t Rose::BinaryAnalysis::Debugger::kernelWordSize ( )

Obtain and cache kernel's word size in bits.

The wordsize of the kernel is not necessarily the same as the word size of the compiled version of this header.

Sawyer::Container::BitVector Rose::BinaryAnalysis::Debugger::readRegister ( RegisterDescriptor )

Read subordinate register.

Some registers are wider than what can be easily represented on this architecture (e.g., x86 XMM registers are 128 bits), therefore return the result as a bit vector. If you want just the low-order 64 bits, invoke it like this:

uint64_t value = debugger->readRegister(RIP).toInteger();

AllRegisters Rose::BinaryAnalysis::Debugger::readAllRegisters ( )

Read all registers.

The return value is opaque but can be used to restore registers with writeAllRegisters.

void Rose::BinaryAnalysis::Debugger::writeAllRegisters ( const AllRegisters & )

Write all registers.

Restores registers that were read earlier.

size_t Rose::BinaryAnalysis::Debugger::readMemory	(	rose_addr_t	va,
		size_t	nBytes,
		uint8_t *	buffer
	)

Read subordinate memory.

Returns the number of bytes read. The implementation accesses the subordinate memory via proc filesystem rather than sending PTRACE_PEEKDATA commands. This allows large areas of memory to be read efficiently.

std::vector<uint8_t> Rose::BinaryAnalysis::Debugger::readMemory	(	rose_addr_t	va,
		size_t	nBytes
	)

Read subordinate memory as an array of bytes.

If the read fails then a shorter buffer is returned.

Sawyer::Container::BitVector Rose::BinaryAnalysis::Debugger::readMemory	(	rose_addr_t	va,
		size_t	nBytes,
		ByteOrder::Endianness	order
	)

Read subordinate memory as a bit vector.

uint64_t value = debugger->readMemory(0x12345678, 4, ByteOrder::ORDER_LSB).toInteger();

size_t Rose::BinaryAnalysis::Debugger::writeMemory	(	rose_addr_t	va,
		size_t	nBytes,
		const uint8_t *	bytes
	)

Writes some bytes to subordinate memory.

Returns the number of bytes written.

Referenced by writeMemory().

template<typename T >

void Rose::BinaryAnalysis::Debugger::writeMemory	(	rose_addr_t	va,
		const T &	value
	)

inline

Write subordinate memory.

Writes something to memory.

Definition at line 491 of file Debugger.h.

References writeMemory().

std::string Rose::BinaryAnalysis::Debugger::readCString	(	rose_addr_t	va,
		size_t	maxBytes = `UNLIMITED`
	)

Read C-style NUL-terminated string from subordinate.

Reads up to maxBytes bytes from the subordinate or until an ASCII NUL character is read, concatenates all the characters (except the NUL) into a C++ string and returns it. The maxBytes includes the NUL terminator although the NUL terminator is not returned as part of the string.

bool Rose::BinaryAnalysis::Debugger::isTerminated ( )

Returns true if the subordinate terminated.

Referenced by trace().

std::string Rose::BinaryAnalysis::Debugger::howTerminated ( )

String describing how the subordinate process terminated.

RegisterDictionaryPtr Rose::BinaryAnalysis::Debugger::registerDictionary ( ) const

Available registers.

Disassembler::BasePtr Rose::BinaryAnalysis::Debugger::disassembler ( ) const

Disassembler.

int Rose::BinaryAnalysis::Debugger::waitpidStatus ( ) const

inline

Returns the last status from a call to waitpid.

Definition at line 516 of file Debugger.h.

int Rose::BinaryAnalysis::Debugger::remoteOpenFile	(	const boost::filesystem::path &	fileName,
		unsigned	flags,
		mode_t	mode
	)

Cause the subordinate to open a file.

The subordinate will be coerced into opening the specified file, and the file descriptor in the subordinate is returned.

int Rose::BinaryAnalysis::Debugger::remoteCloseFile ( unsigned remoteFd )

Cause the subordinate to close a file.

rose_addr_t Rose::BinaryAnalysis::Debugger::remoteMmap	(	rose_addr_t	va,
		size_t	nBytes,
		unsigned	prot,
		unsigned	flags,
		const boost::filesystem::path &	,
		off_t	offset
	)

Map a new memory region in the subordinate.

This is similar to the mmap function, except it operates on the subordinate process.

static void Rose::BinaryAnalysis::Debugger::initDiagnostics ( )

static

Initialize diagnostic output.

This is called automatically when ROSE is initialized.

Member Data Documentation

Sawyer::Message::Facility Rose::BinaryAnalysis::Debugger::mlog

static

Diagnostic facility for debugger.

Definition at line 223 of file Debugger.h.

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

Debugger.h

Description

Classes

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation