Required Software¶

Fomu requires specialized software.

Note

If you’re taking this workshop as a class, the toolchains are provided on the USB disk.

Static builds of this software are provided for GNU/Linux, macOS, and Windows via Fomu Toolchain.

Debian packages are also available for Raspberry Pi.

Moreover, some examples can be executed using Containers.

Fomu Toolchain¶

To install the software, extract it somewhere on your computer, then open up a terminal window and add that directory to your PATH:

export PATH=[path-to-toolchain]/bin:$PATH

If you use PowerShell as your terminal;

$ENV:PATH = "[path-to-toolchain]\bin;" + $ENV:PATH

If you use cmd.exe as your terminal;

 PATH=[path-to-toolchain]\bin;%PATH%

Examples in VHDL on Fomu and Mixed HDL on Fomu use ghdl-yosys-plugin, which looks for standard libraries in the path used when GHDL was configured/built. Therefore, when the toolchain is extracted to an arbitrary location, GHDL_PREFIX needs to be set:

export GHDL_PREFIX=[path-to-toolchain]/lib/ghdl

If you use PowerShell as your terminal;

$ENV:GHDL_PREFIX = "[path-to-toolchain]\lib\ghdl"

If you use cmd.exe as your terminal;

 GHDL_PREFIX=[path-to-toolchain]\lib\ghdl

To confirm installation, run the yosys command and confirm you get the following output;

$ yosys

 /----------------------------------------------------------------------------\
 |                                                                            |
 |  yosys -- Yosys Open SYnthesis Suite                                       |
 |                                                                            |
 |  Copyright (C) 2012 - 2018  Clifford Wolf <clifford@clifford.at>           |
 |                                                                            |
 |  Permission to use, copy, modify, and/or distribute this software for any  |
 |  purpose with or without fee is hereby granted, provided that the above    |
 |  copyright notice and this permission notice appear in all copies.         |
 |                                                                            |
 |  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES  |
 |  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF          |
 |  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR   |
 |  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES    |
 |  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN     |
 |  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF   |
 |  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.            |
 |                                                                            |
 \----------------------------------------------------------------------------/

 Yosys 78b30bbb1102047585d1a2eac89b1c7f5ca7344e (git sha1 41d9173, gcc 5.5.0-12ubuntu1~14.04 -fPIC -Os)

yosys>

Type exit to quit yosys.

Note

See the README of Fomu Toolchain for a complete list of the tools included in the toolchain.

Containers¶

There are several projects which provide ready to use container images including open source EDA tools. One of those is hdl/containers. As explained in hdl.github.io/containers: Usage, there are two main strategies for running EDA tools through containers:

All-in-one: a single container is used, which includes all the required tools and dependencies. make and all the tools are executed inside that single container.
Fine-grained: make is executed on the host. For each tool/step, an specific container is used.

Both strategies are supported by the examples in subdir hdl of this repository. Users willing to run those examples with containers need to take care about the following environment variables:

GHDL_PLUGIN_MODULE: while ghdl-yosys-plugin is built into Yosys in the fomu-toolchain, it is provided as a module in most containers. Typically, GHDL_PLUGIN_MODULE=ghdl is required. Some specific containers might require GHDL_PLUGIN_MODULE=path/to/ghdl-plugin-name.so.
CONTAINER_ENGINE: in order to enable the fine-grained approach, CONTAINER_ENGINE needs to contain the CLI tool name of a container engine, such as docker or podman. This variable needs to be unset for the all-in-one approach. In that case, the build is agnostic to the fact that everything is being done inside a container.

Note

By default, container images defined in hdl/container.mk are used when CONTAINER_ENGINE is set. It’s up to the users to customise that file in order to use different container images, or for executing some of the tools locally.

Tip

Find both approaches (and environment variables) used in the CI workflow (.github/workflows/test.yml) of this repository.