[docs] Minor fixes in the documentation (#264)

* convert debug tutorial from markdown to rst
* Use XelateX for specific symbols
* Minor fixes to remove most of existing warnings

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

@@ -1,22 +1,26 @@
-# How to Debug
+How to Debug
+==============
 
-## How to debug the security monitor (bbl) and the linux kernel?
+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 compile with debugging symbols
 
-```bash
+.. code-block:: bash
+
 # in your <build directory>
 cmake -DCMAKE_BUILD_TYPE=Debug ..
-```
+
 
 From your `build` directory where you ran `make`, use:
 
-```bash
+.. code-block:: bash
+
 ./scripts/run-qemu.sh -debug
-```
+
 
 All cores will immediately hang at the first instruction (i.e., bootrom), waiting for `gdb` to be attached.
 
@@ -26,43 +30,49 @@ bbl binary or the kernel image to add debug information.
 
 For example, if you want to debug with the `bbl` symbols
 
-```bash
+.. code-block:: bash
+
 # in your <build directory>
 riscv64-unknown-linux-gnu-gdb ./sm.build/platform/generic/firmware/fw_payload.elf
-```
+
 
 If you want to debug with the kernel's debug information
 
-```bash
+.. code-block:: bash
+
 # in your <build directory>
 riscv64-unknown-linux-gnu-gdb ./linux.build/vmlinux
-```
+
 
 Then, attach to QEMU on the port printed by the starting qemu script:
 
-```bash
+.. code-block:: bash
+
 (gdb) target remote localhost:$PORT
-```
+
 
 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:
 
-```
+.. code-block:: bash
+
 (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
+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
+.. code-block:: bash
+
 ./riscv-qemu/riscv64-softmmu/qemu-system-riscv64 -d in_asm -D debug.log #...etc...
-```
+

docs/source/Getting-Started/QEMU-Setup-Repository.rst

@@ -3,8 +3,7 @@ Setup
 
 In this stage, you will (1) install RISC-V toolchain, (2) checkout git submodules, and (3) Install
 SDK.
-You can either quickly setup everything (:ref:`QEMUSetupQuick`) or manually setup
-(:ref:`QEMUSetupManual`).
+You can either quickly setup everything (:ref:`QEMUSetupQuick`) or manually setup.
 
 .. _QEMUSetupQuick:
 

docs/source/Getting-Started/Running-Keystone-on-CVA6.rst

@@ -35,7 +35,7 @@ Setting up the CVA6
 ---------------------
 
 FPGA Emulation / Software Simulation
-################
+####################################
 
 Keystone can either be simulated (https://github.com/openhwgroup/cva6#memory-preloading) or FPGA emulated (https://github.com/openhwgroup/cva6#corev-apu-fpga-emulation) on the Xilinx Genesys 2 board 
 (https://digilent.com/reference/programmable-logic/genesys-2/reference-manual)
@@ -60,16 +60,16 @@ bootloader itself. (Likely never)
 
 
 The CVA6 image uses a simplified structure due to bootloader ROM integration on the device:
-::
-  #!/bin/bash
+:: code-block:: bash
+#!/bin/bash
 
-  set -e
+set -e
 
-  # format disk
-  sgdisk --clear --new=1:2048:67583 --new=2 --typecode=1:3000 --typecode=2:8300 /dev/sdc
+# format disk
+sgdisk --clear --new=1:2048:67583 --new=2 --typecode=1:3000 --typecode=2:8300 /dev/sdc
 
-  # flash image
-  dd if=sm.build/platform/generic/firmware/fw_payload.bin  of=/dev/sdc1 status=progress oflag=sync bs=1M
+# flash image
+dd if=sm.build/platform/generic/firmware/fw_payload.bin  of=/dev/sdc1 status=progress oflag=sync bs=1M
 
 
 Running on the CVA6

docs/source/Getting-Started/Running-Keystone-on-Unleashed.rst

@@ -1,5 +1,5 @@
 SiFive HiFive Unleashed Hardware Deployment
-===========================
+===========================================
 
 Building Keystone 
 ----------------------------------------

docs/source/Keystone-Applications/SDK-Basics.rst

@@ -47,9 +47,9 @@ The best way to see how to write a simple application is to look a the
 
 A full system for using a Keystone enclave consists of possibly
 writing 3 things:
- - Host (userspace, outside enclave, untrusted)
- - Runtime (system level, inside enclave, trusted) - most users will not modify this
- - Enclave app (userspace, inside enclave, trusted)
+- Host (userspace, outside enclave, untrusted)
+- Runtime (system level, inside enclave, trusted) - most users will not modify this
+- Enclave app (userspace, inside enclave, trusted)
 
 Most users will only need to write a simple Host, and use the Eyrie
 runtime. The bulk of the work is done in the enclave application, and

docs/source/conf.py

@@ -110,7 +110,7 @@
 
 
 # -- Options for LaTeX output ------------------------------------------------
-
+latex_engine = 'xelatex'
 latex_elements = {
     # The paper size ('letterpaper' or 'a4paper').
     #

docs/source/index.rst

@@ -15,6 +15,9 @@ Welcome to Keystone Enclave's documentation!
    Getting-Started/index
    Getting-Started/How-Keystone-Works/index
    Getting-Started/How-to-Debug
+   Getting-Started/Running-Keystone-on-CVA6
+   Getting-Started/Running-Keystone-on-RV32
+   Getting-Started/Running-Keystone-on-Unleashed
    Getting-Started/Tutorials/index
    Getting-Started/FAQ
 
@@ -35,7 +38,6 @@ Welcome to Keystone Enclave's documentation!
    :caption: Building Keystone Components:
    :numbered:
 
-   Building-Components/Security-Monitor-Platform-Build
    Building-Components/Eyrie