This directory contains the sources of GHDL, the open-source analyzer, compiler, simulator and (experimental) synthesizer for VHDL, a Hardware Description Language (HDL). GHDL is not an interpreter: it allows you to analyse and elaborate sources to generate machine code from your design. Native program execution is the only way for high speed simulation.

Main features

Full support for the 1987, 1993, 2002 versions of the IEEE 1076 VHDL standard, and partial for the latest 2008 revision.

Partial support of PSL.

By using a code generator (LLVM, GCC or, x86_64/i386 only, a built-in one), it is much faster than any interpreted simulator. It can handle very large designs, such as leon3/grlib.

GHDL runs on GNU/Linux, Windows and macOS; on x86, x86_64, armv6/armv7/aarch32 and aarch64. You can freely download a binary distribution for your OS, use GHDL Docker images, or try to build it on your own machine (see 'Getting GHDL' below).

Can write waveforms to a GHW, VCD or FST file. Combined with a GUI-based waveform viewer and a good text editor, GHDL is a very powerful tool for writing, testing and simulating your code.

Supported third party projects: cocotb (through the VPI interface), OSVVM, UVVM, VUnit, ...

GHDL is free software:

• 
• available at ghdl.github.io/ghdl.
• Some of the runtime libraries, are under different terms; see the individual source files for details.

Getting GHDL

• Pre-built packages:
  • Approximately once a year, tagged binary distributions are made available through the releases tab.
  • After each succesful CI run, nightly tarballs/zipfiles for Ubuntu Focal and Windows (MSYS2) are updated.
• For using GHDL in CI, setup-ghdl-ci is provided. It is a GitHub Action (see github.com/features/actions) to setup GHDL in just 3 lines.
• You may use GHDL Docker images in case your didn't find a suitable release.
• Build GHDL yourself (see below)!

Building GHDL

GHDL currently supports three different back-ends (code generators). Each has its pros and cons. You can find specific instructions for each of the options in 'Building'.

TL;DR

In order to follow the traditional way to configure and make, you need an Ada compiler. Most GNU/Linux package managers provide a package named gcc-ada or gcc-gnat.

Alternatively, GNAT GPL can be downloaded anonymously from libre.adacore.com (later than 2017 is suggested; for x86, 32 or 64 bits). Then, untar and run the doinstall script.

Depending on the OS and distribution you are using, you will also need to install some toolchain dependencies, such as zlib. See 'Building' for specific package names.

To use mcode backend (easiest to build), in the GHDL base directory, configure and build:

$ ./configure --prefix=/usr/local
$ make

At that place, you can already use the ghdl_mcode built in the directory. You can also install GHDL:

$ make install

That's all!

The executable is installed as 'ghdl' in /usr/local. To install it to a different path, change the --prefix in the call to configure. For example, on Windows, you may want to set it to --prefix=/c/Program Files (x86)/GHDL.

Project structure

Regular users

• The 'regular' tool allows analysis, compilation, simulation and (very experimental) synthesis of VHDL 1993 netlists. It is written in Ada and C, and three different backends are supported, which are sometimes named ghdl_mcode, ghdl_gcc and ghdl_llvm. This is the entrypoint for most users.

• ghdl-ls implements Language Server Protocol (LSP) in Python. VHDL analysis features provided by GHDL are accessed through libghdl-py. This can be integrated in text editors or IDES, such as, Vim, Emacs, Atom or Visual Studio Code.

• vscode-client is an extension for Visual Studio Code (VSC) to provide language support for VHDL by interfacing ghdl-ls.

Advanced users

• libghdl is a shared library that includes a subset of the regular features plus some features to be used by extension tools (i.e. libghdl-py). This is built along with the regular GHDL and it supports both non-synthesisable and synthesisable code. Nonetheless, this is not for users, but for tools built on top of the core. When configured along with --enable-synth, this shared library includes [experimental] synthesis features too.

• libghdl-py is a Python interface to libghdl. Currently, it is only used by ghdl-ls; however, it can be useful for advanced users which are willing to build Python utilities based on GHDL.

• [experimental] ghdl-yosys-plugin is the integration of GHDL as a frontend plugin module for Yosys Open SYnthesis Suite, which uses the libghdl library (built with --enable-synth).

• [deprecated] ghdl_simul, which supports interpreted simulation, is available for historical reasons and for development/debugging only. It is very slow compared to the 'regular' compiled simulation and not all the features are supported.