Add debug mode using mini-gdbstub submodules

This patch provide an experimental solution that lets rv32emu support a small
set of GDB Remote Serial Protocol packet with the mini-gdbstub library. After
this patch, we could connect our emulator to GDB and interact with
some simple commands like printing current program counter(`print $pc`) or
unpausing the execution(`continue`).

It's worth mentioning that we only enable to use single breakpoint on
rv32emu under this patch. It will be improved in the future.

Author: RinHizakura

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "riscv-arch-test"]
 	path = tests/riscv-arch-test
 	url = https://github.com/riscv-non-isa/riscv-arch-test
+[submodule "mini-gdbstub"]
+	path = mini-gdbstub
+	url = https://github.com/RinHizakura/mini-gdbstub.git

Makefile

@@ -55,6 +55,23 @@ $(OUT)/emulate.o: CFLAGS += -fno-gcse -fno-crossjumping
 endif
 endif
 
+MINI_GDBSTUB :=
+ENABLE_GDBRSP ?= 1
+ifeq ("$(ENABLE_GDBRSP)", "1")
+CFLAGS += -D ENABLE_GDBRSP
+LDFLAGS += -Wl,-rpath="$(CURDIR)/mini-gdbstub" -L./mini-gdbstub -lgdbstub
+MINI_GDBSTUB += ./mini-gdbstub/libgdbstub.so
+$(MINI_GDBSTUB):
+	git submodule update --init mini-gdbstub
+	$(MAKE) -C mini-gdbstub
+$(OUT)/emulate.o: $(MINI_GDBSTUB)
+OBJS_EXT += gdbrsp.o
+endif
+
+# Clear the .DEFAULT_GOAL special variable, so that the following turns
+# to the first target after .DEFAULT_GOAL is not set.
+.DEFAULT_GOAL :=
+
 all: $(BIN)
 
 OBJS := \

README.md

@@ -112,6 +112,35 @@ Detail in riscv-arch-test:
 
 Add `-D` to enable and `-U` to disable the specific ISA extensions.
 
+## Debugging mode with GDB remote serial protocal
+
+By supporting a small set of
+[GDB Remote Serial Protocol](https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html#Remote-Protocol)
+, `rv32emu` is allowed to be run as gdbstub experimentally. To enable this feature, you should
+first configure the `ENABLE_GDBRSP` to 1 in the Makefile and build the emulator. After that,
+ you could run it with the following command.
+
+```
+./build/rv32emu --debug <binary>
+```
+
+The `<binary>` should be the ELF in riscv32 format. You are also recommended to compile
+your program with `-g` option to generate debug information in your ELF.
+
+
+If the emulator starts correctly without exit, you can then execute the riscv-gdb. Two GDB
+commands are required first to hint the supported architecture of the emulator to GDB (also
+provide debugging symbol if there's any) and then connect to the emulator.
+
+```
+$ riscv32-unknown-elf-gdb
+(gdb) file <binary>
+(gdb) target remote :1234
+```
+
+If there's no error message from the riscv-gdb, congratulate! You can now interact with
+the emulator from the GDB command line now!
+
 ## External sources
 
 In `rv32emu` repository, there are some prebuilt ELF files for testing purpose.

emulate.c

@@ -13,6 +13,10 @@ static inline int isinff(float x)
 #endif
 #endif
 
+#ifdef ENABLE_GDBRSP
+#include "gdbrsp.h"
+#endif
+
 #include "riscv.h"
 #include "riscv_private.h"
 
@@ -1672,6 +1676,58 @@ static inline bool op_unimp(struct riscv_t *rv, uint32_t insn UNUSED)
     return false;
 }
 
+#ifdef ENABLE_GDBRSP
+void rv_debug(struct riscv_t *rv)
+{
+    if (!gdbstub_init(&rv->gdbstub, &rv_ops,
+                      (arch_info_t){
+                          .reg_num = 33,
+                          .reg_byte = 4,
+                          .target_desc = TARGET_RV32,
+                      },
+                      "127.0.0.1:1234")) {
+        return;
+    }
+
+    if (!gdbstub_run(&rv->gdbstub, (void *) rv)) {
+        return;
+    }
+    gdbstub_close(&rv->gdbstub);
+}
+
+bool rv_get_breakpoint(struct riscv_t *rv, riscv_word_t *addr)
+{
+    assert(rv && addr);
+    if (!rv->bp_is_set)
+        return false;
+
+    *addr = rv->bp_addr;
+    return true;
+}
+
+bool rv_set_breakpoint(struct riscv_t *rv, riscv_word_t addr)
+{
+    assert(rv);
+    if (rv->bp_is_set)
+        return false;
+
+    rv->bp_is_set = true;
+    rv->bp_addr = addr;
+    return true;
+}
+
+bool rv_reset_breakpoint(struct riscv_t *rv, riscv_word_t bp_addr)
+{
+    assert(rv);
+    if (!rv->bp_is_set || bp_addr != rv->bp_addr)
+        return false;
+
+    rv->bp_is_set = false;
+    rv->bp_addr = 0;
+    return true;
+}
+#endif /* ENABLE_GDBRSP */
+
 void rv_step(struct riscv_t *rv, int32_t cycles)
 {
     assert(rv);
@@ -1884,6 +1940,12 @@ riscv_word_t rv_get_reg(struct riscv_t *rv, uint32_t reg)
     return ~0U;
 }
 
+uint8_t rv_get_mem(struct riscv_t *rv, uint32_t addr)
+{
+    assert(rv);
+    return rv->io.mem_read_b(rv, addr);
+}
+
 struct riscv_t *rv_create(const struct riscv_io_t *io, riscv_user_t userdata)
 {
     assert(io);

gdbrsp.c

@@ -0,0 +1,77 @@
+#include <assert.h>
+#include "mini-gdbstub/include/gdbstub.h"
+#include "riscv.h"
+
+static size_t rv_read_reg(void *args, int regno)
+{
+    struct riscv_t *rv = (struct riscv_t *) args;
+
+    if (regno < 32) {
+        return rv_get_reg(rv, regno);
+    } else if (regno == 32) {
+        return rv_get_pc(rv);
+    }
+
+    return -1;
+}
+
+static void rv_read_mem(void *args, size_t addr, size_t len, void *val)
+{
+    struct riscv_t *rv = (struct riscv_t *) args;
+
+    for (size_t i = 0; i < len; i++)
+        *((uint8_t *) val + i) = rv_get_mem(rv, addr);
+}
+
+static gdb_action_t rv_cont(void *args)
+{
+    struct riscv_t *rv = (struct riscv_t *) args;
+    const uint32_t cycles_per_step = 1;
+    riscv_word_t bp_addr;
+
+    for (; !rv_has_halted(rv);) {
+        if (rv_get_breakpoint(rv, &bp_addr) && (rv_get_pc(rv) == bp_addr)) {
+            break;
+        }
+        rv_step(rv, cycles_per_step);
+    }
+
+    return ACT_RESUME;
+}
+
+static gdb_action_t rv_stepi(void *args)
+{
+    struct riscv_t *rv = (struct riscv_t *) args;
+    rv_step(rv, 1);
+    return ACT_RESUME;
+
+}
+
+static bool rv_set_bp(void *args, size_t addr, bp_type_t type)
+{
+    struct riscv_t *rv = (struct riscv_t *) args;
+    if (type != BP_SOFTWARE)
+        return false;
+
+    return rv_set_breakpoint(rv, addr);
+}
+
+static bool rv_rm_bp(void *args, size_t addr, bp_type_t type)
+{
+    struct riscv_t *rv = (struct riscv_t *) args;
+    if (type != BP_SOFTWARE)
+        return false;
+    // It's fine when there's no matching breakpoint, just doing nothing
+    rv_reset_breakpoint(rv, addr);
+
+    return true;
+}
+
+struct target_ops rv_ops = {
+    .read_reg = rv_read_reg,
+    .read_mem = rv_read_mem,
+    .cont = rv_cont,
+    .stepi = rv_stepi,
+    .set_bp = rv_set_bp,
+    .rm_bp = rv_rm_bp,
+};

gdbrsp.h

@@ -0,0 +1,3 @@
+#pragma once
+
+extern struct target_ops rv_ops;

main.c

@@ -7,6 +7,10 @@
 
 /* enable program trace mode */
 static bool opt_trace = false;
+#ifdef ENABLE_GDBRSP
+/* enable program gdbstub mode */
+static bool opt_gdbstub = false;
+#endif
 
 /* RISCV arch-test */
 static bool opt_arch_test = false;
@@ -60,6 +64,13 @@ static void run_and_trace(struct riscv_t *rv, elf_t *elf)
     }
 }
 
+#ifdef ENABLE_GDBRSP
+static void run_debug(struct riscv_t *rv)
+{
+    rv_debug(rv);
+}
+#endif
+
 static void run(struct riscv_t *rv)
 {
     const uint32_t cycles_per_step = 100;
@@ -76,6 +87,9 @@ static void print_usage(const char *filename)
             "Usage: %s [options] [filename]\n"
             "Options:\n"
             "  --trace : print executable trace\n"
+#ifdef ENABLE_GDBRSP
+            "  --gdbstub: execute emulator in gdbstub mode\n"
+#endif
             "  --arch-test [filename] : dump signature to the given file, "
             "required by arch-test test\n",
             filename);
@@ -94,6 +108,12 @@ static bool parse_args(int argc, char **args)
                 opt_trace = true;
                 continue;
             }
+#ifdef ENABLE_GDBRSP
+            if (!strcmp(arg, "--gdbstub")) {
+                opt_gdbstub = true;
+                continue;
+            }
+#endif
             if (!strcmp(arg, "--arch-test")) {
                 opt_arch_test = true;
                 if (i + 1 >= argc) {
@@ -199,7 +219,13 @@ int main(int argc, char **args)
     /* run based on the specified mode */
     if (opt_trace) {
         run_and_trace(rv, elf);
-    } else {
+    }
+#ifdef ENABLE_GDBRSP
+    else if (opt_gdbstub) {
+        run_debug(rv);
+    }
+#endif
+    else {
         run(rv);
     }
 

mini-gdbstub

@@ -99,6 +99,20 @@ void rv_delete(struct riscv_t *);
 /* reset the RISC-V processor */
 void rv_reset(struct riscv_t *, riscv_word_t pc);
 
+#ifdef ENABLE_GDBRSP
+/* Run the RISCV-emulator in debug mode */
+void rv_debug(struct riscv_t *rv);
+
+/* Get the breakpoint address by breakpoint's number */
+bool rv_get_breakpoint(struct riscv_t *, riscv_word_t *bp_addr);
+
+/* Set the breakpoint address by breakpoint's number */
+bool rv_set_breakpoint(struct riscv_t *, riscv_word_t bp_addr);
+
+/* Reset the breakpoint address by breakpoint's number */
+bool rv_reset_breakpoint(struct riscv_t *, riscv_word_t bp_addr);
+#endif
+
 /* step the RISC-V emulator */
 void rv_step(struct riscv_t *, int32_t cycles);
 
@@ -117,6 +131,9 @@ void rv_set_reg(struct riscv_t *, uint32_t reg, riscv_word_t in);
 /* get a register of the RISC-V emulator */
 riscv_word_t rv_get_reg(struct riscv_t *, uint32_t reg);
 
+/* get a byte from the memory of the RISC-V emulator */
+uint8_t rv_get_mem(struct riscv_t *, uint32_t reg);
+
 /* system call handler */
 void syscall_handler(struct riscv_t *rv);
 

riscv.h

@@ -1,6 +1,9 @@
 #pragma once
 #include <stdbool.h>
 
+#ifdef ENABLE_GDBRSP
+#include "mini-gdbstub/include/gdbstub.h"
+#endif
 #include "riscv.h"
 
 #define RV_NUM_REGS 32
@@ -138,6 +141,15 @@ struct riscv_t {
     /* user provided data */
     riscv_user_t userdata;
 
+#ifdef ENABLE_GDBRSP
+    /* gdbstub instance */
+    gdbstub_t gdbstub;
+
+    /* GDB instruction breakpoint */
+    bool bp_is_set;
+    riscv_word_t bp_addr;
+#endif
+
 #ifdef ENABLE_RV32F
     /* float registers */
     union {