ghdl-yosys-plugin: VHDL synthesis (based on GHDL and Yosys)

This is experimental and work in progress! See ghdl.github.io/ghdl: Using/Synthesis.

• Build as a module
• Build as part of Yosys
• Pre-built packages
• Usage
• Containers

TODO: Create table with features of VHDL that are supported, WIP and pending.

Build as a module (shared library)

On Windows, Yosys does not support loading modules dynamically. Therefore, this build approach is not possible. See Build as part of Yosys below.

• Get and install Yosys.
• Get sources, build and install GHDL. Ensure that GHDL is configured with synthesis features (enabled by default since v0.37). See Building GHDL.

NOTE: GHDL must be built with at least version of 8 GNAT (gnat-8).

HINT: The default build prefix is /usr/local. Sudo permission might be required to install tools there.

• Get and build ghdl-yosys-plugin: make.

HINT: If ghdl is not available in the PATH, set GHDL explicitly, e.g.: make GHDL=/my/path/to/ghdl.

The output is a shared library (ghdl.so on GNU/Linux), which can be used directly: yosys -m ghdl.so.

To install the module, the library must be copied to YOSYS_PREFIX/share/yosys/plugins/ghdl.so, where YOSYS_PREFIX is the installation path of yosys. This can be achieved through a make target: make install.

Alternatively, the shared library can be copied/installed along with GHDL:

cp ghdl.so "$GHDL_PREFIX/lib/ghdl_yosys.so"

yosys-config --exec mkdir -p --datdir/plugins
yosys-config --exec ln -s "$GHDL_PREFIX/lib/ghdl_yosys.so" --datdir/plugins/ghdl.so

Build as part of yosys (not recommended)

• Get and build GHDL as in the previous section.

• Get Yosys sources.

• Get ghdl-yosys-plugin and:

  • Copy src/* to yosys/frontends/ghdl.
  • Configure Yosys by adding (to) Makefile.conf:

ENABLE_GHDL := 1
GHDL_PREFIX := <ghdl install dir>

• Build and install Yosys.

Pre-built packages

Some projects provide pre-built packages including GHDL, Yosys and ghdl-yosys-plugin. Unless you have specific requirements (targeting a different arch, OS, build options...), we suggest using one of the following solutions before building ghdl-yosys-plugin from sources.

• open-tool-forge/fpga-toolchain provides tarballs for GNU/Linux, Windows or macOS, including statically built EDA tools. Packages are available for x86 or amd64.

• On Windows, there is a package group in MSYS2 repositories named mingw-w64-x86_64-eda|mingw-w64-i686-eda. See hdl/MINGW-packages.

Usage

Example for IceStick, using GHDL, Yosys, nextpnr and icestorm:

cd examples/icestick/leds/

# Analyse VHDL sources
ghdl -a leds.vhdl
ghdl -a spin1.vhdl

# Synthesize the design.
# NOTE: if GHDL is built as a module, set MODULE to '-m ghdl' or '-m path/to/ghdl.so',
#       otherwise, unset it.
yosys $MODULE -p 'ghdl leds; synth_ice40 -json leds.json'

# P&R
nextpnr-ice40 --package hx1k --pcf leds.pcf --asc leds.asc --json leds.json

# Generate bitstream
icepack leds.asc leds.bin

# Program FPGA
iceprog leds.bin

Alternatively, it is possible to analyze, elaborate and synthesize VHDL sources at once, instead of calling GHDL and Yosys in two steps. In this example:

yosys $MODULE -p 'ghdl leds.vhdl spin1.vhdl -e leds; synth_ice40 -json leds.json'

Containers

Container (aka Docker/Podman) image hdlc/ghdl:yosys includes GHDL, Yosys and the ghdl-yosys-plugin module (shared library). These can be used to synthesize designs straightaway. For example:

docker run --rm -t \
  -v $(pwd)/examples/icestick/leds:/src \
  -w /src \
  hdlc/ghdl:yosys \
  yosys -m ghdl -p 'ghdl leds.vhdl blink.vhdl -e leds; synth_ice40 -json leds.json'

In a system with docker installed, the image is automatically downloaded the first time invoked.

Furthermore, the snippet above can be extended in order to P&R the design with nextpnr and generate a bitstream with icestorm tools:

cd examples/icestick/leds/

DOCKER_CMD="$(command -v winpty) docker run --rm -it -v /$(pwd)://wrk -w //wrk"

$DOCKER_CMD hdlc/ghdl:yosys    yosys -m ghdl -p 'ghdl leds.vhdl rotate4.vhdl -e leds; synth_ice40 -json leds.json'
$DOCKER_CMD hdlc/nextpnr:ice40 nextpnr-ice40 --hx1k --json leds.json --pcf leds.pcf --asc leds.asc
$DOCKER_CMD hdlc/icestorm      icepack leds.asc leds.bin

iceprog leds.bin

See hdl/containers for further info about containers including other EDA tools.

NOTE: on GNU/Linux, it should be possible to use board programming tools through hdlc/icestorm. On Windows and macOS, accessing USB/COM ports of the host from containers is challenging. Therefore, board programming tools need to be available on the host. Windows users can find several board programming tools available as MSYS2 packages. See mingw-w64-x86_64-eda|mingw-w64-i686-eda and hdl/MINGW-packages.