MaxOS::runtime::GDBServer Class Reference

Handler for running a GDB server over serial. More...

#include <gdbstub.h>

Inheritance diagram for MaxOS::runtime::GDBServer:

Public Member Functions
	GDBServer (console::SerialConsole *serial)
	Constructs a handler for remote debugging using GDB, also sets up interrupt handlers for traps and breakpoints.
void	attach (processes::Thread *thread)
	Begin debugging a thread, will start paused.
string	get_checksum (const string &payload)
	Calculates the GDB checksum of a command.
bool	check_checksum (const string &payload, const string &checksum)
	Validates the checksum of a commnad.
string	build_message (const string &payload)
	Converts a message into the form GDB expects, including and ACK package.
void	send_message (const string &payload)
	Converts a message to the required form and sends it over serial.
void	send_empty ()
	Send an empty message to the GDB server.
void	send_supported (const string &peer_supported)
	Sends the features that this GDB stub supports to the GDB server.
void	send_registers ()
	Sends the registers of the thread to the GDB server.
void	send_memory (const string &message)
	Send a chunk of memory to the GDB server.
void	send_memory (void *address, size_t length)
	Send a chunk of memory to the GDB server.
void	send_breakpoint_reached ()
void	handle_step_instruction ()
	Set the trap flag and allow the thread to run.
void	handle_set_breakpoint (const string &message)
	Set a software break point by replacing the instruction with a INT3.
void	handle_set_breakpoint (void *address)
	Set a software break point by replacing the instruction with a INT3.
void	handle_remove_breakpoint (const string &message)
	Remove a software break point, and replace the original opcode.
void	handle_remove_breakpoint (void *address)
	Remove a software break point, and replace the original opcode.
void	handle_continue ()
	Continues the exeuction of the thread, acknowledges the request and allows the thread to run.
void	handle_detach ()
	Detaches the thread from the GDB, removing all breakpoints and allowing it to be scheduled as usual.
processes::Thread *	attached_thread ()
	Get the attached thread.
Public Member Functions inherited from MaxOS::hardwarecommunication::InterruptHandler
virtual system::cpu_status_t *	handle_interrupt (system::cpu_status_t *status)
	Handles an interrupt and returns the status.

Public Attributes
system::cpu_status_t	thread_regs

Additional Inherited Members
Protected Member Functions inherited from MaxOS::hardwarecommunication::InterruptHandler
	InterruptHandler (uint8_t interrupt_number, int64_t redirect=-1, uint64_t redirect_index=0)
	Creates a new interrupt handler and registers it with the interrupt manager.
virtual	~InterruptHandler ()
	Destroys the interrupt handler and unregisters it from the interrupt manager.
Protected Attributes inherited from MaxOS::hardwarecommunication::InterruptHandler
uint8_t	m_interrupt_number
	The interrupt number this handler handles.

Detailed Description

Handler for running a GDB server over serial.

Definition at line 71 of file gdbstub.h.

Constructor & Destructor Documentation

GDBServer()

GDBServer::GDBServer

(

console::SerialConsole *

serial

)

Constructs a handler for remote debugging using GDB, also sets up interrupt handlers for traps and breakpoints.

Parameters

serial

The serial port where GDB will listen/send packets on

Todo:

GDB owns the interrupt here, should move to a serial API

Definition at line 28 of file gdbstub.cpp.

: InterruptHandler(0x24, 4, 0x18),
  m_serial(serial),
  m_trap_flag_handler(this),
  m_break_point_handler(this)
{
}

Member Function Documentation

attach()

void GDBServer::attach

(

processes::Thread *

thread

)

Begin debugging a thread, will start paused.

Parameters

thread

The thread to debug

Definition at line 43 of file gdbstub.cpp.

                                     {
 
    // Pause the thread
    thread->thread_state = ThreadState::WAITING;
 
    // Read the thread info
    m_attached_thread = thread;
    thread_regs = (const cpu_status_t&)m_attached_thread->execution_state;
 
}

References MaxOS::processes::Thread::execution_state, and MaxOS::processes::Thread::thread_state.

attached_thread()

Thread * GDBServer::attached_thread

(

)

Get the attached thread.

Returns

