Skip to main content

Getting Started

Here's a detailed guide on how to get started with the hwdbg debugger.

Deployment Board​

This repository contains pre-built TCL files to facilitate project creation for running hwdbg on various FPGA development boards.

Output​

For generating SystemVerilog files, you need to install Chisel. Once installed, use the following commands:

$ sbt run

This command prompts you to select a component. The hwdbg.Main class contains the debugger for synthesis purposes, while the hwdbg.MainWithInitializedBRAM class includes a pre-initialized Block RAM (BRAM), primarily for simulation and testing.

After selecting the appropriate class for synthesis (option 1) or simulation (option 2), the output should look like this:

$ sbt run
[info] welcome to sbt 1.9.7 (Eclipse Adoptium Java 17.0.10)
[info] loading settings for project -build-build-build from metals.sbt ...
[info] loading project definition from /home/sina/HyperDbg//project/project/project
[info] loading settings for project -build-build from metals.sbt ...
[info] loading project definition from /home/sina/HyperDbg//project/project
[success] Generated .bloop/-build-build.json
[success] Total time: 1 s, completed Apr 16, 2024, 1:49:05 PM
[info] loading settings for project -build from metals.sbt,plugins.sbt ...
[info] loading project definition from /home/sina/HyperDbg//project
[success] Total time: 0 s, completed Apr 16, 2024, 1:49:05 PM
[info] loading settings for project root from build.sbt ...
[info] set current project to hwdbg (in build file:/home/sina/HyperDbg/hwdbg/)

Multiple main classes detected. Select one to run:
 [1] hwdbg.Main
 [2] hwdbg.MainWithInitializedBRAM

Enter number: 2
[info] running hwdbg.MainWithInitializedBRAM

The generated code for the debugger can be found in the generated directory.

Testbenches​

To test hwdbg, cocotb should be installed. After that, first, run the debugger (generated SystemVerilog files) and then run the following commands:

cd sim/hwdbg/DebuggerModuleTestingBRAM
./test.sh

The above command generates a waves file at ./sim/hwdbg/DebuggerModuleTestingBRAM/sim_build/DebuggerModuleTestingBRAM.fst which can be read using GTKWave.

cd sim/hwdbg/DebuggerModuleTestingBRAM
gtkwave ./sim_build/DebuggerModuleTestingBRAM.fst

ModelSim​

If you prefer to use ModelSim instead of GTKWave, you can configure the modelsim.config file. Please visit here for more information.

API​

If you want to create the latest version of API documentation, you can run the following command:

$ sbt doc

This will generate documentation at ./target/scala-{version}/api/index.html.