SW Debugger API

Overview

This debugger was specially developed as a software utility to interact with our SOC implementation in riscv_soc repository. The main purpose was to provide convinient way to develop and debug our Satellite Navigation firmware that can not be debugged by any other tool provided RISC-V community. Additionally, we would like to use the single unified application capable to work with Real and Simulated platforms without any modification of source code. Debugger provides base functionality such as: run control, read/write memory, registers and CSRs, breakpoints. It allows to reload FW image and reset target. Also we are developing own version of the CPU simulator (analog of spike) that can be extended with peripheries models to Full SOC simulator. These extensions for the debugger simplify porting procedure of the Operating System (Zephyr project) so that simulation doesn't require any hardware and allow develop SW simultaneously with HW developing.

C++ Project structure

General idea of the project is to develop one Core library providing API methods for registering classes, services, attributes and methods to interact with them. Each extension plugin registers one or several class services performing some usefull work. All plugins are built as an independent libraries that are opening by Core library at initialization stage with the call of method plugin_init(). All Core API methods start with RISCV_... prefix:

void RISCV_register_class(IFace *icls);

IFace *RISCV_create_service(IFace *iclass, const char *name, 
                            AttributeType *args);

IFace *RISCV_get_service(const char *name);
...

Configuration of the debugger and plugins is fully described in JSON formatted configuration files targets/target_name.json. These files store all instantiated services names, attributes values and interconnect among plugins. This configuration can be saved to/load from file at any time. By default command exit will save current debugger state into file (including full command history).

Note

You can manually add/change new Registers/CSRs names and indexes by modifying this config file without changing source code.

Folders description

1. libdgb64g - Core library (so/dll) that provides standard API methods defined in file api_core.h.
2. appdbg64g - Executable (exe) file implements functionality of the console debugger.
3. Plugins:
   1. simple_plugin - Simple plugin (so/dll library) just for demonstration of the integration with debugger.
   2. cpu_fnc_plugin - Functional model of the RISC-V CPU (so/dll library).
   3. cpu_sysc_plugin - Precise SystemC model of RIVER CPU (so/dll library).
   4. socsim_plugin - Functional models of the peripheries and assembled board (so/dll library). This plugin registers several classes: UART, GPIO, SRAM, ROMs and etc.

Debug Target

We provide several targets that can run your software (bootloader, firmware or user application) without source code modifications:

Start Configuration	Description
$ ./_run_functional_sim.sh[bat]	Functional RISC-V Full System Model
$ ./_run_systemc_sim.sh[bat]	Use SystemC Precise Model of RIVER CPU
$ ./_run_fpga_gui.sh[bat]	FPGA board. Default port 'COM3', TAP IP = 192.168.0.51

To run debugger with real FPGA target connected via Ethernet do:

*     # cd rocket_soc/debugger/win32build/debug
*     # _run_functional_sim.bat
* 

The result should look like on the picture below:

Plugins interaction structure

Core library uses UDP protocol to communicate with all targets: FPGA or simulators. The general structure is looking like on the following figure:

or with real Hardware

Troubleshooting

Image Files not found

If you'll get the error messages that image files not found

To fix this problem do the following steps:

1. Close debugger console using exit command.
2. Open config_file_name.json file in any editor.
3. Find strings that specify these paths and correct them. Simulator uses the same images as VHDL platform for ROMs intialization. You can find them in 'rocket_soc/fw_images' directory. After that you should see something like follow:

Debug your target. All commands that are available for Real Hardware absolutely valid for the Simulation. Debugger doesn't see any difference between these two targets.

Note

We redirect all output streams of the simulated platform into debugger console but we are going to implement independent GUI for simulated platform with its own UART/GPIO or Ethernet outputs and serial console window.

Can't open COM3 when FPGA is used

1. Open fpga_gui.json
2. Change value ['ComPortName','COM3'], on your one (for an example on ttyUSB0).

EDCL: No response. Break read transaction

This erros means that host cannot locate board with specified IP address. Before you continue pass through the following checklist:

1. You should properly setup network connection and see FPGA board in ARP-table.
2. If you've changed default FPGA IP address:
   1. Open fpga_gui.json
   2. Change value ['BoardIP','192.168.0.51'] on your one.
3. Run debugger

Example of debugging session (Switch ON all User LEDs on board):

riscv# help                     -- Print full list of commands
riscv# csr MCPUID               -- Read supported ISA extensions
riscv# read 0xfffff000 20       -- Read 20 bytes from PNP module
riscv# write 0x80000000 4 0xff  -- Write into GPIO new LED value
riscv# loadelf helloworld       -- Load elf-file to board RAM and run

Debugger console view