Enable GDB debugging with event-driven coroutine #106

jserv · 2025-10-31T03:43:19Z

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

Summary by cubic

Adds non-blocking GDB remote debugging using an event-driven mini-gdbstub. Supports breakpoints, single-step, and register/memory inspect with per-hart control for SMP, without changing WFI coroutine behavior.

New Features
- Event-driven GDB I/O (kqueue/epoll) runs alongside coroutines; no blocking.
- Breakpoints and single-step with per-hart suspend/resume in SMP.
- Exec loop integrates breakpoint checks and single-step; continue/step and breakpoint set/delete wired to gdbstub.
Migration
- No change for normal runs; debugging is off unless you pass -g.
- Start with: semu -g ... and connect GDB to 127.0.0.1:1234.
- Optional: scripts/test-gdb.sh verifies connection, stepping, and breakpoints.

^{Written for commit 9236b58. Summary will update automatically on new commits.}

cubic-dev-ai

3 issues found across 9 files

Prompt for AI agents (all 3 issues)


Understand the root cause of the following 3 issues and fix them.


<file name="coro.h">

<violation number="1" location="coro.h:47">
Debug suspend should not reuse the same CORO_STATE_SUSPENDED flag that WFI uses; otherwise coro_is_suspended() cannot distinguish WFI from debugger freezes and the scheduler will treat breakpoints as WFI sleeps.</violation>

<violation number="2" location="coro.h:59">
coro_step_hart() should verify that the hart really yielded back; currently it always returns true even if the coroutine keeps running, so a failed step request is silently reported as success.</violation>
</file>

<file name="scripts/test-gdb.sh">

<violation number="1" location="scripts/test-gdb.sh:11">
`set -e` causes the script to abort on the first failing GDB command, so tests cannot report failures as intended. Allow the commands to fail and let the logging logic handle the result.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

coro.h

cubic-dev-ai · 2025-11-02T15:57:02Z

coro.h

+ * The hart will not be scheduled until explicitly resumed.
+ * This is different from WFI suspension.
+ */
+void coro_suspend_hart_debug(uint32_t hart_id);


Debug suspend should not reuse the same CORO_STATE_SUSPENDED flag that WFI uses; otherwise coro_is_suspended() cannot distinguish WFI from debugger freezes and the scheduler will treat breakpoints as WFI sleeps.

Prompt for AI agents

Address the following comment on coro.h at line 47: <comment>Debug suspend should not reuse the same CORO_STATE_SUSPENDED flag that WFI uses; otherwise coro_is_suspended() cannot distinguish WFI from debugger freezes and the scheduler will treat breakpoints as WFI sleeps.</comment> <file context> @@ -37,3 +37,23 @@ bool coro_is_suspended(uint32_t slot_id); + * 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 */ </file context>

scripts/test-gdb.sh

cubic-dev-ai

1 issue found across 9 files

Prompt for AI agents (all 1 issues)


Understand the root cause of the following 1 issues and fix them.


<file name="scripts/test-gdb.sh">

<violation number="1" location="scripts/test-gdb.sh:134">
Because the script runs with `set -e`, a failing `timeout` here will abort the entire suite instead of recording a failed test. Please guard the `timeout` invocation so the test can report the failure instead of exiting immediately.</violation>
</file>

_{React with 👍 or 👎 to teach cubic. Mention @cubic-dev-ai to give feedback, ask questions, or re-run the review.}

scripts/test-gdb.sh

RinHizakura · 2025-11-02T15:52:54Z

gdbctrl.h

+
+/* Set a breakpoint at the specified address
+ * @vm: VM instance
+ * @addr: Virtual address for breakpoint


Could it be confusing for the term "Virtual address"?

RinHizakura · 2025-11-02T15:53:09Z

gdbctrl.h

+
+/* Delete a breakpoint at the specified address
+ * @vm: VM instance
+ * @addr: Virtual address of breakpoint to remove


RinHizakura · 2025-11-02T15:55:15Z

gdbctrl.h

+ */
+uint32_t gdb_get_breakpoint_count(vm_t *vm);
+
+/* Suspend a hart for debugging (breakpoint or user interrupt)


Doesn't "user interrupt" resume a hart instead of suspend?

RinHizakura · 2025-11-02T15:58:24Z

gdbctrl.c

+    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;


Just came up with the idea that we may combine enabled and addr together by using the bit0.

But such optimization can be minor, and it could be fine in debug mode.

RinHizakura · 2025-11-02T16:01:59Z

riscv.h

+    hart_state_t state;       /**< Current debug state */
+    bool single_step_mode;    /**< True if single-stepping */
+    bool breakpoint_pending;  /**< Breakpoint check needed */
+    uint32_t last_stopped_pc; /**< PC where hart last stopped */


