Tutorials

Docker instructions for the ESP tutorial

The Docker images for this tutorial are a smaller version of the main ESP Docker images, tailored for this tutorial. If you are interested in using the main ESP Docker images please refer to the Docker section of the How to: setup guide.

Install Docker

To start the Docker daemon on Linux systems you need to run:

sudo systemctl start docker


On Linux systems you will need to use sudo to run all docker commands (sudo docker) unless you add your user to the docker group. To add your user to the docker group run the following:

sudo usermod -aG docker ${USER}


Then you need to logout and log back in and after that you can verify you are part of the docker group by running groups.

Download the Docker image

The Docker image for this tutorial is available on DockerHub: esp-tutorial. There are two Docker images available for this tutorial. The complete image for the tutorial is esp-tutorial:asplos2021 (compressed size: 1.5GB) . We also offer a smaller image esp-tutorial:asplos2021-small (compressed size: 600MB) which still allows you to run most steps of the tutorial, but it does not include the RISC-V software toolchain. To use the small image replace esp-tutorial:asplos2021 with esp-tutorial:asplos2021-small in all the Docker commands in this guide.

Download the Docker image by running the following command (on Windows 10 you should run it in the PowerShell).

# use this for the full image
docker pull davidegiri/esp-tutorial:asplos2021


You may need to add login credentials to be able to pull. In that case you can add your credentials by running the following. A prompt will ask for your password as well.

docker login -u <your-dockerhub-username>

Start the Docker container

Linux

This Docker has been tested on Ubuntu 18.04, CentOS 7 and RedHat 7.8, however it should work on other Linux distributions as well. On Linux you can start a Docker container in interactive mode by specifying security-opt, network, env and volume arguments when running your docker as follows:

# use this for the full image
docker run -it --security-opt label=type:container_runtime_t --network=host -e DISPLAY=$DISPLAY -v "$HOME/.Xauthority:/root/.Xauthority:rw" davidegiri/esp-tutorial:asplos2021 /bin/bash

MacOS

On MacOS you need to make sure that the X server is running and is configured properly to be able to open graphical interfaces from inside the Docker container:

  • Install XQuartz

  • Open a terminal and launch the application with open -a xQuartz.

  • From the XQuartz drop-down menu, open Preferences.. and select the Security tab. Make sure that the check box “Allow connections from network clients” is enabled, as shown in the picture below.

  • From the same drop-down menu, quit XQuartz. The application must exit completely, then you should restart XQuartz.

  • From a new terminal window, enable X forwarding for your current IP address:

      ip=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')
  xhost + $ip


Finally, you can run the container as follows:

docker run -it --network=host -e DISPLAY=$ip:0 -v /tmp/.X11-unix:/tmp/.X11-unix davidegiri/esp-tutorial:asplos2021 /bin/bash

Windows 10

On Windows 10 you can start a Docker container in interactive mode from the Docker dashboard GUI by clicking first on the RUN button next to the Docker image name and then on the CLI button next to the running container.

To be able to launch graphical interfaces from inside the container on Windows 10 you need a couple of extra steps (adapted from these guides: guide1, guide2):

  • Install VcXsrv Windows X Server and after that launch XLaunch. In the XLaunch configuration steps use all the default configurations apart from selecting the “Disable access control” option, which is not selected by default.

  • Find the IP of you Windows machine by running ipconfig in the PowerShell. Look for the IPv4 Address entry.

  • Run export DISPLAY=<host-ip-address>:0.0 in the Docker container that you previously started with the CLI button.

Test X forwarding

From inside the container you can test the connection to the host display by running xeyes or xclock.

Environment setup in the container

To setup the container environment for the tutorial run the following in every new terminal you launch in the container:

cd /home/espuser/
source esp_env.sh

CAD tools with Docker

Although some of the SoC design steps of ESP require CAD tools (e.g. an RTL simulator), the tutorial steps performed by the participants will not require access to any CAD tool. However, you can refer to the CAD tools with Docker of the How to: setup guide to learn how to use CAD tools with the ESP Docker images.

Useful Docker commands

Exit a container:

# run from inside the container
exit


List all local containers and their IDs:

docker ps -a


Stop a container:

docker stop <container-ID>


Start a container:

docker start <container-ID>


Attach to a running container:

docker attach <container-ID>


Copy data from host machine to a container:

docker cp <path-on-host> <container-ID>:/<path-inside-container>


Delete a container:

docker rm -f <container-ID>


List all local images:

docker images


Delete an image:

docker rmi <image-name>


Here is the complete Docker documentation.