To get started with learning FPGA easily, it’s best to begin with Free and Open Source Software (FOSS). The first tool you’ll need is a Synthesizer. Although I will write a full article about it in the future, for now what you need to know is that a Synthesizer will convert your Verilog or VHDL design into a Netlist.

The Synthesizer we’ll be using is Yosys. I was inspired by the excellent article “Building ice40 fpga toolchain” written by Will Green on his blog projectf. He uses the ICEBreaker board, while I use an Alchitry CU board. Both of these boards have an ICE40 FPGA and have a free and open source workflow from Verilog to Bitstream. If you want to install this toolchain on your system without using Docker, follow his article. I have not much to add. But if you are interested in using docker to install it follow me.

This article is a prerequisite for the bigger article : From HDL to FPGA Bitstream with Open Source toolchain

I. What is docker ? What are the benefits ?

Docker is an open-source platform for automating the deployment, scaling, and management of applications as containers. Containers are lightweight, stand-alone, and executable software packages that include everything needed to run a piece of software, including the code, a runtime, system tools, libraries, settings, and more. By using Docker, developers can package their applications and dependencies into containers that can be run consistently on any infrastructure, including laptops, servers, and cloud environments. This makes it easier to develop, test, and deploy applications, especially in a distributed and dynamic environment.

The benefits of using Docker in your FPGA workflow are:

1. Fixed Workspace and Tool Versions: Docker images are immutable, which means that they contain a fixed version of the Linux operating system and tools. This makes it possible to regenerate your bitstream even years later with ease, if you store images of all your project.
2. No More “It Works on My Computer”: With Docker, everyone on your team will be using the same workspace, reducing the likelihood of “it works on my computer” scenarios.
3. Multiple Images with Different Tool Versions: You can run multiple images with different versions of the same tools on the same laptop or server without any conflicts. This is useful when working on multiple projects that require different versions of the same tool.
4. Easily install software not available on your linux distro/OS. Since your image can be based on a Ubuntu image.
5. As always, I am sure some of you know many more advantages, do not hesitate to share them in the comment section.

II. Installing Yosys in docker

To install docker follow the instruction here.

a. The dockerfile

Here is a standalone docker file to install Yosys inside a docker container.

FROM ubuntu:20.04

ARG DEBIAN_FRONTEND=noninteractive
ENV TZ=Europe/Paris

RUN apt-get update; apt-get -y install curl

RUN apt-get install -y build-essential git clang bison flex \
	libreadline-dev gawk tcl-dev libffi-dev git \
	graphviz xdot pkg-config python3 libboost-system-dev \
	libboost-python-dev libboost-filesystem-dev zlib1g-dev

RUN git clone https://github.com/YosysHQ/yosys.git yosys

RUN cd yosys; make -j$(nproc); make install

You can get it on my github here.

The dockerfile above is a generic and a standalone one. For this tutorial please add the two line at the end of the file:

WORKDIR "/project/"
ENTRYPOINT [ "/bin/bash", "-c", "yosys src/synth/synth.ys > build/logs/syn_log.txt" ]

Alternatively you can build the generic Yosys dockerfile to create an image (yosys:latest) and inherit from it in a new dockerfile:

FROM yosys:latest

WORKDIR "/project/"
ENTRYPOINT [ "/bin/bash", "-c", "yosys src/synth/synth.ys > build/logs/syn_log.txt" ]

b. Code Explaination

The first line “FROM ubuntu:20.04” tells docker to create an image from another one. Here ubuntu 20.04. If docker does not find it on your system it will pull it from docker hub.

The following lines with `ARG` and `ENV` serve to avoid interruption during the build process. During the build, you cannot interact with the Docker terminal, and if a dependency such as `tzdata` (timezone data) requires input, the build will become stuck. To prevent this, the `ARG` and `ENV` lines ensure that the build continues without interruption.

The two first RUN command setup every dependencies to install Yosys.

The two last RUN command clone the Yosys repository and build Yosys.

The WORKDIR defines the directory where any script will be execute by default.

By default it is the root directory “/” if you have to work in another folder you will have to “cd <path/to/working/dir>” everytime. WORKDIR solve this.

The ENTRYPOINT is the default command that will be launch if no other is given to the docker when you start your container. Here the container will launch bash “/bin/bash” with the option “-c” meaning “with the following command” :

