Enable GDB debugging with event-driven coroutine

This adds full GDB remote debugging support using mini-gdbstub with
event-driven I/O (kqueue/epoll) to enable non-blocking debugging without
interfering with the existing WFI coroutine system. This provides
breakpoints, single-step, register/memory inspection, and multi-hart
debugging for SMP configurations.

Architecture:
- Single-hart mode (n_hart=1): Direct execution with debug state tracking
- SMP mode (n_hart>1): Coroutine-based with per-hart debug suspend/resume
- Event-driven GDB I/O prevents blocking during debug operations
- Preserves existing WFI coroutine semantics unchanged

Author: jserv

Makefile

@@ -170,6 +170,7 @@ OBJS := \
 	main.o \
 	aclint.o \
 	coro.o \
+	gdbctrl.o \
 	$(OBJS_EXTRA)
 
 deps := $(OBJS:%.o=.%.o.d)

coro.c

@@ -1,10 +1,11 @@
 /* Lightweight coroutine for multi-hart execution */
 
-#include "coro.h"
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 
+#include "coro.h"
+
 /* Platform detection */
 
 #if !defined(CORO_USE_UCONTEXT) && !defined(CORO_USE_ASM)
@@ -602,3 +603,67 @@ uint32_t coro_current_hart_id(void)
 {
     return coro_state.current_hart;
 }
+
+/* Debug-related coroutine functions for GDB integration */
+
+void coro_suspend_hart_debug(uint32_t hart_id)
+{
+    if (hart_id >= coro_state.n_hart || !coro_state.initialized)
+        return;
+
+    /* Mark the hart as suspended for debugging.
+     * The scheduler should skip this hart until resumed.
+     */
+    coro_t *co = coro_state.coroutines[hart_id];
+    if (co && co->state != CORO_STATE_DEAD)
+        co->state = CORO_STATE_SUSPENDED;
+}
+
+void coro_resume_hart_debug(uint32_t hart_id)
+{
+    if (hart_id >= coro_state.n_hart || !coro_state.initialized)
+        return;
+
+    /* Resume the hart from debug suspension by delegating to coro_resume_hart.
+     * This ensures proper state transition and actually jumps into the
+     * coroutine, rather than just setting the state flag which would cause the
+     * scheduler to refuse resumption on the next iteration.
+     */
+    coro_t *co = coro_state.coroutines[hart_id];
+    if (co && co->state == CORO_STATE_SUSPENDED)
+        coro_resume_hart(hart_id);
+}
+
+bool coro_is_debug_suspended(uint32_t hart_id)
+{
+    if (hart_id >= coro_state.n_hart || !coro_state.initialized)
+        return false;
+
+    coro_t *co = coro_state.coroutines[hart_id];
+    return (co && co->state == CORO_STATE_SUSPENDED);
+}
+
+bool coro_step_hart(uint32_t hart_id)
+{
+    if (hart_id >= coro_state.n_hart || !coro_state.initialized)
+        return false;
+
+    coro_t *co = coro_state.coroutines[hart_id];
+    if (!co)
+        return false;
+
+    /* Only allow stepping if hart is currently suspended */
+    if (co->state != CORO_STATE_SUSPENDED)
+        return false;
+
+    /* Resume the coroutine for one instruction.
+     * DO NOT manually set state to RUNNING before calling coro_resume_hart(),
+     * as that function requires SUSPENDED state and will handle the transition.
+     * The hart coroutine should check single_step_mode and yield after one
+     * instruction.
+     */
+    coro_resume_hart(hart_id);
+
+    /* It should have yielded after one instruction and be suspended again */
+    return true;
+}

coro.h

@@ -42,3 +42,23 @@ bool coro_is_suspended(uint32_t hart_id);
  * Returns: Hart ID of the currently executing coroutine, or UINT32_MAX if idle
  */
 uint32_t coro_current_hart_id(void);
+
+/* Debug-related coroutine functions for GDB integration */
+
+/* Suspend a hart for debugging (e.g., hit breakpoint)
+ * The hart will not be scheduled until explicitly resumed.
+ * This is different from WFI suspension.
+ */
+void coro_suspend_hart_debug(uint32_t hart_id);
+
+/* Resume a hart from debug suspension */
+void coro_resume_hart_debug(uint32_t hart_id);
+
+/* Check if a hart is suspended for debugging */
+bool coro_is_debug_suspended(uint32_t hart_id);
+
+/* Execute exactly one instruction on a hart (for single-step debugging)
+ * This will resume the hart, execute one instruction, then suspend again.
+ * Returns: true on success, false if hart is not in valid state
+ */
+bool coro_step_hart(uint32_t hart_id);

