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.
(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
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!
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]
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.