I don't see when this field will be used. In the PR, it is only assigned with value but seems to never be checked anywhere.

RinHizakura · 2025-11-02T16:16:35Z

coro.c

+     */
+    coro_t *co = coro_state.coroutines[hart_id];
+    if (co && co->state == CORO_STATE_SUSPENDED)
+        coro_resume_hart(hart_id);


It looks like we can remove the if condition here, as the same thing will be checked again in coro_resume_hart

RinHizakura · 2025-11-02T16:17:29Z

coro.c

+
+void coro_suspend_hart_debug(uint32_t hart_id)
+{
+    if (hart_id >= coro_state.n_hart || !coro_state.initialized)


I don't see coro_state has the field n_hart...? Can you check the compilation? It should fail.

RinHizakura · 2025-11-02T16:21:41Z

coro.c

+    return (co && co->state == CORO_STATE_SUSPENDED);
+}
+
+bool coro_step_hart(uint32_t hart_id)


Logically, this is the same as calling coro_resume_hart. Isn't it?

If so, I suggest we just let coro_resume_hart return the error value, and call coro_resume_hart under coro_step_hart directly, instead of doing so many duplicate checks.

Add 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. Key components: - gdbctrl.c/h: GDB control layer for breakpoint and hart suspension management - coro.c/h: Debug-specific suspend/resume functions for SMP debugging - main.c: Integrate GDB callbacks with hart execution loop and single-step logic - riscv.h: Debug state structures (hart_state_t, hart_debug_info_t, vm_debug_ctx_t) - scripts/test-gdb.sh: Automated test suite validating GDB functionality 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

jserv requested review from Mes0903 and ranvd October 31, 2025 03:44

jserv force-pushed the coro-gdb branch from 4b3f8f5 to ac1abdc Compare October 31, 2025 03:48

jserv requested a review from shengwen-tw October 31, 2025 03:51

This comment was marked as resolved.

Sign in to view

jserv force-pushed the coro-gdb branch 3 times, most recently from 8188ee6 to 59ca149 Compare November 2, 2025 15:47

sysprog21 deleted a comment from cubic-dev-ai bot Nov 2, 2025

cubic-dev-ai bot reviewed Nov 2, 2025

View reviewed changes

scripts/test-gdb.sh Outdated Show resolved Hide resolved

RinHizakura reviewed Nov 2, 2025

View reviewed changes

sysprog21 deleted a comment from cubic-dev-ai bot Nov 2, 2025

RinHizakura reviewed Nov 2, 2025

View reviewed changes

jserv force-pushed the coro-gdb branch 3 times, most recently from e6f4075 to 20d3cf9 Compare November 2, 2025 16:37

jserv force-pushed the coro-gdb branch from 20d3cf9 to 9236b58 Compare November 2, 2025 16:37

Enable GDB debugging with event-driven coroutine #106

Are you sure you want to change the base?

Enable GDB debugging with event-driven coroutine #106

Conversation

jserv commented Oct 31, 2025 • edited by cubic-dev-ai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by cubic

Uh oh!

This comment was marked as resolved.

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai bot Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

RinHizakura Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

RinHizakura Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

RinHizakura Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

RinHizakura Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

RinHizakura Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RinHizakura Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RinHizakura Nov 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RinHizakura Nov 2, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jserv commented Oct 31, 2025 •

edited by cubic-dev-ai bot

Loading

cubic-dev-ai bot Nov 2, 2025 •

edited

Loading

RinHizakura Nov 2, 2025 •

edited

Loading

RinHizakura Nov 2, 2025 •

edited

Loading

RinHizakura Nov 2, 2025 •

edited

Loading