gdbctrl.c

@@ -0,0 +1,202 @@
+/* GDB control layer for coroutine-based multi-hart execution */
+
+#include <string.h>
+
+#include "coro.h"
+#include "gdbctrl.h"
+
+bool gdb_debug_init(vm_t *vm)
+{
+    if (!vm)
+        return false;
+
+    /* Initialize debug context */
+    memset(&vm->debug_ctx, 0, sizeof(vm_debug_ctx_t));
+
+    /* Initialize debug info for all harts */
+    for (uint32_t i = 0; i < vm->n_hart; i++) {
+        hart_t *hart = vm->hart[i];
+        if (!hart)
+            continue;
+
+        memset(&hart->debug_info, 0, sizeof(hart_debug_info_t));
+        hart->debug_info.state = HART_STATE_RUNNING;
+        hart->debug_info.single_step_mode = false;
+        hart->debug_info.breakpoint_pending = false;
+        hart->debug_info.last_stopped_pc = 0;
+    }
+
+    return true;
+}
+
+void gdb_debug_cleanup(vm_t *vm)
+{
+    if (!vm)
+        return;
+
+    /* Clear all breakpoints */
+    gdb_clear_all_breakpoints(vm);
+
+    /* Reset all hart debug states */
+    for (uint32_t i = 0; i < vm->n_hart; i++) {
+        hart_t *hart = vm->hart[i];
+        if (!hart)
+            continue;
+
+        hart->debug_info.state = HART_STATE_RUNNING;
+        hart->debug_info.single_step_mode = false;
+        hart->debug_info.breakpoint_pending = false;
+        hart->debug_info.last_stopped_pc = 0;
+    }
+}
+
+bool gdb_check_breakpoint(hart_t *hart)
+{
+    if (!hart || !hart->vm)
+        return false;
+
+    vm_t *vm = hart->vm;
+    uint32_t pc = hart->pc;
+
+    /* Check if current PC matches any enabled breakpoint */
+    for (uint32_t i = 0; i < vm->debug_ctx.bp_count; i++) {
+        breakpoint_t *bp = &vm->debug_ctx.breakpoints[i];
+        if (bp->enabled && bp->addr == pc) {
+            /* Breakpoint hit */
+            hart->debug_info.breakpoint_pending = true;
+            hart->debug_info.last_stopped_pc = pc;
+            return true;
+        }
+    }
+
+    return false;
+}
+
+bool gdb_set_breakpoint(vm_t *vm, uint32_t addr)
+{
+    if (!vm)
+        return false;
+
+    /* Check if breakpoint already exists at this address */
+    for (uint32_t i = 0; i < vm->debug_ctx.bp_count; i++) {
+        if (vm->debug_ctx.breakpoints[i].addr == addr) {
+            /* Already exists, just ensure it's enabled */
+            vm->debug_ctx.breakpoints[i].enabled = true;
+            return true;
+        }
+    }
+
+    /* Check if we have room for a new breakpoint */
+    if (vm->debug_ctx.bp_count >= MAX_BREAKPOINTS)
+        return false;
+
+    /* Add new breakpoint */
+    breakpoint_t *bp = &vm->debug_ctx.breakpoints[vm->debug_ctx.bp_count];
+    bp->addr = addr;
+    bp->enabled = true;
+    vm->debug_ctx.bp_count++;
+
+    return true;
+}
+
+bool gdb_del_breakpoint(vm_t *vm, uint32_t addr)
+{
+    if (!vm)
+        return false;
+
+    /* Find the breakpoint */
+    for (uint32_t i = 0; i < vm->debug_ctx.bp_count; i++) {
+        if (vm->debug_ctx.breakpoints[i].addr == addr) {
+            /* Found it - remove by shifting remaining breakpoints down */
+            uint32_t remaining = vm->debug_ctx.bp_count - i - 1;
+            if (remaining > 0) {
+                memmove(&vm->debug_ctx.breakpoints[i],
+                        &vm->debug_ctx.breakpoints[i + 1],
+                        remaining * sizeof(breakpoint_t));
+            }
+            vm->debug_ctx.bp_count--;
+            return true;
+        }
+    }
+
+    return false;
+}
+
+void gdb_clear_all_breakpoints(vm_t *vm)
+{
+    if (!vm)
+        return;
+
+    memset(&vm->debug_ctx.breakpoints, 0, sizeof(vm->debug_ctx.breakpoints));
+    vm->debug_ctx.bp_count = 0;
+}
+
+uint32_t gdb_get_breakpoint_count(vm_t *vm)
+{
+    if (!vm)
+        return 0;
+
+    return vm->debug_ctx.bp_count;
+}
+
+void gdb_suspend_hart(hart_t *hart)
+{
+    if (!hart)
+        return;
+
+    /* Mark hart as suspended for debugging */
+    hart->debug_info.state = HART_STATE_DEBUG_BREAK;
+    hart->debug_info.last_stopped_pc = hart->pc;
+
+    /* Suspend the coroutine (only in SMP mode) */
+    if (hart->vm && hart->vm->n_hart > 1)
+        coro_suspend_hart_debug(hart->mhartid);
+}
+
+void gdb_resume_hart(hart_t *hart)
+{
+    if (!hart)
+        return;
+
+    /* Clear breakpoint pending flag */
+    hart->debug_info.breakpoint_pending = false;
+
+    /* If single-step mode is enabled, mark as DEBUG_STEP instead of RUNNING */
+    if (hart->debug_info.single_step_mode) {
+        hart->debug_info.state = HART_STATE_DEBUG_STEP;
+    } else {
+        hart->debug_info.state = HART_STATE_RUNNING;
+    }
+
+    /* Resume the coroutine (only in SMP mode) */
+    if (hart->vm && hart->vm->n_hart > 1) {
+        coro_resume_hart_debug(hart->mhartid);
+    }
+}
+
+void gdb_enable_single_step(hart_t *hart)
+{
+    if (!hart)
+        return;
+
+    hart->debug_info.single_step_mode = true;
+    hart->debug_info.state = HART_STATE_DEBUG_STEP;
+}
+
+void gdb_disable_single_step(hart_t *hart)
+{
+    if (!hart)
+        return;
+
+    hart->debug_info.single_step_mode = false;
+    if (hart->debug_info.state == HART_STATE_DEBUG_STEP)
+        hart->debug_info.state = HART_STATE_RUNNING;
+}
+
+bool gdb_is_single_stepping(hart_t *hart)
+{
+    if (!hart)
+        return false;
+
+    return hart->debug_info.single_step_mode;
+}

