[Documentation] Added How-to-Debug.md

docs/source/Getting-Started/How-to-Debug.md

@@ -0,0 +1,64 @@
+# How to Debug
+
+## How to debug the security monitor (bbl) and the linux kernel?
+
+We use QEMU+GDB to debug the security monitor or the kernel.  
+QEMU is an effective way to debug them.  
+
+First, add `-s -S` flags to the QEMU command.  
+You can simply edit `run-qemu.sh` to add `-s -S` flags.
+
+```bash
+./riscv-qemu/riscv64-softmmu/qemu-system-riscv64 -s -S #...etc...
+```
+
+All cores will immediately hang at the first instruction (i.e., bootrom), waiting for `gdb` to be attached.
+
+Now, run `gdb` in another terminal.  
+You can feed it with the bbl binary or the kernel image to add debug information.  
+(You may want to compile them with the debugging flag `-g`)  
+
+For example, if you want to debug with the `bbl` symbols
+
+```bash
+riscv64-unknown-linux-gnu-gdb ./riscv-pk/build/bbl
+```
+
+If you want to debug with the kernel's debug information
+
+```bash
+riscv64-unknown-linux-gnu-gdb ./riscv-linux/vmlinux
+```
+
+Then, attach to QEMU:
+
+```bash
+(gdb) target remote localhost:1234
+```
+
+Now, you can start debugging the SM (bbl) or the kernel.  
+Try to set breakpoints and run.  
+
+Before setting breakpoints, you should run following command:
+
+```
+(gdb) set riscv use_compressed_breakpoints no
+```
+
+To see why we need that command, see [this issue](https://github.com/riscv/riscv-binutils-gdb/issues/106)
+
+## Logging QEMU debug messages
+
+QEMU provides a great option to collect the logs.  
+If you add `-D [filename]` flag to the QEMU command, it will print out the logs into `[filename]`.  
+
+You can also choose which kind of logs you want to print out, using `-d [options]` flag.  
+For example,
+
+```bash
+./riscv-qemu/riscv64-softmmu/qemu-system-riscv64 -d in_asm -D debug.log #...etc...
+```
+
+## Using `debug.sh`
+Actually, `debug.sh` contains everything you need.  
+run `debug.sh`, run gdb, and attach to QEMU!

docs/source/conf.py

@@ -38,17 +38,15 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
-]
+extensions = ['recommonmark']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
 
 # The master toctree document.
 master_doc = 'index'

docs/source/index.rst

@@ -15,6 +15,7 @@ Welcome to Keystone Enclave's documentation!
    Getting-Started/index
    Getting-Started/How-Keystone-Works/index
    Getting-Started/Guide-to-Components
+   Getting-Started/How-to-Debug
    Getting-Started/FAQ
 
 .. toctree::