The attached thread

Definition at line 536 of file gdbstub.cpp.

                                   {
 
    return m_attached_thread;
 
}

Referenced by MaxOS::runtime::TrapFlagExcpetion::handle_interrupt(), and MaxOS::runtime::BreakPointException::handle_interrupt().

build_message()

string GDBServer::build_message

(

const string &

payload

)

Converts a message into the form GDB expects, including and ACK package.

Parameters

payload

The message to convert

Returns

The message plus its checksum and the related indicators

Definition at line 258 of file gdbstub.cpp.

                                                     {
    return "+$"s + payload + "#" + get_checksum(payload);
}

References get_checksum().

Referenced by send_message().

check_checksum()

bool GDBServer::check_checksum	(	const string &	payload,
		const string &	checksum
	)

Validates the checksum of a commnad.

Parameters

payload	The command to validate
checksum	The expected checksum

Returns

True if valid, false otherwise

Definition at line 248 of file gdbstub.cpp.

                                                                            {
    return get_checksum(payload).to_lower() == checksum;
}

References get_checksum().

get_checksum()

string GDBServer::get_checksum

(

const string &

payload

)

Calculates the GDB checksum of a command.

Parameters

payload

The command to get the checksum of

Returns

The checksum string, always 2 chars wide

Definition at line 222 of file gdbstub.cpp.

                                                    {
 
    // Sum each character
    uint8_t checksum = 0;
    for (int i = 0; i < payload.length(); ++i)
        checksum += (uint8_t)payload[i];
 
    // Take first 8 bits
    checksum &= 0xFF;
 
    // Convert to hex
    string hex = string((uint64_t)checksum);
    if (hex.length() == 1)
        hex = "0"s + hex;
 
    return hex;
 
}

Referenced by build_message(), and check_checksum().

handle_continue()

void GDBServer::handle_continue

(

)

Continues the exeuction of the thread, acknowledges the request and allows the thread to run.

Definition at line 508 of file gdbstub.cpp.

                                {
 
    // Acknowledge
    m_serial->write_char('+');
 
    // Let the thread be scheduled
    m_attached_thread->thread_state = ThreadState::READY;
}

References MaxOS::processes::Thread::thread_state, and MaxOS::console::SerialConsole::write_char().

handle_detach()

void GDBServer::handle_detach

(

)

Detaches the thread from the GDB, removing all breakpoints and allowing it to be scheduled as usual.

Definition at line 520 of file gdbstub.cpp.

                              {
 
    // Remove all breakpoints
    for (const auto& bp : m_breakpoints)
        handle_remove_breakpoint(bp.first);
 
    // Allow program to continue rest of execution
    m_attached_thread->thread_state = ThreadState::READY;
 
}

References handle_remove_breakpoint(), and MaxOS::processes::Thread::thread_state.

handle_remove_breakpoint() [1/2]

void GDBServer::handle_remove_breakpoint

(

const string &

message

)

Remove a software break point, and replace the original opcode.

Parameters

message

The GDB command requesting the breakpoint removal

Definition at line 457 of file gdbstub.cpp.

                                                              {
 
    // Parse
    Vector<String> parts = message.substring(2,message.length( ) - 2).split(",");
    string address_str = parts[1].to_upper();
 
    handle_remove_breakpoint((void*)address_str.hex_to_uint64());
 
}

References handle_remove_breakpoint().

Referenced by handle_detach(), and handle_remove_breakpoint().

handle_remove_breakpoint() [2/2]

void GDBServer::handle_remove_breakpoint

(

void *

address

)

Remove a software break point, and replace the original opcode.

Parameters

address

The address to break on

Definition at line 472 of file gdbstub.cpp.

                                                      {
 
    // Invaild address
    if (address < (void*)0x1000) {
        send_message("OK");
        return;
    }
 
    // Doesnt exist
    auto breakpoint = m_breakpoints.find(address);
    if (breakpoint == m_breakpoints.end()) {
        send_message("OK");
        return;
    }
 
    // Switch into the processes' address space
    MemoryManager* old = GlobalScheduler::current_process()->memory_manager;
    MemoryManager::switch_active_memory_manager(GlobalScheduler::get_process(m_attached_thread->parent_pid)->memory_manager);
 
    // Replace with old byte
    CPU::disable_write_protect();
    *(uint8_t*)address = breakpoint->second;
    CPU::enable_write_protect();
 
    // Remove reference
    m_breakpoints.erase(breakpoint);
 
    // Restore executing process's address space
    MemoryManager::switch_active_memory_manager(old);
    send_message("OK");
 
}

