Remote stub for GNU Debugger (GDB) More...

#include <debug/gdb/stub.h>

Inheritance diagram for GDB_Stub:

Collaboration diagram for GDB_Stub:

Public Member Functions
	GDB_Stub (bool wait=false, bool debug_output=false, ComPort port=COM1, BaudRate baud_rate=BAUD_9600)
	constructor

void	configureInterrupt (bool active)

Public Member Functions inherited from Serial
	Serial (ComPort port=COM1, BaudRate baud_rate=BAUD_115200, DataBits data_bits=DATA_8BIT, StopBits stop_bits=STOP_1BIT, Parity parity=PARITY_NONE)
	Constructor.

int	read (bool blocking=true)
	Read one byte from the serial interface.

int	write (char out, bool blocking=true)
	Write one byte to the serial interface.

bool	receiveInterrupt (bool enable)
	Activate or deactivate interrupts on data reception.

Static Public Attributes
static int	signal = 0
	Last trap/interrupt vector handled in GDB.

Protected Member Functions
void	handle ()
	Handling traps.

int	writeString (const char *buf, size_t len)
	Send a string via the serial connection.

int	readString (char *buf, size_t buf_len, size_t len)
	Receive a string via the serial connection.

int	sendPacket (const char *pkt_data, size_t pkt_len)
	Transmits a packet of data.

int	receivePacket (char pkt_buf, size_t pkt_buf_len, size_t pkt_len)
	Receives a packet of data assuming a 7-bit clean connection.

int	receiveAck (void)
	Receive acknowledgment for a packet.

int	sendOkPacket ()
	Create and send an OK packet (`OK`)

int	sendSignalPacket (char *buf, size_t buf_len, char signal)
	Create and send a signal packet (`S [int]`)

int	sendErrorPacket (char *buf, size_t buf_len, char error)
	Create and send an error packet (`E [code]`)

Static Protected Member Functions
static int	checksum (const char *buf, size_t len)
	Calculate 8-bit checksum of a buffer.

static int	memRead (char *buf, size_t buf_len, uintptr_t addr, size_t len, bool hex)
	Read contents of system memory area into the buffer.

static int	memWrite (const char *buf, size_t buf_len, uintptr_t addr, size_t len, bool hex)
	Write buffer contents to system memory area.

static void	sysContinue ()
	Continue program execution (at current instruction pointer)

static void	sysStep ()
	Single step the next instruction.

Private Member Functions
	GDB_Stub (const GDB_Stub &)=delete

GDB_Stub &	operator= (const GDB_Stub &)=delete

Private Attributes
const bool	debug
	Additional debug outputs on the target system (useful for debugging the debugger stub)

Friends
void	gdb_interrupt_handler (DebugContext *context)
	Allow the generic GDB interrupt handler to access the protected methods of this class.

Additional Inherited Members
Public Types inherited from Serial
enum	ComPort { COM1 = 0x3f8 , COM2 = 0x2f8 , COM3 = 0x3e8 , COM4 = 0x2e8 }
	COM-Port. More...

enum	BaudRate { BAUD_300 = 384 , BAUD_600 = 192 , BAUD_1200 = 96 , BAUD_2400 = 48 , BAUD_4800 = 24 , BAUD_9600 = 12 , BAUD_19200 = 6 , BAUD_38400 = 3 , BAUD_57600 = 2 , BAUD_115200 = 1 }
	Transmission speed. More...

enum	DataBits { DATA_5BIT = 0 , DATA_6BIT = 1 , DATA_7BIT = 2 , DATA_8BIT = 3 }
	Number of data bits per character. More...

enum	StopBits { STOP_1BIT = 0 , STOP_1_5BIT = 4 , STOP_2BIT = 4 }
	Number of stop bits per character. More...

enum	Parity { PARITY_NONE = 0 , PARITY_ODD = 8 , PARITY_EVEN = 24 , PARITY_MARK = 40 , PARITY_SPACE = 56 }
	parity bit More...

Protected Attributes inherited from Serial
const ComPort	port
	Selected COM port.

Detailed Description

Remote stub for GNU Debugger (GDB)

Allows remote debugging of the operating system with GDB on real (bare metal) hardware (but also in the emulator) by implementing the main part of the GDB Remote Serial Protocols (RSP), installing own interrupt handler routines for traps and communicating with the GDB host over the serial port.

