How to Simulate VHDL with GHDL

Goal: Analyze, elaborate, and simulate a VHDL design using the open-source GHDL simulator.

Note

GHDL requires no Vivado or Xilinx license. It is an independent open-source VHDL simulator and works on any Linux system where ghdl is installed.

Prerequisites

Before running the simulation flow, ensure the following are in place:

ghdl binary installed and on PATH (version 2.0+ recommended)
gtkwave installed for waveform viewing
vhdeps installed (used by make analysis to order the sources)
A project ruckus.tcl tree that loads the design’s VHDL sources
yosys with the GHDL plugin installed (only required for the optional make export_verilog step)
Project Makefile includes system_ghdl.mk

Makefile Setup

Add the following to your project Makefile:

include $(TOP_DIR)/submodules/ruckus/system_ghdl.mk

No PDK variables are required. GHDL uses only the VHDL sources loaded by the project’s ruckus.tcl tree.

Steps

GHDL uses a staged pipeline. Steps 3 through 7 each correspond to a distinct GHDL command. Run targets in the order shown below.

Create output directories:
```
make dir
```
Removes any existing $(OUT_DIR) (dir depends on clean), then creates $(OUT_DIR) and $(IMAGES_DIR).
Load source file list:
```
make load_source_code
```
Runs ruckus’s ghdl/load_source_code.tcl, which generates the build info package and loads the project’s ruckus.tcl tree to enumerate the VHDL source files.
Analyze VHDL sources (ghdl -a):
```
make analysis
```
Parses and type-checks all VHDL source files in dependency order (computed with vhdeps). Errors here indicate syntax or type-checking problems in your HDL.
Import design units (ghdl -i):
```
make import
```
Imports design units into the working library.
Determine elaboration order (ghdl --elab-order):
```
make elab_order
```
Prints the elaboration order of the top-level design unit.
Build (elaborate) the design (ghdl -m):
```
make build
```
Elaborates the top-level design unit into a simulation executable and writes the source analysis order to $(IMAGES_DIR)/$(PROJECT).elab_order for reference.
Run simulation (ghdl -r):
```
make tb
```
Runs the simulation and produces a waveform file at $(OUT_DIR)/$(PROJECT).ghw. Simulation stops at GHDL_STOP_TIME (default: 10ns).
View waveform in GTKWave:
```
make gtkwave
```
Opens GTKWave with the .ghw waveform file produced by make tb.

Note

Steps 1 through 7 can be run individually in sequence, or you can run make tb directly. Because make tb depends on every prior target except analysis, it executes the full chain automatically from a clean state. make analysis is a standalone check and is not part of the make tb chain.

Optional: Export Synthesizable Verilog

If you have yosys with the GHDL plugin installed, you can export a synthesizable Verilog netlist from the VHDL design:

make export_verilog

This runs yosys -m ghdl to synthesize the VHDL design into Verilog, written to $(IMAGES_DIR)/$(PROJECT).v. This step is independent of the simulation flow and does not require GTKWave.

Key Variables

Variable	Default	Description
`GHDL_CMD`	`ghdl`	GHDL executable path or name. Override if `ghdl` is not on PATH or you need a specific version.
`GHDL_TOP_LIB`	`work`	Top-level VHDL library name. Must match the `library` clause in your VHDL top-level entity.
`GHDL_STOP_TIME`	`10ns`	Simulation stop time. Increase this for testbenches that require longer run times.
`GHDLFLAGS`	`--std=08 --ieee=synopsys -frelaxed-rules ...`	Full set of flags passed to all GHDL commands. The complete default is: `--workdir=$(OUT_DIR) --std=08 --ieee=synopsys -frelaxed-rules -fexplicit -Wno-elaboration -Wno-hide -Wno-specs -Wno-shared`. Override in your project Makefile (before the include) to change the VHDL standard or suppress different warnings.
`GIT_BYPASS`	`1`	Git dirty-state check bypassed by default.

Note

To override GHDLFLAGS, set it in your project Makefile before the include line:

export GHDLFLAGS = --workdir=$(OUT_DIR) --std=93 --ieee=standard

include $(TOP_DIR)/submodules/ruckus/system_ghdl.mk

Troubleshooting

“ghdl: command not found”

Install GHDL on your system:

# Debian / Ubuntu
sudo apt install ghdl

For other distributions or to build from source, see the GHDL repository at https://github.com/ghdl/ghdl.

“bound check failure” or simulation stops immediately

Increase GHDL_STOP_TIME. The default (10ns) is intentionally short and will be too brief for most testbenches. Set a longer stop time in your project Makefile:

export GHDL_STOP_TIME = 1us

Analysis errors: “no library” or unresolved references

Verify that GHDL_TOP_LIB matches the library name used in your VHDL library and use clauses. If your design uses library work;, the default value of work is correct. Mismatches cause GHDL to fail to find design units during elaboration.

GTKWave shows an empty or unreadable waveform

Ensure make tb completed successfully and the .ghw file exists in $(OUT_DIR)/ before running make gtkwave. An incomplete simulation (stopped by a runtime assertion) may produce a truncated waveform file.