Posted on

Dockerized FPGA toolchains

For a while, LXC (linux container) technology might have been known for the better chroot. Docker takes this approach even further by letting you mess with changes and undo them easily. You can just install foreign binaries and play with dependencies without compromising your desktop host’s runtime libraries. This article describes how to easily put commercial FPGA toolchains into a docker environment and carry them around on an external hard disk for quick installation on a new developer machine.

Lattice Diamond

The Lattice Diamond toolchain comes as RPM package and is recommended to be run under a Redhat OS. It is possible to convert to a DEB and install and run it on a Debian system likewise, but we try basing it on a minimal RPM compatible environment as an existing CentOS container.

This short howto describes the necessary steps for Diamond v3.8.

First create a file called Dockerfile in a sandbox work directory, like:

FROM centos

RUN yum update ; \
	yum install -y freetype libSM libXrender fontconfig libXext libXt \
		tcl xorg-x11-fonts-Type1 net-tools libusb-0.1.4 usbutils \
                libXScrnSaver-1.2.2

RUN adduser -u 1000 -g 100 diamond; echo ". env-setup.sh" >> /home/diamond/.bashrc

COPY env-setup.sh /home/diamond

ENTRYPOINT ["/bin/bash"]

You could automate things more by copying the RPM into the docker container, but that would just take useless space in the image (and stripping this back down would take little elegant extra action). Therefore we mount the directory where the RPM was downloaded to into the container. Unfortunately, there is no clean way to pull it from an official source.

You may have to sort out permissions first (by adding yourself to the ‘docker’ group) or prepend ‘sudo’ to each docker call.

The env-setup.sh is a small setup script needed to initialize the environment:

DIAMOND_DIR=/usr/local/diamond/3.8_x64

export DISPLAY=:0.0
bindir=$DIAMOND_DIR/bin/lin64

export QT_GRAPHICSSYSTEM=native

source $bindir/diamond_env

export LM_LICENSE_FILE=$HOME/license.dat

Other than that, follow these steps:

  1. Change UID and GID for adduser command in the Dockerfile, if necessary
  2. Run
    docker build -t diamond .
  3. Then you can start the docker container using the following command. Note you have to replace $ETHADDR by the ethernet MAC address you have registered your license.dat to. Also, make $PATH_TO_RPM_INSTALLDIR point to the directory where you installed the RPM from.
    docker run -ti -e DISPLAY=0:0 \
    --mac-address=$ETHADDR \
    --privileged --ipc host \
    -v $PATH_TO_RPM_INSTALLDIR:/mnt \
    -v /dev/bus/usb/:/dev/bus/usb/ \
    -v /tmp/.X11-unix/:/tmp/.X11-unix diamond:latest
  4. Then install diamond by
    rpm -i /mnt/diamond_3_8-base_x64-115-3-x86_64-linux.rpm
  5. You still need to copy your license.dat into your /home/diamond/ directory within the docker container. If it’s supposed to be elsewhere, edit the LM_LICENSE_FILE environment variable in env-setup.sh.
  6. Then you should be able to start the diamond GUI as user ‘diamond’:
    su -l diamond
    diamond
  7. Finally, if you are happy with your changes, you might want to commit everything to a new image:
    docker commit -m "Diamond install" $HASH_OF_YOUR_CONTAINER diamond:v0

A few notes

The -v option takes care about sharing your X11 sockets with the docker sandbox. Note that there also some options inside the env-setup.sh to make QT work in this limited environment. Don’t try to run Diamond as root, as the X11 forwarding will not be allowed.

For Diamond v3.9, the libXt package needs to be installed, the Dockerfile listing was updated accordingly.

Xilinx ISE

The same procedure works  for the ISE 14.7 toolchain. The Dockerfile in this case is almost similar, although includes a few X11 extras.

FROM centos

RUN yum update ; \
    yum install -y freetype libSM libXrender fontconfig libXext \
        tcl xorg-x11-fonts-Type1 net-tools libXScrnSaver-1.2.2 \
        libXi libXrandr \
        libusb-0.1.4 usbutils

RUN adduser -u 1000 -g 100 ise; echo ". env-setup.sh" >> /home/ise/.bashrc

COPY env-setup.sh /home/ise

ENTRYPOINT ["/bin/bash"]

Downloading and unpacking ISE

Make sure you have downloaded the following files from the Xilinx website:

Xilinx_ISE_DS_14.7_1015_1-1.tar
Xilinx_ISE_DS_14.7_1015_1-2.zip.xz
Xilinx_ISE_DS_14.7_1015_1-3.zip.xz
Xilinx_ISE_DS_14.7_1015_1-4.zip.xz

Then untar the first one by

> tar xf Xilinx_ISE_DS_14.7_1015_1-1.tar

This directory path will have to be exported to docker under $PATH_TO_UNPACKED_XILINX_TAR below.

The env-setup.sh file:

#!/bin/bash

export DISPLAY=:0.0
XILINXDIR=/opt/Xilinx/14.7/ISE_DS

. $XILINXDIR/settings64.sh
alias ise=$XILINXDIR/ISE/bin/lin64/ise

Likewise, the docker container is run by something like:

docker run -ti -e DISPLAY=0:0 \
--mac-address=$ETHADDR \
--privileged --ipc host \
-v $PATH_TO_UNPACKED_XILINX_TAR:/mnt \
-v /dev/bus/usb/:/dev/bus/usb/ \
-v /tmp/.X11-unix/:/tmp/.X11-unix ise:latest

Once you’re inside docker, install as root by running /mnt/xsetup. This may take a long time. Left to do:

  • Install a license file
  • Mess with the USB drivers for Impact. This is left open to the user. I am using xc3sprog from my host system.

4 thoughts on “Dockerized FPGA toolchains

  1. Thanks for these notes.
    Your container setup does not support the programer though.
    I have fiddled about a little.
    You have to start your container with other option to expose usb devices:

    -v /dev/bus/usb/:/dev/bus/usb/

    Then you need libusb dependancy:

    # yum install libusb-0.1.4 usbutils

    Also in host OS you must give access to /dev/bus/usb/../.. device (check lsusb) and remove ftdi_sio module in host OS:

    > sudo rmmod ftdi_sio

    1. Thanks.
      I’ve updated these.

      If you want to use the programmer and UART I/O from your design, like possible on some boards like MACHXO2 breakout, etc., you may also just run an “unbind” command, like:

      echo -n 1-3.2:1.0 > /sys/bus/usb/drivers/ftdi_sio/unbind

      to get rid of /dev/ttyUSB0, selectively.

  2. Looks like this is missing the env-setup.sh for Lattice?

    1. Fixed that, thanks!

Leave a Reply

Your email address will not be published. Required fields are marked *