From 2e6949e66db3ba264f976b05d81b58285ad1e04b Mon Sep 17 00:00:00 2001
From: Dan Robertson <dan.robertson@anidata.org>
Date: Tue, 5 Dec 2017 01:20:52 +0000
Subject: [PATCH] Add documentation on using gdb

---
 README.md | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d2245dd5..26f1bb68 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,32 @@ Redox OS Microkernel
 [![docs](https://img.shields.io/badge/docs-master-blue.svg)](https://doc.redox-os.org/kernel/kernel/)
 [![](https://tokei.rs/b1/github/redox-os/kernel?category=code)](https://github.com/Aaronepower/tokei)
 
+## Debugging the redox kernel
 
-Documentation is still a work in progress
+Running [qemu] with the `-s` flag will set up [qemu] to listen on port 1234 for
+a [gdb] client to connect to it. To debug the redox kernel run.
 
+```
+make qemu debug=yes
+```
+
+This will start a VM with and listen on port 1234 for a [gdb] client. Run the following
+to connect to it.
+
+```
+(gdb) target remote localhost:1234
+```
+
+This is great, but without debug info debugging can be quite difficult. The
+redox build process strips the kernel of debug info and copies the debug info
+to a separate file `kernel.sym`. You can import these symbols in [gdb] with
+the following
+
+```
+(gdb) symbol-file build/kernel.sym
+```
+
+Now you can set some interesting breakpoints and `continue` the process.
+
+[qemu]: https://www.qemu.org
+[gdb]: https://www.gnu.org/software/gdb/
-- 
GitLab