yosys src/synth/synth.ys > build/logs/syn_log.txt

This command ask yosys to launch the yosys script synth.ys.

” > build/logs/syn_log.txt” redirect the log into a file to save them.

“But where does that synth.ys come from ?” you might ask. This file isn’t included in our image, but don’t worry. Since it’s a project-specific file, and not a tool(yosys) specific file, so it will be passed into the container using a Docker volume at a later stage.(cf part 3)

c. Building the image

To create the image, simply navigate to the Dockerfile folder and run the following command, including the desired tag name and version:

docker build -t <tag_name>:<version> .

For this tutorial you can just have a “yosys” as tag name without version (it will assigned “latest” version by default):

docker build -t yosys .

III. Project Workspace

Here is the directory tree of the project to test yosys.

Makefile
src:
    synth:
        - synth.ys
    hdl:
        - top.v
build:
    logs:
    artifacts:
        syn:

The synth.ys is the yosys script for yosys to know what to do.

read -sv src/hdl/top.v
hierarchy -top top
proc; opt; techmap; opt
synth_ice40 -top top -json build/artifacts/syn/synth.json

The first line read the file. The second points the top to Yosys. The third do some kind of optimization. And the last one syntheses the design and save the netlist as a json file.

The design is a dim led. The LED is turn on half the time at the clock frequency giving it a dim brightness. You can replace it by whatever you want, as long a the file is called “top.v” and the top module “top” to be compatible with the synth.ys script.

// top.v
module top(
    input clock,
    input resetn,
    output reg LED
);
reg tmp = 1'b0;
always @(posedge clock)
begin
if(!resetn)
    tmp <= 1'b0;
else 
    tmp <= ~tmp;
    LED <= tmp;
end
endmodule

The tiny Makefile:

synthesis: src/hdl/top.v
	docker run -v $(PWD):/project/ yosys

Instead of using a makefile you could simply run the following command in you terminal:

docker run -v "$PWD":/project/ yosys

Command description:

• docker run : mean “please docker run a container”
• -v $(PWD):/project/ : The -v stands for volume. A Docker volume is a way to persist data in a container beyond the life of the container. Volumes are stored outside of the container’s filesystem, allowing data to persist even if the container is deleted or recreated. This makes volumes useful for storing important data, such as configuration files, database files, logs ,or here synthesis result, that need to be preserved between container restarts or recreations. Our volume share the project root “$PWD” containing source file and build directory
• the last word of the command “yosys” is the name of your image. if you gave it another name at the build stage, use the name you choose. If you gave it another version than “latest” don’t forget to add :<your_version> after the tag name. The container will be based on this image.

What is going to happen when you run the command:

1. Docker will created a container based on the yosys image you just created.
2. The Docker volume will mount the root project on your PC in the “/project” folder of your container.
3. It will run the command defined in the ENTRYPOINT of the image in the WORKDIR which is “/project”.
4. Since every directories and files are in place thanks to the volume (-v). Yosys (installed in the container) will run the synth.ys script (mounted with the volume). The script will get the top module, syntheses the design and finally creates a netlist synth.json and syn_log.txt in the build folder.
5. Thanks to the shared Docker volume, the build folder will persist any changes made to it, including the synth.json and syn_log.txt files. This means that these files will be saved in the build folder of your project on your computer, even after the container is deleted.
6. When the command inside the container has completed its execution, the container will automatically shut down and exit.

It’s important to keep in mind that every time you run the command, Docker will create a new container, rather than reusing the previous one. This ensures that you always have a clean and fresh workspace within the container. Once you’ve completed step 6, you can safely delete the container, as it won’t be needed again.

Your project tree should look like this after running the synthesis successfully :

Makefile
src:
    synth:
        - synth.ys
    hdl:
        - top.v
build:
    logs:
        - syn_log.txt
    artifacts:
        syn:
            - synth.json

Conclusion

Now you know how to install Yosys inside a docker container and use it to synthese your design. I highly recommend you to learn more about Docker and integrate it in your workflow. If you want to know more about Docker and/or Yosys please tell me in the description. In the next two articles, we will continue installing the tool-chain (with Icestorm and NextPnR) in docker.

If you like the article, please comment, share and bookmark. Thank you for reading !