ROSE
0.11.21.0
|
Simple debugger.
This class implements a very simple debugger.
Definition at line 26 of file BinaryDebugger.h.
#include <BinaryDebugger.h>
Classes | |
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... | |
typedef Sawyer::SharedPointer< Debugger > | Ptr |
Shared-ownership pointer to Debugger. 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 | 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... | |
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... | |
size_t | readMemory (rose_addr_t va, size_t nBytes, uint8_t *buffer) |
Read 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... | |
const RegisterDictionary * | registerDictionary () const |
Available registers. More... | |
Disassembler * | disassembler () const |
Disassembler. More... | |
int | waitpidStatus () const |
Returns the last status from a call to waitpid. More... | |
int | remoteSystemCall (int syscallNumber, std::vector< uint64_t > args) |
Cause the subordinate to execute a system call. 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. | |
![]() | |
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... | |
Shared-ownership pointer to Debugger.
See Shared ownership.
Definition at line 29 of file BinaryDebugger.h.
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 351 of file BinaryDebugger.h.
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 BinaryDebugger.h.
Flags controlling operation.
Definition at line 40 of file BinaryDebugger.h.
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 341 of file BinaryDebugger.h.
|
inlineexplicitprotected |
Construct a debugger attached to a specimen.
Definition at line 254 of file BinaryDebugger.h.
References attach().
|
inlinestatic |
Create a debugger object that isn't attached to any subordinate process.
Definition at line 271 of file BinaryDebugger.h.
Referenced by Rose::BinaryAnalysis::InstructionSemantics2::NativeSemantics::Dispatcher::instance().
Create a debugger and start debugging a specimen.
Definition at line 276 of file BinaryDebugger.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.
Referenced by Debugger().
|
inline |
Returns true if attached to a subordinate.
Return value is the subordinate process ID.
Definition at line 295 of file BinaryDebugger.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.
|
inline |
Remove all breakpoints.
Definition at line 323 of file BinaryDebugger.h.
References Sawyer::Container::IntervalSet< I >::clear().
void Rose::BinaryAnalysis::Debugger::singleStep | ( | ) |
Execute one instruction.
Referenced by trace().
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.
|
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 359 of file BinaryDebugger.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:
Sawyer::Container::BitVector Rose::BinaryAnalysis::Debugger::readMemory | ( | rose_addr_t | va, |
size_t | nBytes, | ||
ByteOrder::Endianness | order | ||
) |
Read subordinate memory as a bit vector.
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().
|
inline |
Write subordinate memory.
Writes something to memory.
Definition at line 410 of file BinaryDebugger.h.
References writeMemory().
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::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.
const RegisterDictionary* Rose::BinaryAnalysis::Debugger::registerDictionary | ( | ) | const |
Available registers.
|
inline |
Definition at line 438 of file BinaryDebugger.h.
|
inline |
Returns the last status from a call to waitpid.
Definition at line 443 of file BinaryDebugger.h.
int Rose::BinaryAnalysis::Debugger::remoteSystemCall | ( | int | syscallNumber, |
std::vector< uint64_t > | args | ||
) |
Cause the subordinate to execute a system call.
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 |
Initialize diagnostic output.
This is called automatically when ROSE is initialized.
|
static |
Diagnostic facility for debugger.
Definition at line 223 of file BinaryDebugger.h.