To use this feature, GDB must be started on the host with the identical kernel binary file as the operating system on the target hardware runs with – ideally in the kernels source code directory, because then the source code can be embedded in the debug output of the GDB host.

In addition, the settings for serial transmission must be identical on both hardware and GDB.

Note: The last (current) trap/interrupt vector handled by the GDB Stub can be queried inside the GDB shell using the command print GDB_Stub::signal.; GDB already comes with the i386-stub.c. However, it is ugly, poorly maintained and not very easy to integrate into this object-oriented operating system. Therefore we use a revised version of Matt Borgersons gdbstub (released 2016 under the GPL v2 license).

Constructor & Destructor Documentation

◆ GDB_Stub() [1/2]

GDB_Stub::GDB_Stub ( const GDB_Stub & )

privatedelete

◆ GDB_Stub() [2/2]

GDB_Stub::GDB_Stub	(	bool	wait = `false`,
		bool	debug_output = `false`,
		ComPort	port = `COM1`,
		BaudRate	baud_rate = `BAUD_9600`
	)

explicit

constructor

configures interrupt handler and serial interface (as 8N1)

Note: To avoid worrying about interrupt handling of the serial port, we initialize Serial in the IOAPIC as usual, however, GDB_Stub won't inherit from Gate – we just replace the interrupt handler for the serial interface: instead of interrupt_handler the serial vector will be handled in the gdb_interrupt_handler by changing the entry routine in the IDT to the one provided by this stub. To be able to this we just have to make sure that gdb_interrupt_entries (NUM_HANDLERS in debug/gdb/handler.asm) is big enough to create an entry routine for the serial vector and make a corresponding call to IDT::handle.

Optional:: Install handler for serial connections receive interrupts

Parameters

wait	Wait for a GDB connection after configuration
debug_output	Debug the stub by printing the communication on the DBG output (could be useful while extending the RSP)
port	COM port for the serial connection
baud_rate	Baud Rate, default for GDB is `9600` (can be a bottleneck)

Member Function Documentation

◆ operator=()

GDB_Stub & GDB_Stub::operator= ( const GDB_Stub & )

privatedelete

◆ configureInterrupt()

void GDB_Stub::configureInterrupt ( bool active )

◆ handle()

void GDB_Stub::handle ( void )

protected

Handling traps.

Called by the generic debug interrupt handler after the current core state has been stored.

This contains the heart functionality of the GDB_Stub, including the communication with the GDB host.

◆ writeString()

int GDB_Stub::writeString	(	const char *	buf,
		size_t	len
	)

protected

Send a string via the serial connection.

Parameters

buf	Pointer to buffer
len	Size of buffer (or characters to transmit)

Return values

0	on success
-1	if no or not all bytes have been sent

◆ readString()

int GDB_Stub::readString	(	char *	buf,
		size_t	buf_len,
		size_t	len
	)

protected

Receive a string via the serial connection.

Parameters

buf	Pointer to buffer
buf_len	Size of buffer
len	Size of received characters

Return values

0	on success
-1	if no or not all bytes have been received

◆ sendPacket()

int GDB_Stub::sendPacket	(	const char *	pkt_data,
		size_t	pkt_len
	)

protected

Transmits a packet of data.

Packets are of the form:

$<packet-data>#<checksum>

Parameters

pkt_data	Pointer to packet buffer
pkt_len	Size of packet buffer

Return values

0	if the packet was transmitted and acknowledged
1	if the packet was transmitted but not acknowledged
-1	otherwise

◆ receivePacket()

int GDB_Stub::receivePacket	(	char *	pkt_buf,
		size_t	pkt_buf_len,
		size_t *	pkt_len
	)

protected

Receives a packet of data assuming a 7-bit clean connection.

Parameters

pkt_buf	Pointer to packet buffer
pkt_buf_len	Size of packet buffer
pkt_len	Size of packet to receive

Return values

0	if the packet was received
-1	otherwise

◆ checksum()

int GDB_Stub::checksum	(	const char *	buf,
		size_t	len
	)

staticprotected

Calculate 8-bit checksum of a buffer.

Parameters

buf	Pointer to buffer
len	Size of buffer

Returns: 8-bit checksum of buffer

◆ receiveAck()

int GDB_Stub::receiveAck ( void )

protected

