Controls VirtualBox debugger over a TCP/IP connection. More...

#include <VBoxClient.h>

Public Member Functions
	VBoxClient (const BazisLib::Network::InternetAddress &addr)
	Creates an instance of the VirtualBox debugger client connected to a debugger over TCP/IP.

	~VBoxClient ()

bool	Initialize ()
	Initializes the debugger, detects parameters and checks for errors.

std::vector < BazisLib::DynamicStringA >	ExecuteCommand (const char *pCommand)

std::map < BazisLib::DynamicStringA, ULONGLONG >	ReadRegisters ()
	Reads the values of all registers from the target.

bool	WriteRegister (const char *pName, ULONGLONG value)
	Writes the value of a single target register.

bool	ReadRegister (const char pName, ULONGLONG pValue)
	Reads a value of a single target register.

bool	WaitForStop ()
	Waits until VirtualBox reports a stop event.

void	RequestStopAsync ()
	Requests the VirtualBox debugger to stop executing the target (i.e. forces a breakpoint)

void	Disconnect ()
	Sends the "exit" command and closes the connection to the VirtualBox debugger.

bool	ReadMemory (ULONGLONG address, void pData, size_t pLength, bool allowCaching=true)
	Reads target memory.

bool	WriteMemory (ULONGLONG address, const void *pData, size_t length)
	Writes target memory.

bool	StepAndWait ()
	Executes a single step and waits for it to complete.

bool	ContinueAndWait ()
	Resumes the target execution and waits for a debug event.

bool	IsSuccessfulReply (const std::vector< BazisLib::DynamicStringA > &reply, bool report=true)
	Returns false if the provided reply contains the "error:" string.

int	CreateBreakpoint (ULONGLONG addr)
	Creates a software breakpoint using the "bp" command.

bool	RemoveBreakpoint (int idx)
	Removes a previously created breakpoint.

Protected Member Functions
virtual void	ReportError (const char *pErrorDescription)
	Reports an error to the user.

Detailed Description

Controls VirtualBox debugger over a TCP/IP connection.

This class allows controlling the VirtualBox debugger over the TCP/IP connection. The key method of this class is ExecuteCommand() that sends an arbitrary commands to the debugger. Almost all other methods are using ExecuteCommand() and parsing the reply.

Attention: The class is not thread-safe. All methods except RequestStopAsync() should be called from the same thread.

Definition at line 22 of file VBoxClient.h.

Constructor & Destructor Documentation

VBoxClient::VBoxClient ( const BazisLib::Network::InternetAddress & addr )

Creates an instance of the VirtualBox debugger client connected to a debugger over TCP/IP.

Attention: After an instance of this class, the Initialize() method should be called.

Definition at line 9 of file VBoxClient.cpp.

VBoxGDB::VBoxClient::~VBoxClient ( )

Definition at line 23 of file VBoxClient.cpp.

Member Function Documentation

bool VBoxGDB::VBoxClient::ContinueAndWait ( )

Resumes the target execution and waits for a debug event.

Definition at line 400 of file VBoxClient.cpp.

int VBoxGDB::VBoxClient::CreateBreakpoint ( ULONGLONG addr )

Creates a software breakpoint using the "bp" command.

Remarks: Note that just inserting "int 3" instruction at a certain address won't cause VirtualBox to stop there. Thus, we need to support creating software breakpoint explicitly

Returns: If the method succeeds, the breakpoint numer is returned. If the method fails, it returns -1.

Definition at line 407 of file VBoxClient.cpp.

void VBoxGDB::VBoxClient::Disconnect ( )

Sends the "exit" command and closes the connection to the VirtualBox debugger.

Attention: Due to a bug in VirtualBox debugger just closing the controlling socket will leave the debugger in an inaccessible state. Thus, if the VBoxGDB process is about to exit unexpectedly (e.g. via Ctrl+Break), it should still try to call this method.

Definition at line 223 of file VBoxClient.cpp.

std::vector< DynamicStringA > VBoxGDB::VBoxClient::ExecuteCommand ( const char * pCommand )

Definition at line 81 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::Initialize ( )

Initializes the debugger, detects parameters and checks for errors.

Definition at line 39 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::IsSuccessfulReply	(	const std::vector< BazisLib::DynamicStringA > &	reply,
		bool	report = `true`
	)

Returns false if the provided reply contains the "error:" string.

Parameters

reply	Contains a reply returned by ExecuteCommand() method.
report	If this argument is TRUE and the reply contains an error message, the method will report it to the user by calling ReportError().

Definition at line 230 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::ReadMemory	(	ULONGLONG	address,
		void *	pData,
		size_t *	pLength,
		bool	allowCaching = `true`
	)

Reads target memory.

Parameters

allowCaching If this argument is set to TRUE, VBoxClient won't send another memory reading request to VirtualBox if the requested data was already contained in the previous VirtualBox reply. Note that calling WriteMemory() resets the cache.

Remarks: The caching is employed as VirtualBox debugger can only read memory in fixed-size blocks. Assume that GDB requests 10 consequent blocks 4 bytes each. The VirtualBox reply for the command reading the first address will already contain enough data to serve all 9 remaining requests. Caching and reusing this data significantly improves performance.

Definition at line 351 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::ReadRegister	(	const char *	pName,
		ULONGLONG *	pValue
	)

Reads a value of a single target register.

Definition at line 457 of file VBoxClient.cpp.

std::map< DynamicStringA, ULONGLONG > VBoxGDB::VBoxClient::ReadRegisters ( )

Reads the values of all registers from the target.

Definition at line 141 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::RemoveBreakpoint ( int idx )

Removes a previously created breakpoint.

Definition at line 425 of file VBoxClient.cpp.

void VBoxGDB::VBoxClient::ReportError ( const char * pErrorDescription )

protectedvirtual

Reports an error to the user.

This method is called when VBoxClient encounters an error and needs to report it to the user. The current implementation simply calls printf() to report it.

Definition at line 98 of file VBoxClient.cpp.

void VBoxGDB::VBoxClient::RequestStopAsync ( )

Requests the VirtualBox debugger to stop executing the target (i.e. forces a breakpoint)

Definition at line 103 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::StepAndWait ( )

Executes a single step and waits for it to complete.

Definition at line 393 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::WaitForStop ( )

Waits until VirtualBox reports a stop event.

Definition at line 188 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::WriteMemory	(	ULONGLONG	address,
		const void *	pData,
		size_t	length
	)

Writes target memory.

Definition at line 299 of file VBoxClient.cpp.

bool VBoxGDB::VBoxClient::WriteRegister	(	const char *	pName,
		ULONGLONG	value
	)

Writes the value of a single target register.

Definition at line 162 of file VBoxClient.cpp.

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

VBoxGDB/VBoxClient.h
VBoxGDB/VBoxClient.cpp

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation