# Debug RISC-V assembly with QEMU and GDB

In this tutorial, we will write RISC-V assembly code, run it in the QEMU emulator and debug it using GDB, the GNU debugger.

First, we write a short manifest file so that we can pull in all the tools we need using the ever-convenient Guix.

## Install the required tools

```
(use-modules (gnu packages cross-base)
             (gnu packages gdb)
             (gnu packages virtualization))

(define cross-base
  (@@ (gnu packages cross-base) cross))

(packages->manifest
 (list (cross-base gdb "riscv64")
       (cross-binutils "riscv64")
       qemu))
```
Put the above in a file manifest.scm, and run
```
$ guix shell -m manifest.scm
```
This drops us into a shell with a gdb, as, ld and qemu for riscv64.
```
[env]$ which riscv64-gdb riscv64-as riscv64-ld qemu-riscv64
/gnu/store/…-profile/bin/riscv64-gdb
/gnu/store/…-profile/bin/riscv64-as
/gnu/store/…-profile/bin/riscv64-ld
/gnu/store/…-profile/bin/qemu-riscv64
```

## Assemble, link and run a Hello World RISC-V assembly program

Here we have a simple Hello World program that prints the string "Hello World" using the write syscall (64) and exits with status 0 using the exit syscall (93).
```
        .global _start
        
        .data
str:    .string "Hello world!\n"

        .text
_start: li a0, 1                # stdout file descriptor
        la a1, str              # load address of str
        li a2, 13               # length of str
        li a7, 64               # write syscall
        ecall

exit:   li a0, 0                # set exit code
        li a7, 93               # exit syscall
        ecall
```
We put this in a file hello.s, assemble and link it. When assembling, we pass the -gstabs flag so that GDB debugging information is generated.
```
[env]$ riscv64-as hello.s -gstabs -o hello.o
[env]$ riscv64-ld hello.o -o hello
```
Now that we have our executable, we can run it in qemu.
```
[env]$ qemu-riscv64 hello
Hello World!
```

## Debug using GDB

We run the hello executable in qemu but tell it to wait for a gdb connection on port 1234.
```
[env]$ qemu-riscv64 -g 1234 hello
```
While qemu is waiting in a shell, in another shell we run gdb and connect to port 1234.
```
[env]$ riscv64-gdb hello
(gdb) target remote :1234
Remote debugging using :1234
_start () at hello.s:7
7	_start: li a0, 1                # stdout file descriptor
```
We have dropped into debugging the program at the _start label in the program. We may step through the instructions one by one using the next command.
```
(gdb) next
8	        la a1, str              # load address of str
(gdb) next
9	        li a2, 13               # length of str
(gdb) next
10	        li a7, 64               # write syscall
```
We may continue normal execution using the continue command.
```
(gdb) continue
Continuing.
[Inferior 1 (process 1) exited normally]
```
Finally, quit.
```
(gdb) quit
```

## Other useful gdb commands

We may also set breakpoints at different labels using the break command. For example, to break execution at the exit label:
```
(gdb) break exit
```
We may print memory or the value of CPU registers. To print the value of CPU register a0 using
```
(gdb) print $a0
```
If register a0 contains a memory address, we may print, say 10 bytes, at that address using
```
(gdb) x/10xb $a0
0x12000:	0x48	0x65	0x6c	0x6c	0x6f	0x20	0x77	0x6f
0x12008:	0x72	0x6c
```
Or, we may print 10 characters at that address.
```
(gdb) x/10cb $a0
0x12000:	72 'H'	101 'e'	108 'l'	108 'l'	111 'o'	32 ' '	119 'w'	111 'o'
0x12008:	114 'r'	108 'l'
```
There are many more commands. Here is a good GDB cheatsheet listing the commonly used ones.
=> https://darkdust.net/files/GDB%20Cheat%20Sheet.pdf