Receive acknowledgment for a packet.

Note: The key combination [ctrl]+[c]in GDB can be used to stop the running operating system. GDB simply sends the value3` (not ASCII, also no valid packet). Our operating system is usually in this function when receiving this value. We can simply ignore the receipt of the value and wait for the next character – the actual acknowledgement.

Optional:: Extend method to ignore the character \3

Return values

0	received [positive] acknowledgment (ACK, `+`)
1	received negative acknowledgment (NACK, `-`)
-1	otherwise (invalid character)

◆ sendOkPacket()

int GDB_Stub::sendOkPacket ( )

protected

Create and send an OK packet (OK)

Returns: Status code returned from sendPacket

◆ sendSignalPacket()

int GDB_Stub::sendSignalPacket	(	char *	buf,
		size_t	buf_len,
		char	signal
	)

protected

Create and send a signal packet (S [int])

Parameters

buf	Pointer to buffer
buf_len	Size of buffer
signal	Interrupt vector

Returns: Status code returned from sendPacket

◆ sendErrorPacket()

int GDB_Stub::sendErrorPacket	(	char *	buf,
		size_t	buf_len,
		char	error
	)

protected

Create and send an error packet (E [code])

Parameters

buf	Pointer to buffer
buf_len	Size of buffer
error	Error code

Returns: Status code returned from sendPacket

◆ memRead()

int GDB_Stub::memRead	(	char *	buf,
		size_t	buf_len,
		uintptr_t	addr,
		size_t	len,
		bool	hex
	)

staticprotected

Read contents of system memory area into the buffer.

Parameters

buf	Pointer to buffer
buf_len	Size of buffer
addr	Base address of system memory to read from
len	Size of memory area to read from
hex	Buffer content has hexadecimal (`true`) or binary (`false`) encoding

Returns: Number of bytes read or -1 on error (buffer to small)

◆ memWrite()

int GDB_Stub::memWrite	(	const char *	buf,
		size_t	buf_len,
		uintptr_t	addr,
		size_t	len,
		bool	hex
	)

staticprotected

Write buffer contents to system memory area.

Parameters

buf	Pointer to buffer
buf_len	Size of buffer
addr	Base address of system memory to write at
len	Size of memory area to write at
hex	Buffer content has hexadecimal (`true`) or binary (`false`) encoding

Returns: Number of written bytes or -1 on error (buffer to big)

◆ sysContinue()

void GDB_Stub::sysContinue ( void )

staticprotected

Continue program execution (at current instruction pointer)

◆ sysStep()

void GDB_Stub::sysStep ( void )

staticprotected

Single step the next instruction.

Friends And Related Symbol Documentation

◆ gdb_interrupt_handler

void gdb_interrupt_handler ( DebugContext * context )

friend

Allow the generic GDB interrupt handler to access the protected methods of this class.

Similar to the default interrupt_handler. Called by the entry function written in assembly (see debug/gbd/handler.asm) – these routines are installed in the constructor.

After preparing the data this function calls GDB_Stub::handle, which handles the communication with the host via the serial interface.

Optional:: Since this function should now also be triggered by the serial interrupt, the end of interrupt must be signaled.

Parameters

context contains a pointer to the stack, which can be used to access the debug interrupt context.

Member Data Documentation

◆ debug

const bool GDB_Stub::debug

private

Additional debug outputs on the target system (useful for debugging the debugger stub)

◆ signal

int GDB_Stub::signal = 0

static

Last trap/interrupt vector handled in GDB.

store signal to simplify debugging

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

debug/gdb/stub.h
debug/gdb/handler.cc
debug/gdb/protocol.cc

Public Member Functions

Static Public Attributes

Protected Member Functions

Static Protected Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ GDB_Stub() [1/2]

◆ GDB_Stub() [2/2]

Member Function Documentation

◆ operator=()

◆ configureInterrupt()

◆ handle()

◆ writeString()

◆ readString()

◆ sendPacket()

◆ receivePacket()

◆ checksum()

◆ receiveAck()

◆ sendOkPacket()

◆ sendSignalPacket()

◆ sendErrorPacket()

◆ memRead()

◆ memWrite()

◆ sysContinue()

◆ sysStep()

Friends And Related Symbol Documentation

◆ gdb_interrupt_handler

Member Data Documentation

◆ debug

◆ signal