Package: libhgdb
hgdb is a flexible hardware debugging framework. It offers runtime
APIs to interact with the simulator.Core featureshgdb is designed to be versatile and provides an abstraction to
facilitate hardware debugging. It offers the following features:Breakpoints, including step-over and conditional breakpoint.Frame/context reconstruction with complex data types.Full reverse debugging in replay mode, and limited capability in interactive
debugging.Set signal values in interactive debuggingSymbol table and query. No RTL modification required.High-level synthesis (HLS) support.Supported SimulatorsThe simulators listed below have been tested in regression tests.
Theoretically hgdb can run on any Verilog/SystemVerilog specification
compliant simulator.Cadence® Xcelium™Synopsys VCS®Mentor Questa®VerilatorIcarus VerilogSupported Generator FrameworksWe are working on passes to extract symbol tables from different
generator frameworks. The list below will be growing!Chisel/Firrtl, viahgdb-firrtl.CIRCT, native support. Current requires patchhere.Kratos, native support.LegUp (HLS), experimental support, viahgdb-legup.Xilinx Vitis (HLS), viahgdb-vitis.Hand-written Verilog/SystemVerilog, viahgdb-rtl.UsageThe easiest way to get started is to install the compiled shared object
viapip. To do so, simply typepip install libhgdbYou can find the download shared library using the following one-linerpython-c"import pkgutil; print(pkgutil.get_loader('libhgdb').path)"You can copy it or symbolic link to places you want to use.Compile from sourceTo compile it from source, you need a C++20 compatible compiler, such asgcc-10orclang-10. Make sure that git submodules are properly cloned.gitclone--recurse-submodules-j8https://github.com/Kuree/hgdbcdhgdbmkdirbuild&&cdbuild&&cmake..makehgdb-jYou should see the compiled shared library inbuild/src/How to use it with simulatorsIf you have installed hgdb viapip, you can directly use the wrapper
script to invoke popular simulators. For instance, you can usehgdb-vcsin lieu ofvcsand reuse the exact command line arguments. The wrapper
scripts insert proper flags to enable hgdb. Here is a list of tools:hgdb-vcshgdb-xrunhgdb-vsimhgdb-verilatorhgdb-vvpIf you want more freedom or you compile hgdb from source,
you need to provide specific flags to the simulator in order to load the
runtime. Notice that in most cases you need to make sure that the
simulator can findlibhgdb.so. The easiest way is to invoke commands
withLD_LIBRARY_PATH=${hgdb_lib_path}$, where${hgdb_lib_path}is the directory containinglibhgdb.so. Here are some examples on
how to use it with different simulators.Cadence® Xcelium™xrun[commands]-access+rw-loadvpilibhgdb.so:initialize_hgdb_runtimeSynopsys VCS®vcs[commands]-debug_acc+all-loadlibhgdb.soMentor Questa®vsim[flags]-plilibghdb.soVerilatorVerilator is a little bit tedious since it is not specification-compliant.First, we need to generate the verilator files with extra VPI flagsverilator[flags]--vpi${path_to_libhgdb.so}``In addition, most signals should be labeled as public, otherwise breakpoints and frame
inspection will not work. An easy way is to use--public-flat-rwflag when invokingverilator. In addition to the flags, we need add following code to the test bench:Forward declare the runtime call:namespacehgdb{voidinitialize_hgdb_runtime_cxx();}At the beginning of the test bench code:hgdb::initialize_hgdb_runtime_cxx();Also make sureargcandargvare properly passed to verilator:Verilated::commandArgs(argc,argv);At each posedge of the clock, we need to call specific callback:VerilatedVpi::callCbs(cbNextSimTime);You can check out thisexample test benchfor more details.Icarus VerilogIcarus Verilog only takes shared library with.vpiextension. As a result,
it is a good idea to simply symbolic linklibhgdb.sotolibhgdb.vpiin the
current working directory.
When you run the compiled circuit withvvp, add the following command:vvp-M.-mlibhgdb[commands]Runtime command-line argumentsYou can change the runtime settings using plus-args when invoking the simulator. Here is
a short list of options you can change:+DEBUG_PORT=num, wherenumis the port number. By default this is8888+DEBUG_LOG=1, enable the debugging log. Useful when debugging the behavior of the
runtimeThere are several predefined environment variables one can use to debug the runtime. It
is not recommended for production usage:DEBUG_DISABLE_BLOCKING: when present, will disable the initial blocking. As a result,
the simulator will starts execution without user’s explicit “start” or “continue”
command.DEBUG_DATABASE_FILENAME=filename: when present, will preload the debug table into the system.DEBUG_BREAKPOINT#=filename:line_num@[condition]: where#counts from 0. The runtime will
query the predefined breakpoints starting from 0 and stops if corresponding environment
variable name not found.conditionis optional.DEBUG_PERF_COUNT: when present, the system will collect performance information. Only valid
when the library is build with-DPERF_COUNT=ONwhen invokingcmake.DEBUG_PERF_COUNT_LOG: when set, the system will dump the performance data into the set value
instead of cout;Which debugger to usehgdb offers several open-sourced debuggers:Visual Studio Code Debugger Extensiongdb-style debuggerYou can check out the debuggershere.Reverse-debugginghgdb supports full reverse-debugging via trace file. Users can forward
and backward any time, with breakpoint support. This is achieved by a
trace replay tool that implements hgdb’s compatibility layer. The tool,hgdb-replay, is shipped withlibhgdbpackage. To use it, simply dohgdb-replaywaveform.vcd[args]where[args]are optional arguments passed to the debug runtime. Due to
the license issue, the public release version of hgdb does not build with
FSDB. You have to first load Verdi (or setting$VERDI_HOME) and then build
the project from source. This allowshgdb-replayautomatically detects FSDB
waveforms.Source-level waveformhgdb also supports source-level waveform by rewriting existing waveform against
the symbol table. The rewritten waveform will produce source-level
constructs, such asBundleand arrays. Currently only VCD format is
supported. The rewrite toolhgdb-rewrite-vcdis shipped withlibhgdbpackage.$hgdb-rewrite-vcd<original.vcd><debug.db><new.vcd>Symbol table generationThe symbol table used by hgdb is designed to be compiler-friendly and
language-independent. Hardware generator framework developers should
check thisdocumentout to see more details.Available language bindingsBelow shows a list of language bindings offered by hgdb and their implementation statusC/C++:creationqueryruntimePython:creationquerySystemVerilog:runtimetcl:queryCitationYou can check the pre-print version atarxiv(DAC ‘22).@misc{https://doi.org/10.48550/arxiv.2203.05742,
doi = {10.48550/ARXIV.2203.05742},
url = {https://arxiv.org/abs/2203.05742},
author = {Zhang, Keyi and Asgar, Zain and Horowitz, Mark},
title = {Bringing Source-Level Debugging Frameworks to Hardware Generators},
publisher = {arXiv},
year = {2022},
}