KelvinIssDebugging.md

# 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.