The hwdbg debugger chip generator is a gate-level debugging tool designed to make configurable and synthesizable hardware debuggers for white-box and black-box chip fuzzing, testing, and reverse engineering. The primary goal of hwdbg is to provide control over hardware, enabling monitoring and modification of signals down to the granular level of a single clock cycle. It is written in Chisel and Verilog.

• ⚠️ This project is a work in progress and is not yet ready for testing.

hwdbg is a highly customizable debugger designed to ease hardware debugging by bringing software debugging concepts into the hardware debugging domain. hwdbg aims to help with the complexities associated with debugging hardware, including chips and IP cores. Key features of hwdbg include the ability to step through the hardware design at the clock-cycle level, visualize waveforms, inspect values (e.g., like a logical analyzer), and modify signals. Moreover, it is synthesizable into FPGAs and has the potential for fabrication into physical chips.

            ┏━━━━━━━━━━━━━━━━━━━━━━━┓
     _             _  _             ┃
    | |_  _ _ _  _| || |_  ___      ┃
    | . || | | |/ . || . \/ . |     ┃
    |_|_||__/_/ \___||___/\_. |     ┃
                          <___'     ┃
                                    ┃      ╱|、
  HyperDbg's chip-level debugger    ┃     (˚ˎ 。7
                                    ┃     |、 ˜〵
            ┗━━━━━━━━━━━━━━━━━━━━━━━┛     じしˍ,)ノ

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

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.

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

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

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.

hwdbg and all its submodules and repos, unless a license is otherwise specified, are licensed under GPLv3 LICENSE.