KelvinIssDebugging.md - docs - Git at Google

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

 Running the Kelvin SW binary can be done with the following CLIs

 ```bash
 source build/setup.sh
 m kelvin_sim
 sim_kelvin <elf file path>
 ```

 The bash function detects the file type by ELF's *magic_bytes* and launches the `kelvin_sim`. `kelvin_sim` runs the exetuable, and depends on the terminator ops
 `mpause` or `ebreak`, it prints out different messages before exit the simulator.

 Illegal instruction also terminates the simulation, with the fault PC printed out.

 ### Debug Kelvin SW via Kelvin Sim

 ```bash
 sim_kelvin <elf file path> debug
 ```

 It launches `kelvin_sim` in the interactive mode. It acts as a debugger, with
 `break`, `run`, and `step` available for instructions. Use `help` to see the
 supported debug functions.

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

	Running the Kelvin SW binary can be done with the following CLIs

	```bash
	source build/setup.sh
	m kelvin_sim
	sim_kelvin <elf file path>
	```

	The bash function detects the file type by ELF's magic_bytes and launches the `kelvin_sim`. `kelvin_sim` runs the exetuable, and depends on the terminator ops
	`mpause` or `ebreak`, it prints out different messages before exit the simulator.

	Illegal instruction also terminates the simulation, with the fault PC printed out.

	### Debug Kelvin SW via Kelvin Sim

	```bash
	sim_kelvin <elf file path> debug
	```

	It launches `kelvin_sim` in the interactive mode. It acts as a debugger, with
	`break`, `run`, and `step` available for instructions. Use `help` to see the
	supported debug functions.

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