Docker, Xilinx Platforms & PYNQ


PYNQ v2.6 released last week and one feature we added was docker support. This means docker is ready to run on any PYNQ enabled board (Zynq-7000, ZU+ and RFSoC).

Why? Well, containers are a great way to deliver complete applications and their dependencies on top of existing platforms. Perhaps you’ve used containers on your x86 machines – one notable example is the Xilinx Vitis-AI docker that includes all the tools necessary for training ML models targeting Xilinx’s DPU. Within the PYNQ team, we use containers inside our Jenkins flows for automated building of SD Card images. And finally, delivering applications for IoT edge devices is also often done using a software container technology.

In the context of Xilinx Platforms using PYNQ – this now means users can explore delivering and sharing FPGA applications through Docker Hub or within container-based orchestration frameworks.

How do I run Docker’s hello worlds on PYNQ?

Docker out-of-box allows users to run some simple images to see docker working. For PYNQ v2.6 images – copy/paste the steps below to get the helloworld applications running (I ran examples on a Ultra96 board):

# replace 'arm64' with 'armhf' if using a Zynq-7000 part
sudo apt-get -y install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
sudo echo "deb [arch=arm64] bionic stable" > /etc/apt/sources.list.d/docker.list
sudo curl -fsSL | sudo apt-key add -
sudo apt-get update

export CIO_VER=1.2.6-3
export DCE_VER=5:19.03.14~3-0~ubuntu-bionic
apt-get -y install$CIO_VER
apt-get -y install docker-ce=$DCE_VER docker-ce-cli=$DCE_VER

And then to actually see docker working, some nice examples below:

docker run hello-world
docker run -it ubuntu bash

You should see an Ubuntu 20.04 prompt in your terminal window.

Other Docker images

…will run on PYNQ. Visiting Docker Hub, there are ~32K images that support arm64 (remember not all docker images support arm64 or armhf architectures). I tried out the RUST docker image and was able to download the image onto an Ultra96 and use it to compile a hello-world Rust program. When I’m done with the image, I can delete it, leaving my existing root filesystem in its original state.

My RUST Dockerfile

FROM rust:latest

COPY . .

RUN rustc
CMD ["/hello"]

And my file

fn main() {
   println!("hello rust from within docker on pynq");

Now building and running it…

docker build -t rust-docker-hello .
docker run rust-docker-hello

And output is as expected!


And for FPGA overlays

If you’d like to run an overlay, the actual docker run call needs to expose a subset of Linux devices to allow the container’s pynq access to the programmable logic. Adding --privileged flag to the docker run call allows the container to access Linux device drivers - also not the most secure thing to do. I tried out the PYNQ Helloworld example starting from the Ubuntu base image and everything runs as expected. We’ll release docker files for this in the future - pip install ... is still the best way to load PYNQ overlays for now.

Look for more blogs as we explore containers for Xilinx platforms. And please let us know how you would use containers on PYNQ enabled devices.



When I try to run the following command:

I get the following error:
The following packages have unmet dependencies: docker-ce : Depends: (>= 1.4.1) but 1.2.6-3 is to be installed E: Unable to correct problems, you have held broken packages.
Here it says that I need to have (>=1.4.1) Where as the given instructions installs

My pynq image is 2.6

Thanks for letting me know.

I just updated the steps in the blog to hardcode the versions of docker-ce-* packages. I reran on a fresh v2.6 image and was able to replicate the helloworld, ubuntu and rust docker examples. Let me know if that fixes things for you as well.


Yup, It worked, Thanks!

May i ask, what is the docker base image that u used? I cant seem to install pynq==2.6.0 for an ubuntu docker base image container

Are you trying to install pynq in a container?

I’d recommend a ubuntu 18.04 base image … what error are you seeing?