References MaxOS::processes::GlobalScheduler::current_process(), MaxOS::processes::GlobalScheduler::get_process(), MaxOS::processes::Process::memory_manager, MaxOS::processes::Thread::parent_pid, and send_message().

handle_set_breakpoint() [1/2]

void GDBServer::handle_set_breakpoint

(

const string &

message

)

Set a software break point by replacing the instruction with a INT3.

Parameters

message

The GDB command requesting the breakpoint

Definition at line 405 of file gdbstub.cpp.

                                                           {
 
    // Parse
    Vector<String> parts = message.substring(2,message.length( ) - 2).split(",");
    string address_str = parts[1].to_upper();
 
    handle_set_breakpoint((void*)address_str.hex_to_uint64());
 
}

References handle_set_breakpoint().

Referenced by handle_set_breakpoint().

handle_set_breakpoint() [2/2]

void GDBServer::handle_set_breakpoint

(

void *

address

)

Set a software break point by replacing the instruction with a INT3.

Parameters

address

The address to break on

Definition at line 420 of file gdbstub.cpp.

                                                   {
 
    // Invaild address
    if (address < (void*)0x1000) {
        send_message("OK");
        return;
    }
 
    // Already set or invalid address
    if (m_breakpoints.find(address) != m_breakpoints.end()) {
        send_message("OK");
        return;
    }
 
    // Switch into the processes' address space
    MemoryManager* old = GlobalScheduler::current_process()->memory_manager;
    MemoryManager::switch_active_memory_manager(GlobalScheduler::get_process(m_attached_thread->parent_pid)->memory_manager);
 
    // Store old byte
    uint8_t old_byte = *(uint8_t*)address;
    m_breakpoints.insert(address, old_byte);
 
    // Replace with breakpoint (INT3)
    CPU::disable_write_protect();
    *(uint8_t*)address = 0xCC;
    CPU::enable_write_protect();
 
    // Restore executing process's address space
    MemoryManager::switch_active_memory_manager(old);
    send_message("OK");
}

References MaxOS::processes::GlobalScheduler::current_process(), MaxOS::processes::GlobalScheduler::get_process(), MaxOS::processes::Process::memory_manager, MaxOS::processes::Thread::parent_pid, and send_message().

handle_step_instruction()

void GDBServer::handle_step_instruction

(

)

Set the trap flag and allow the thread to run.

Definition at line 383 of file gdbstub.cpp.

                                        {
 
    // Acknowledge
    m_serial->write_char('+');
 
    // Enable trap flag for the thread and allow it to run
    thread_regs.rflags |= (1 << 8);
    m_attached_thread->thread_state = ThreadState::READY;
 
    // Make sure change is mirrored if not in kernel
    if (thread_regs.rip == m_attached_thread->execution_state.rip)
        m_attached_thread->execution_state.rflags |= (1 << 8);
 
    // wait for the step to occur and be caught by the exception handler
    // ...
}

References MaxOS::processes::Thread::execution_state, MaxOS::processes::Thread::thread_state, and MaxOS::console::SerialConsole::write_char().

send_empty()

void GDBServer::send_empty

(

)

Send an empty message to the GDB server.

Definition at line 275 of file gdbstub.cpp.

                           {
    send_message("");
}

References send_message().

send_memory() [1/2]

void GDBServer::send_memory

(

const string &

message

)

Send a chunk of memory to the GDB server.

Parameters

message

The GDB command requesting the chunk

Definition at line 343 of file gdbstub.cpp.

                                                 {
 
    // Parse
    Vector<String> parts = message.substring(1,message.length( ) - 1).split(",");
    string address_str = parts[0].to_upper();
    string length_str = parts[1].to_upper();
 
    send_memory((void*)address_str.hex_to_uint64(), length_str.hex_to_uint64());
}

