/sdk-docker-fpga

Intel Quartus Prime Synthesis Engine for Docker

Primary LanguageDockerfileMIT LicenseMIT

Intel Quartus Prime Synthesis Engine for Docker

QuartusDocker

What is Quartus?

Intel® Quartus® Prime is programmable logic device design software for analysis and synthesis of HDL designs, enabling developers to compile their designs, perform timing analysis, examine RTL diagrams, simulate a design's reaction to different stimuli, and configure the target device with the programmer.

Quartus Prime includes an implementation of VHDL and Verilog for hardware description, visual editing of logic circuits, and vector waveform simulation.

Quick reference

What's in this image?

Quartus® Lite Edition for Intel's low-cost FPGA devices families.

These images are built from official installation files provided by Intel (specifically, FPGA Software Download Center).

Supported tags, hardware and respective Dockerfile links

Supported tag alias for specific FPGA projects

Project Version Alias Architecture Model
MiMiC NSX 17.1 mimic Various Various
Analogue Pocket 18.1 pocket Cyclone V 5CEBA4F23C8
Atlas 17.1 atlas Cyclone 10 LP 10CL025YU256C8G
MiST 13.1 mist Cyclone III EP3C25E144C8
MiSTer 17.0 mister Cyclone V SE 5CSEBA6U23I7
MultiCore 13.1 mc Cyclone IV E EP4CE10E22C8
MultiCore2 13.1 mc2 Cyclone IV E EP4CE22F17C8
MultiCore2 Plus 13.1 mcp Cyclone IV E EP4CE55F23C8
NeptUNO 13.1 neptuno Cyclone IV E EP4CE55F23C8
SiDi 13.1 sidi Cyclone IV E EP4CE22F17C8
Turbo Chameleon 64 v1 13.1 tc64v1 Cyclone III EP3C25E144C8
Turbo Chameleon 64 v2 18.1 tc64v2 Cyclone 10 LP 10CL025YU256C8G
Unamiga Reloaded 13.1 uareloaded Cyclone IV E EP4CE55F23C8

MiMiC Supported Boards: DE10-Nano, SoCKit, Deca, C10LP-RefKit, CYC1000, Chameleon96.

Usage: docker run -it --rm raetro/quartus:<alias>. E.g.: docker run -it --rm raetro/quartus:mimic

How to use this image

The images are published on the Docker Hub as raetro/quartus:<version> and GitHub Container Registry as ghcr.io/raetro/quartus:<version>.

While the images works fine on desktops, the primary purpose is to be used in a continuous integration and continuous deployment (CI/CD) pipeline.

GitHub actions workflow

Running compilation flow

name: Test Build

on:
  push:
    branches:
      - main
    paths-ignore:
      - '**.md'
  pull_request:
    branches:
      - main
    paths-ignore:
      - '**.md'

jobs:
  synthesis:
    runs-on: ubuntu-latest
    container: raetro/quartus:17.1
    steps:
      # 1 - Checkout repository
      - name: Checkout repository
        uses: actions/checkout@v2
      # 2 - RTL synthesis
      - name: Run compilation flow
        run: quartus_sh --flow compile my_project.qpf
      # 3 - Upload artifacts
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: OutputFiles.zip
          path: output_files/

For more examples and full workflow look inside the examples folder

Desktop

Install the image

docker pull raetro/quartus:<version> #DockerHub
# or
docker pull ghcr.io/raetro/quartus:<version> #GitHub Packages

Run the image

docker run -it --rm -v /path/to/project:/build raetro/quartus:<version> #DockerHub
# or
docker run -it --rm -v /path/to/project:/build ghcr.io/raetro/quartus:<version> #GitHub Packages

Docker will automatically download the image if it's not present locally

Run a complete compilation flow

Use the quartus_sh executable with the --flow option to perform a complete compilation flow with a single command.

Linux/Mac Terminal
docker run -it --rm -v $(pwd):/build raetro/quartus:17.1 quartus_sh --flow compile my_project.qpf
Windows

Windows Command Line (cmd)

docker run -it --rm -v %cd%:/build raetro/quartus:17.1 quartus_sh --flow compile my_project.qpf

Windows PowerShell/WSL (Debian/Ubuntu)

docker run -it --rm -v ${pwd}:/build raetro/quartus:17.1 quartus_sh --flow compile my_project.qpf

WSL Users: Make sure to enable WSL Integration on Docker Desktop at Settings > Resources > WSL Integration

Where:

  • docker run spins up the container from the image
  • -it specifies that you want an interactive TTY
  • --rm tells it to remove this temporary image when it exits
  • -v <cmd> mounts a volume on the current directory and :/build within the container
  • raetro/quartus:17.1 is our Docker Image and
  • quartus_sh --flow compile my_project.qpf perform a complete compilation flow.

Your project will be synthesized inside the container and exit when it finishes, the output files will be placed in the project directory.

