How to run GDB on Athena

In the first window:
  1. ssh <your kerb>@athena.dialup.mit.edu
  2. add -f 6.828
  3. git clone git://g.csail.mit.edu/xv6-labs-2022 (omit if you already have cloned the lab repo)
  4. cd xv6-labs-2022
  5. make qemu-gdb
  6. Note the last line of the output of the previous command. It should say something like tcp::<PORT NUMBER HERE>. For example, you might see tcp::26000
In the second window:
  1. ssh <your kerb>@athena.dialup.mit.edu
  2. add -f 6.828
  3. cd xv6-labs-2022
  4. riscv64-unknown-elf-gdb
  5. Inside the gdb prompt: target remote localhost:<PORT NUMBER FROM POINT 6 ABOVE>
Say you wanted to break every time the kernel enters the function syscall from kernel/syscall.c
  1. Inside the gdb prompt: file kernel/kernel (this is a binary that has all kernel code)
  2. Inside the gdb prompt: b syscall
  3. Hit c. At this point you will start hitting the breakpoint above
  4. Keep hitting c to see where the kernell hits the syscall function. You will how the output in the first window is progressing.
Now, say you wanted to break in the ls function in user/ls.c. Then, you would need to run file user/_ls at step 6 since this is the name of the binary where that function is. You would also run b ls in step 7.

Common issues with running GDB

  1. Running GDB from the wrong directory. You need to run make qemu-gdb AND riscv64-unknown-elf-gdb (or the alternative gdb-multiarch) inside the xv6-labs-2022 directory. Not in ~ and not in xv6-labs-2022/kernel or xv6-labs-2022/user.
  2. Forgetting to add the Athena locker with the tools for the class. See step 2 above (add -f 6.828). This is only relevant if you are on Athena.
  3. Running the wrong type of gdb. If you run just gdb, it will not be able to understand the machine code that your binary is in (your computer/Athena is using x86 and the binary kernel/kernel is using RISCV). You need to run riscv64-unknown-elf-gdb or the alternative gdb-multiarch. If you are on Athena, run riscv64-unknown-elf-gdb.
  4. gdb not being able to find what you are trying to debug. You might need to run target remote localhost:<PORT NUMBER FROM POINT 6 ABOVE>, including if you are running on Athena.
  5. Not adding in the file that you are trying to debug. If you get an error that says something about running file command or unknown symbol, you need to run file kernel/kernel so that gdb knows where to look to find the code you are trying to debug.
  6. If you quit GDB, and then re-run gdb-multiarch (or riscv64-unknown-elf-gdb) without also re-running make qemu-gdb, weird things might happen. Most of the times it works but sometimes it does not and then you just need to restart both and start over. This might exhibit itself in a behavior of GDB not being responsive to your requests.
  7. If you are using Athena, make sure that the two windows are on the same Athena machine. You can find out what machine you are on by checking out the beginning of each prompt line. It will say <your kerb>@<Athena machine name>. If you have trouble getting the two windows to be on the same machine, you can checkout tmux.
  8. Not using GDB to help you debug! I know that using GDB is really annoying in the beginning but it is super super helpful in the later labs and we want you all to know the basic commands to make debugging less painful in the future.