References send_memory().

Referenced by send_memory().

send_memory() [2/2]

void GDBServer::send_memory	(	void *	address,
		size_t	length
	)

Send a chunk of memory to the GDB server.

Parameters

address	The start address of the chunk
length	How large the chunk is (in bytes)

Definition at line 359 of file gdbstub.cpp.

                                                        {
 
    // Cant read
    if (address < (void*)0x1000) {
        send_message("E01");
        return;
    }
 
    // Switch into the processes' address space
    MemoryManager* old = GlobalScheduler::current_process()->memory_manager;
    MemoryManager::switch_active_memory_manager(GlobalScheduler::get_process(m_attached_thread->parent_pid)->memory_manager);
 
    // Send data
    String payload(address, length);
    send_message(payload.to_lower());
 
    // Restore executing process's address space
    MemoryManager::switch_active_memory_manager(old);
 
}

References MaxOS::processes::GlobalScheduler::current_process(), MaxOS::processes::GlobalScheduler::get_process(), MaxOS::processes::Process::memory_manager, MaxOS::processes::Thread::parent_pid, and send_message().

send_message()

void GDBServer::send_message

(

const string &

payload

)

Converts a message to the required form and sends it over serial.

Parameters

payload

The message to send

Definition at line 267 of file gdbstub.cpp.

                                                  {
    string message = build_message(payload.c_str());
    m_serial->write(message);
}

References build_message().

Referenced by MaxOS::runtime::TrapFlagExcpetion::handle_interrupt(), MaxOS::runtime::BreakPointException::handle_interrupt(), handle_remove_breakpoint(), handle_set_breakpoint(), send_empty(), send_memory(), send_registers(), and send_supported().

send_registers()

void GDBServer::send_registers

(

)

Sends the registers of the thread to the GDB server.

Definition at line 300 of file gdbstub.cpp.

                               {
 
    string payload = "";
 
    // General Purpose Registers
    payload += format_register(thread_regs.rax, 8);
    payload += format_register(thread_regs.rbx, 8);
    payload += format_register(thread_regs.rcx, 8);
    payload += format_register(thread_regs.rdx, 8);
    payload += format_register(thread_regs.rsi, 8);
    payload += format_register(thread_regs.rdi, 8);
    payload += format_register(thread_regs.rbp, 8);
    payload += format_register(thread_regs.rsp, 8);
 
    // Secondary General Purpose Registers
    payload += format_register(thread_regs.r8, 8);
    payload += format_register(thread_regs.r9, 8);
    payload += format_register(thread_regs.r10, 8);
    payload += format_register(thread_regs.r11, 8);
    payload += format_register(thread_regs.r12, 8);
    payload += format_register(thread_regs.r13, 8);
    payload += format_register(thread_regs.r14, 8);
    payload += format_register(thread_regs.r15, 8);
 
    // Instruction Pointer
    payload += format_register(thread_regs.rip, 8);
 
    // Flags / Segments
    payload += format_register(thread_regs.rflags, 4);
    payload += format_register(thread_regs.cs, 4);
    payload += format_register(thread_regs.ss, 4);
 
    // Remaining
    payload += "x"s * (8 * 4);
 
    send_message(payload);
}

References send_message().

send_supported()

void GDBServer::send_supported

(

const string &

peer_supported

)

Sends the features that this GDB stub supports to the GDB server.

Parameters

peer_supported

The features that the server has indicated that it supports

Definition at line 284 of file gdbstub.cpp.

                                                           {
 
    string out = "PacketSize=4000;qXfer:features:read+;";
 
    // Must support hardware breakpoints
    Vector<string> features = peer_supported.split("+;");
    for (const auto& feature : features)
        if (feature == "hwbreak")
            out += "hwbreak+;";
 
    send_message(out);
}

References send_message().

Member Data Documentation

thread_regs

system::cpu_status_t MaxOS::runtime::GDBServer::thread_regs

Definition at line 119 of file gdbstub.h.

---

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

• /home/runner/work/MaxOS/MaxOS/kernel/include/runtime/gdbstub.h
• /home/runner/work/MaxOS/MaxOS/kernel/src/runtime/gdbstub.cpp