StuBS
GDB_Stub Class Reference

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

#include <debug/gdb/stub.h>

Inheritance diagram for GDB_Stub:
[legend]
Collaboration diagram for GDB_Stub:
[legend]

Public Member Functions

 GDB_Stub (bool wait=false, bool debug_output=false, ComPort port=COM1, BaudRate baud_rate=BAUD_9600)
 constructor More...
 
- 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. More...
 
int read (bool blocking=true)
 Read one byte from the serial interface. More...
 
int write (char out, bool blocking=true)
 Write one byte to the serial interface. More...
 
bool receiveInterrupt (bool enable)
 Activate or deactivate interrupts on data reception. More...
 

Static Public Attributes

static int signal = 0
 Last trap/interrupt vector handled in GDB. More...
 

Protected Member Functions

void handle ()
 Handling traps. More...
 
int writeString (const char *buf, size_t len)
 Send a string via the serial connection. More...
 
int readString (char *buf, size_t buf_len, size_t len)
 Receive a string via the serial connection. More...
 
int sendPacket (const char *pkt_data, size_t pkt_len)
 Transmits a packet of data. More...
 
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. More...
 
int receiveAck (void)
 Receive acknowledgment for a packet. More...
 
int sendOkPacket ()
 Create and send an OK packet (OK) More...
 
int sendSignalPacket (char *buf, size_t buf_len, char signal)
 Create and send a signal packet (S [int]) More...
 
int sendErrorPacket (char *buf, size_t buf_len, char error)
 Create and send an error packet (E [code]) More...
 

Static Protected Member Functions

static int checksum (const char *buf, size_t len)
 Calculate 8-bit checksum of a buffer. More...
 
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. More...
 
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. More...
 
static void sysContinue ()
 Continue program execution (at current instruction pointer)
 
static void sysStep ()
 Single step the next instruction.
 

Friends

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

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.
 
enum  StopBits {
  STOP_1BIT = 0 ,
  STOP_1_5BIT = 4 ,
  STOP_2BIT = 4
}
 Number of stop bits per character.
 
enum  Parity {
  PARITY_NONE = 0 ,
  PARITY_ODD = 8 ,
  PARITY_EVEN = 24 ,
  PARITY_MARK = 40 ,
  PARITY_SPACE = 56
}
 parity bit
 
- 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()

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
waitWait for a GDB connection after configuration
debug_outputDebug the stub by printing the communication on the DBG output (could be useful while extending the RSP)
portCOM port for the serial connection
baud_rateBaud Rate, default for GDB is 9600 (can be a bottleneck)

Member Function Documentation

◆ 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
bufPointer to buffer
lenSize of buffer (or characters to transmit)
Return values
0on success
-1if 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
bufPointer to buffer
buf_lenSize of buffer
lenSize of received characters
Return values
0on success
-1if 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_dataPointer to packet buffer
pkt_lenSize of packet buffer
Return values
0if the packet was transmitted and acknowledged
1if the packet was transmitted but not acknowledged
-1otherwise

◆ 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_bufPointer to packet buffer
pkt_buf_lenSize of packet buffer
pkt_lenSize of packet to receive
Return values
0if the packet was received
-1otherwise

◆ checksum()

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

Calculate 8-bit checksum of a buffer.

Parameters
bufPointer to buffer
lenSize 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 value 3 (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
0received [positive] acknowledgment (ACK, +)
1received negative acknowledgment (NACK, -)
-1otherwise (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
bufPointer to buffer
buf_lenSize of buffer
signalInterrupt 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
bufPointer to buffer
buf_lenSize of buffer
errorError 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
bufPointer to buffer
buf_lenSize of buffer
addrBase address of system memory to read from
lenSize of memory area to read from
hexBuffer 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
bufPointer to buffer
buf_lenSize of buffer
addrBase address of system memory to write at
lenSize of memory area to write at
hexBuffer content has hexadecimal (true) or binary (false) encoding
Returns
Number of written bytes or -1 on error (buffer to big)

Friends And Related Function 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
contextcontains a pointer to the stack, which can be used to access the debug interrupt context.

Member Data Documentation

◆ 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: