GHDL is “a VHDL analyzer, compiler, simulator and (experimental) synthesizer that can process (nearly) any VHDL design.”


Table of Contents


Installing

You can find GHDL’s comprehensive documentation on readthedocs.

Ubuntu

  1. sudo apt install ghdl
  2. Open a terminal and try ghdl -v to check that your installation was successful

Windows

  1. Go to the overview of pre-built packages and download the zip for Windows
  2. Extract the files in the zip
  3. Add the bin folder to your PATH
  4. Open cmd, powershell, or msys/git bash and run ghdl -v to check that your installation was successful

The remainder of this post will assume you are running on Ubuntu or a similar OS, adjust accordingly if you are running something considerably different, like Windows.

Building and running testbenches

For a simple, one file design and a single testbench the following script will build and run the simulation:

build_simple.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

#!/bin/env bash
# file: build_simple.sh

if [[ $# -lt 1 || $# -gt 1 ]]; then
  echo "Usage: build.sh design_name"
  exit 1
fi

design=$*
testbench=${design}_tb

set -ex

ghdl -i $design.vhd $testbench.vhd
ghdl -m $testbench
ghdl -r $testbench
Listing 1: Script for building simple designs with a testbench

Remember to set executable permissions chmod +x build_simple.sh and then run the script with for example:

./build_simple.sh half_adder

to run it on the same half adder design from nandland which I used in the VHDL Style Guide post.

Due to the set -ex statement, which shows the commands as they are executed, the output of the script is:

+ ghdl -i half_adder.vhd half_adder_tb.vhd
+ ghdl -m half_adder_tb
+ ghdl -r half_adder_tb

You could absolutely skip the script entirely and just run these three commands directly in the terminal.

Building libraries

In case you need a VHDL resource library, which for PlTbUtils could look like this in your VHDL code:

library pltbutils;
  use pltbutils.txt_util.all;

you can build that library using the following script:

buildlib.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

#!/bin/env bash
# file: buildlib.sh

workdir="_work"

if [[ $# -lt 2 ]]; then
  echo "Usage: build.sh [-o _work] lib_name lib_sources"
  exit 1
else
  while [[ "$#" -gt 0 ]]; do
    case $1 in
      -o) workdir="$2"; shift;;
      *) lib_name="$1" && shift 1 && lib_src="$@" && break;;
    esac
    shift
  done
fi

# Make sure workdir exists
mkdir -p $workdir

set -ex

ghdl -i --workdir=$workdir -P$workdir --work=$lib_name $lib_src
Listing 2: Script for building libraries

Remember to set executable permissions chmod +x buildlib.sh and then to build the library from source (which I have downloaded to ~/Dev/hdl/pltbutils) you can run:

./buildlib.sh pltbutils ~/Dev/hdl/pltbutils/trunk/src/vhdl/*.vhd

This creates a pltbutils-obj93.cf in _work which GHDL can use as a resource library.

Using libraries with testbenches

To direct GHDL to include the libraries placed in a certain directory we need to point to it with the -P option.

build.sh
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

#!/bin/env bash
# file: build.sh

if [[ $# -lt 1 || $# -gt 1 ]]; then
  echo "Usage: build.sh design_name"
  exit 1
fi

design=$*
testbench=${design}_tb
workdir=_work
options="-P$workdir --workdir=$workdir"

# Make sure workdir exists
mkdir -p $workdir

set -ex

ghdl -i $options $design.vhd $testbench.vhd
ghdl -m $options $testbench
ghdl -r $options $testbench
Listing 3: Script for building simple designs that use libraries

Now, running ./build.sh half_adder_pltb gives the output:

+ ghdl -i -P_work --workdir=_work half_adder_pltb.vhd half_adder_pltb_tb.vhd
+ ghdl -m -P_work --workdir=_work half_adder_pltb_tb
+ ghdl -r -P_work --workdir=_work half_adder_pltb_tb

--- START OF SIMULATION ---
Testcase: Half Adder PlTbUtils Testbench
0 fs

Test 1: Check defaults on output ports (0 fs)
Done with test 1: Check defaults on output ports (0 fs)

Test 2: Check logic (0 fs)
Done with test 2: Check logic (50000000 fs)

--- END OF SIMULATION ---
Note: the results presented below are based on the PlTbUtil's check() procedure calls.
      The design may contain more errors, for which there are no check() calls.
         50 ns
          2 Tests
          0 Skipped tests
         10 Checks
          0 Errors
*** SUCCESS ***

Which shows the three GHDL commands prefixed with a + and then the output printed to the transcript/stdout by PlTbUtils and the testbench.

Vendor Primitives Libraries

If you make use of vendor primitives in your designs you’ll need to build a library from the VHDL source files provided by the vendor.

For example, the source files for Xilinx’s unisim library can be found in the following directory of my installation of Vivado 2020.2: Xilinx/Vivado/2020.2/data/vhdl/src/unisims

GHDL provides compilation scripts for these libraries.

When building unisim I had a problem with using the VHDL-93 standard so I built it with the ‘08 standard by running:

/usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --vhdl2008 --unisim --source ./src

and got the output

Loading environment...
Not all Xilinx primitives are VHDL-2008 compatible! Setting CONTINUE_ON_ERROR to TRUE.
[WARNING] Vendor directory '/home/sturlalange/Dev/hdl/vivado_vhdl/xilinx-vivado' already exists.
Analyzing library 'unisim'...
Creating VHDL Library 'unisim'...
Analyzing files into library 'unisim'...
  WARNING: /home/sturlalange/Dev/hdl/vivado_vhdl/src/unisims/primitive/SYSMONE4.vhd:1536:44:warning: prefix of array attribute must be an object name [-Wattribute]
  Warnings detected by filtering script.
--------------------------------------------------------------------------------
Compiling Xilinx Vivado libraries [SUCCESSFUL]

Now the library has been created in the directory xilinx-vivado/, it is called unisim-obj08.cf

We can check the contents by issuing ghdl -d --std=08 -Pxilinx-vivado unisim which outputs

# Library unisim
# Directory: xilinx-vivado/
entity xorcy_d
architecture xorcy_d_v of xorcy_d
entity xor4
architecture xor4_v of xor4
entity xor2
architecture xor2_v of xor2
entity xnor4
architecture xnor4_v of xnor4
...

Conclusion

GHDL is a great alternative to proprietary simulators such as xsim and modelsim, it is actively developed and is adopting new versions of the VHDL standard, currently VHDL-2008 is partially implemented according to the documentation.


Comments? You are welcome to start a discussion on Github.