The debugger · Soft Forge HDL Studio

Press F5 on a testbench (see the Quick start). The session pauses at 0 fs when stopAtEntry is on, which is the default.

A breakpoint in the counter process is hit; Step Over walks the sequential statements, a hover shows a signal's value, and Step Time advances to the next activity. — A breakpoint in `counter.vhdl`, *Continue*, three *Step Over*, a hover, two *Step Time* (Ctrl+F10), *Continue* again.

Actions#

Action	What it does
Breakpoint in a process or subprogram	stops there; supports conditions and hit counts
Step Over / Into / Out	sequential statements; leaving a process moves to the next time step
Step Time (`Ctrl`+`F10`, debug toolbar)	advances to the next time with activity, or by the step set with HDL Studio: Set Step Time…
Run For… (`Ctrl`+`Shift`+`F11`, debug toolbar)	advances by a duration such as `100 ns`
Step Back (`Ctrl`+`Shift`+`F10`) and HDL Studio: Run Back To…	rewinds a recorded session; see Time travel
Variables → Signals	the design hierarchy with current values; edit a value to deposit it
Variables → right-click a signal → Break on Value Change	a data breakpoint; give it a condition such as `x"5"` to stop on that value only
Breakpoints → Assertion Failures	stops where an `assert` fails, with the failing line on top of the stack
Hover / Watch	any signal name, or a hierarchical suffix such as `dut.value`

The Debug Console#

Command
`run <time>`	run for a duration, e.g. `run 100 ns`
`step`	to the next time step with activity
`force <signal> <value>`	deposit a value: `'1'`, `"0101"`, `x"5"`, `5`
`gdb <command>`	pass a command to GDB
`help`	list the commands

launch.json#

A launch configuration is optional: F5 works without one, from the open file or the workspace file. Write one when you need other options:

jsonc
{
  "type": "ghdl",
  "request": "launch",
  "name": "HDL Studio: counter_tb",
  "top": "counter_tb",                     // entity to simulate
  "files": ["src/**/*.vhdl", "tb/*.vhdl"], // paths or globs; GHDL orders the analysis
  "std": "08",
  "ghdlArgs": ["-fsynopsys"],              // analysis / elaboration options
  "simArgs": ["--assert-level=error"],     // run-time options
  "stopTime": "1 ms",
  "stopOnEntry": true
}

Add --wave=run.ghw or --vcd=run.vcd to simArgs to also record a waveform file while debugging.

Building with CMake#

With cmake-language-vhdl, a testbench is an ordinary add_executable(). Let CMake build it and point program at the result instead of listing files. The Debug build type passes -g, which source breakpoints need:

jsonc
{ "type": "ghdl", "request": "launch", "name": "dds_tb (CMake)",
  "top": "dds_tb", "program": "${workspaceFolder}/build/dds_tb",
  "preLaunchTask": "cmake: build" }

examples/cmake is a complete project: CMakeLists.txt, presets, the tasks and launch configurations, and a waves target that leaves build/dds_tb.ghw and build/dds_tb.vcd to open in the viewer.

Settings#

Setting	Default
`hdl.debugger.stepTime`	empty	what Step Time advances, e.g. `10 ns`; empty means the next time with activity
`hdl.debugger.stopAtEntry`	`true`	stop at the start of a launch without a workspace file
`hdl.debugger.record`	`true`	keep a `.ghw` recording of each launch without a workspace file
`hdl.diagnostics.onSave`	`true`	check a VHDL file with GHDL when it is saved

All settings are listed in the settings reference.