Description
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.
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:
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:
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:
The above command generates a waves file at ./sim/hwdbg/DebuggerModuleTestingBRAM/sim_build/DebuggerModuleTestingBRAM.fst which can be read using GTKWave.
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:
This will generate documentation at ./target/scala-{version}/api/index.html.
License
hwdbg and all its submodules and repos, unless a license is otherwise specified, are licensed under GPLv3 LICENSE.