gdbctrl.h

@@ -0,0 +1,80 @@
+/* GDB control layer for coroutine-based multi-hart execution */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include "riscv.h"
+
+/* Initialize GDB debug subsystem for a VM
+ * @vm: VM instance to initialize debugging for
+ * Returns: true on success, false on failure
+ */
+bool gdb_debug_init(vm_t *vm);
+
+/* Cleanup GDB debug subsystem
+ * @vm: VM instance to cleanup
+ */
+void gdb_debug_cleanup(vm_t *vm);
+
+/* Check if a hart has hit a breakpoint at its current PC
+ * This should be called before executing each instruction.
+ * @hart: Hart to check
+ * Returns: true if breakpoint hit, false otherwise
+ */
+bool gdb_check_breakpoint(hart_t *hart);
+
+/* Set a breakpoint at the specified address
+ * @vm: VM instance
+ * @addr: Virtual address for breakpoint
+ * Returns: true on success, false if breakpoint table is full
+ */
+bool gdb_set_breakpoint(vm_t *vm, uint32_t addr);
+
+/* Delete a breakpoint at the specified address
+ * @vm: VM instance
+ * @addr: Virtual address of breakpoint to remove
+ * Returns: true if breakpoint was found and removed, false otherwise
+ */
+bool gdb_del_breakpoint(vm_t *vm, uint32_t addr);
+
+/* Clear all breakpoints
+ * @vm: VM instance
+ */
+void gdb_clear_all_breakpoints(vm_t *vm);
+
+/* Get breakpoint count
+ * @vm: VM instance
+ * Returns: Number of active breakpoints
+ */
+uint32_t gdb_get_breakpoint_count(vm_t *vm);
+
+/* Suspend a hart for debugging (breakpoint or user interrupt)
+ * This marks the hart as DEBUG_BREAK and prevents it from being scheduled.
+ * @hart: Hart to suspend
+ */
+void gdb_suspend_hart(hart_t *hart);
+
+/* Resume a hart from debug suspension
+ * This marks the hart as RUNNING and allows it to be scheduled.
+ * @hart: Hart to resume
+ */
+void gdb_resume_hart(hart_t *hart);
+
+/* Enable single-step mode for a hart
+ * The hart will execute one instruction then suspend again.
+ * @hart: Hart to single-step
+ */
+void gdb_enable_single_step(hart_t *hart);
+
+/* Disable single-step mode for a hart
+ * @hart: Hart to disable single-stepping
+ */
+void gdb_disable_single_step(hart_t *hart);
+
+/* Check if a hart is in single-step mode
+ * @hart: Hart to check
+ * Returns: true if single-stepping, false otherwise
+ */
+bool gdb_is_single_stepping(hart_t *hart);