Add docs for Kelvin ISS simulation and debugging
Change-Id: I03f93743cea1e895b4ccc71a91b42854d940eb76
diff --git a/KelvinIssDebugging.md b/KelvinIssDebugging.md
new file mode 100644
index 0000000..14f4603
--- /dev/null
+++ b/KelvinIssDebugging.md
@@ -0,0 +1,66 @@
+# How to Debug Kelvin ISS
+
+This doc explains how to run kelvin SW in its Instruction Set Simulator (ISS).
+
+## Running Kelvin ISS with Kelvin Sim
+
+Kelvin Sim is the ISS simulator that's built based on
+[MPACT_Sim](https://github.com/google/mpact-sim) and supports all the kelvin
+instructions. It is used for single-core testing and debugging.
+
+**TODO** Add kelvin sim CLI instructions when it sits in `sim/kelvin`
+
+## Running Kelvin ISS with Renode
+
+Kelvin simulator can connect to renode and then be integrated with the full
+`nexus` behavioral simulation framework. As the first step, It uses a rv32im
+placeholder model running non-SIMD binaries so we can test the integrated
+system behaviors
+
+Running the Kelvin SW binary can be done with the following CLIs
+
+```bash
+source build/setup.sh
+
+sim_kelvin <location of the kelvin SW .bin file>
+```
+
+The `.bin` file is the binary blob of the loadable segment parsed by
+`cache/toolchain_kelvin/bin/riscv32-unknown-elf-objcopy`. It is the additional
+output from the Kelvin build rules from either the Bazel build or CMake build
+after the `.elf` executables are built
+
+### Debug Kelvin SW via Renode + GDB
+
+Like Cantrip debugging, Kelvin Renode ISS can also attached to GDB to debug the
+SW, step through the program, and dump the register or memory content.
+
+At the first shell session, run
+
+```bash
+source build/setup.sh
+
+sim_kelvin <.bin file> debug
+```
+
+At the second shell session, run GDB as
+
+```bash
+cache/toolchain/bin/riscv32-unknown-elf-gdb -ex "target remote: 3333" <elf path>
+```
+
+Notice we load the actual `.elf` executable here so we can get the symbols and
+proper address. After the Renode GDBServer is attached to GDB, GDB will
+automatically start the Renode simulation (without actually running the program)
+
+Set up the proper breakpoints on the GDB console then continue the execution, e.g.,
+
+```bash
+b main
+continue
+```
+
+**Note**: Once GDB is attached to the Renode simuation, you can start stepping
+the execution without `run` or set up the breakpoint at the entry of the
+executable. In fact, the first breakpoint can be captured relieably if it is ___after___
+the entry address.
