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
A ruckus project with system_ghdl.mk and a ghdl/load_source_code.tcl source enumeration file
yosys with GHDL plugin installed — only required if using make export_verilog (optional 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 enumerated by ghdl/load_source_code.tcl.

Steps

GHDL uses a staged pipeline. Each step corresponds to a distinct GHDL command. Run targets in the order shown below.

Create output directories:
```
make dir
```
Creates $(OUT_DIR) and $(IMAGES_DIR) if they do not exist.
Load source file list:
```
make load_source_code
```
Runs ghdl/load_source_code.tcl to enumerate the VHDL source files for the project.
Analyze VHDL sources (ghdl -a):
```
make analysis
```
Parses and type-checks all VHDL source files. 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
```
Writes the elaboration order to $(IMAGES_DIR)/$(PROJECT).elab_order for reference.
Build (elaborate) the design (ghdl -m):
```
make build
```
Elaborates the top-level design unit into a simulation executable.
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 declares all prior targets as dependencies, it will execute the full chain automatically from a clean state.

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. 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.