From 6856919e98112c1b8be72d76a049709c5d4fa916 Mon Sep 17 00:00:00 2001 From: eine Date: Tue, 29 Dec 2020 06:58:49 +0100 Subject: readme: update guidelines, update container image names, add ref to mingw-w64-*-eda package groups --- README.md | 82 +++++++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 34 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 5761bb0..07b71a5 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,15 @@ 'push' workflow Status

-# ghdl-yosys-plugin: VHDL synthesis (based on [ghdl](https://github.com/ghdl/ghdl) and [yosys](https://github.com/YosysHQ/yosys)) +# ghdl-yosys-plugin: VHDL synthesis (based on [GHDL](https://github.com/ghdl/ghdl) and [Yosys](https://github.com/YosysHQ/yosys)) -**This is experimental and work in progress!** See [ghdl.rtfd.io: Using/Synthesis](http://ghdl.readthedocs.io/en/latest/using/Synthesis.html). +**This is experimental and work in progress!** See [ghdl.github.io/ghdl: Using/Synthesis](http://ghdl.github.io/ghdl/using/Synthesis.html). -- [Build as a module (shared library)](#build-as-a-module-shared-library) +- [Build as a module](#build-as-a-module-shared-library) +- [Build as part of Yosys](#build-as-part-of-yosys-not-recommended) +- [Pre-built packages](#pre-built-packages) - [Usage](#Usage) -- [Docker](#Docker) +- [Containers](#Containers) > TODO: Create table with features of VHDL that are supported, WIP and pending. @@ -22,8 +24,10 @@ ## Build as a module (shared library) -- Get and install [yosys](https://github.com/YosysHQ/yosys). -- Get sources, build and install [ghdl](https://github.com/ghdl/ghdl). Ensure that GHDL is configured with synthesis features (enabled by default since v0.37). See [Building GHDL](https://github.com/ghdl/ghdl#building-ghdl). +> On Windows, Yosys does not support loading modules dynamically. Therefore, this build approach is not possible. See [*Build as part of Yosys*](#build-as-part-of-yosys-not-recommended) below. + +- Get and install [Yosys](https://github.com/YosysHQ/yosys). +- Get sources, build and install [GHDL](https://github.com/ghdl/ghdl). Ensure that GHDL is configured with synthesis features (enabled by default since v0.37). See [Building GHDL](https://github.com/ghdl/ghdl#building-ghdl). > NOTE: GHDL must be built with at least version of 8 GNAT (`gnat-8`). @@ -37,7 +41,7 @@ The output is a shared library (`ghdl.so` on GNU/Linux), which can be used direc 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: +Alternatively, the shared library can be copied/installed along with GHDL: ```sh cp ghdl.so "$GHDL_PREFIX/lib/ghdl_yosys.so" @@ -46,9 +50,34 @@ 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](https://github.com/YosysHQ/yosys) sources. + +- Get ghdl-yosys-plugin and: + - Copy `src/*` to `yosys/frontends/ghdl`. + - Configure Yosys by adding (to) `Makefile.conf`: + +```makefile +ENABLE_GHDL := 1 +GHDL_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](https://github.com/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](https://www.msys2.org/) repositories named [mingw-w64-x86_64-eda](https://packages.msys2.org/group/mingw-w64-x86_64-eda)|[mingw-w64-i686-eda](https://packages.msys2.org/group/mingw-w64-i686-eda). See [hdl/MINGW-packages](https://github.com/hdl/MINGW-packages). + ## Usage -Example for icestick, using ghdl, yosys, nextpnr and icestorm: +Example for IceStick, using GHDL, Yosys, nextpnr and icestorm: ```sh cd examples/icestick/leds/ @@ -58,7 +87,8 @@ 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' +# 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 @@ -71,21 +101,21 @@ icepack leds.asc leds.bin 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: +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 +## Containers -Docker image [`ghdl/synth:beta`](https://hub.docker.com/r/ghdl/synth/tags) includes yosys and the ghdl module (shared library). These can be used to synthesize designs straightaway. For example: +Container (aka Docker/Podman) image [`hdlc/ghdl:yosys`](https://hub.docker.com/r/hdlc/ghdl/tags) includes GHDL, Yosys and the ghdl-yosys-plugin module (shared library). These can be used to synthesize designs straightaway. For example: ```sh docker run --rm -t \ -v $(pwd)/examples/icestick/leds:/src \ -w /src \ - ghdl/synth:beta \ + hdlc/ghdl:yosys \ yosys -m ghdl -p 'ghdl leds.vhdl blink.vhdl -e leds; synth_ice40 -json leds.json' ``` @@ -98,29 +128,13 @@ 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 +$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 ``` -> 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](https://github.com/YosysHQ/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`: - -```makefile -ENABLE_GHDL := 1 -GHDL_DIR := -``` +See [hdl/containers](https://github.com/hdl/containers) for further info about containers including other EDA tools. -- Build and install yosys. +> 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](https://www.msys2.org/) packages. See [mingw-w64-x86_64-eda](https://packages.msys2.org/group/mingw-w64-x86_64-eda)|[mingw-w64-i686-eda](https://packages.msys2.org/group/mingw-w64-i686-eda) and [hdl/MINGW-packages](https://github.com/hdl/MINGW-packages). -- cgit v1.2.3