Note: The --flow option supports the smart recompile feature and efficiently sets command-line arguments for each executable in the flow. You can resume an interrupted compilation with the -resume argument of the --flow option.

Quick Pro Tip

Add an alias to your profile:

Mac: nano ~/.bash_profile Linux: nano ~/.bashrc or nano ~/.profile

alias qdc='f(){ docker run -it --rm -v "$(pwd)":/build raetro/quartus:17.1 "$@"; unset -f f; }; f'

Windows PowerShell: ${Home}\Documents\WindowsPowerShell\Profile.ps1

Function _qdc { docker run -it --rm -v ${pwd}:/build raetro/quartus:17.1 @Args }
Set-Alias -Name qdc -Value _qdc

From now on you can simply type qdc to log into the container on the current folder, or just qdc quartus_sh --flow compile my_project.qpf to compile your source code.

Environment Variables

  • GITHUB_TOKEN: The GitHub token to use with GitHub CLI.
  • JTAG_SERVER: JTAG Server Name/IP address (eg: host running jtagd/jtagserver).
  • JTAG_PASSWD: JTAG Server Password.
  • LM_LICENSE_FILE: Specifies the location of a license file. Note: Separate multiple license servers and node locking license files with ":"

Using Docker CLI

docker run -it -rm \
    -e JTAG_SERVER=192.168.1.10 \
    -e JTAG_PASSWD=1234 \
    -e GITHUB_TOKEN=<GH_PAT> \
    -e LM_LICENSE_FILE=/opt/license.dat \
    -v /path/to/license.dat:/opt/license.dat:ro
    -v ${pwd}:/build \
    raetro/quartus:17.1

Programming the FPGA

Building locally

If you want to make local modifications to these images for development purposes or just to customize the logic:

git clone https://github.com/raetro/sdk-docker-fpga.git
cd sdk-docker-fpga
./build.sh -v17.1 -b
# or if you wanna change the base image
./build.sh -vbase -o

build.sh

Quartus Prime Lite Container Builder.

Usage: build.sh [-v] [OPTION...]

  -v    Quartus version to build.
        [13.0, 13.1, 17.0, 17.1, 18.1, 19.1, 20.1, 21.1]

 Main modes of operation:
  -b    Build container using remote files.
  -p    Publish container to registry.
  -g    Publish container to GitHub registry.
  -d    Download files for local build.
  -l    Build container using local files.
  -c    Check local files integrity.
  -o    Build Base OS.

 eg. build.sh -v21.1 -b
     build.sh -vbase -o

Usage examples

./build.sh -v17.1 -b # Build container using remote files.
./build.sh -v17.1 -p # Publish container to registry.
./build.sh -v17.1 -g # Publish container to GitHub registry.
./build.sh -v17.1 -d # Download files for local build.
./build.sh -v17.1 -c # Check local files integrity.
./build.sh -v17.1 -l # Build container using local files.
./build.sh -vbase -o # Build Base OS container.

Creating an Image Variant

The Quartus images come in many versions, each designed for a specific use case.

If you need to install any additional packages beyond what comes with the image, you can do so by expanding the container.

For example, if you need to install the verilator utility, you can do so by creating a new Dockerfile for your project.

FROM raetro/quartus:17.1

RUN apt-get update                                         && \
    apt-get install -y --no-install-recommends verilator      \
    autoconf g++ flex bison ccache libgoogle-perftools-dev    \
    numactl perl-doc libfl-dev zlibc zlib1g zlib1g-dev     && \
    rm -rf /var/lib/apt/lists/* \

CMD [ "/bin/bash" ]

Then, run the commands to build and run the Docker image:

docker build -t quartus-verilator .
docker run -it --rm quartus-verilator

What's in the Box

What's in the Box

Further Reading

Intel Legal Notice

Intel® Quartus® Prime Software - Copyright © Intel Corporation. All rights reserved.

Altera, Avalon, Cyclone, Intel, the Intel logo, MAX, Nios, Quartus are trademarks of Intel Corporation or its subsidiaries.

Your use of Intel Corporation's design tools, logic functions and other software and tools, and its AMPP partner logic functions, and any output files from any of the foregoing (including device programming or simulation files), and any associated documentation or information are expressly subject to the terms and conditions of the Intel Program License Subscription Agreement, the Intel Quartus Prime License Agreement, the Intel FPGA IP License Agreement, or other applicable license agreement, including, without limitation, that your use is for the sole purpose of programming logic devices manufactured by Intel and sold by Intel or its authorized distributors. Please refer to the applicable agreement for further details.

FPGA Software License Subscription Agreements

License

This work is licensed under multiple licenses.

The Rætro authors and contributors or any of its maintainers are in no way associated with or endorsed by Intel® or any other company not implicit indicated. All other brands or product names are the property of their respective holders.

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc. from the base distribution, along with any direct or indirect dependencies of the primary software being contained).

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.