Skip to content

ghdl/ghdl-yosys-plugin

Repository files navigation

'push' workflow Status

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

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

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


Build as a module (shared library)

  • 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

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

Docker

Docker image ghdl/synth:beta includes yosys and the ghdl 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 \
  ghdl/synth:beta \
  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 ghdl/synth:beta     yosys -m ghdl -p 'ghdl leds.vhdl rotate4.vhdl -e leds; synth_ice40 -json leds.json'
$DOCKER_CMD ghdl/synth:nextpnr  nextpnr-ice40 --hx1k --json leds.json --pcf leds.pcf --asc leds.asc
$DOCKER_CMD ghdl/synth:icestorm icepack leds.asc leds.bin

iceprog leds.bin

NOTE: on GNU/Linux, it should be possible to use iceprog through ghdl/synth:icestorm. On Windows and macOS, accessing USB/COM ports of the host from containers seems not to be supported yet. Therefore, iceprog is required to be available on the host.

Build as part of yosys (not recommended)

  • Get and build ghdl as in the previous section.

  • Get yosys sources.

  • Get ghdl-yosys-plugin and:

    • Patch yosys sources using yosys.diff.
    • Copy src/* to yosys/frontends/ghdl.
    • Configure yosys by adding (to) Makefile.conf:
ENABLE_GHDL := 1
GHDL_DIR := <ghdl install dir>
  • Build and install yosys.