cvw/docs/docker

Consistant Build of Toolchain for Wally

Dockerfile.* contains a multi-stage build for all the toolchains that are required for Wally's open-source features.

TODOs

• Pinning the tools version
  • As for the consistent tool build, should we use specific versions of tools in order to avoid bugs at the master branch?
  • And we will upgrade the versions of tool after a certain period of time to get the latest features and patches while verifying it won’t cause any problem.
• Mount the EDA Tools and Path
• Enable X11 forwarding for docker
  • --network=host for docker run
  • xhost +localhost:${USER} for host
• Regression Script

Conventions

• In the container
  • default user is cad
  • RISCV is defined as /opt/riscv
  • QUESTA is defined as /cad/mentor/questa_sim-xxxx.x_x
    • bin location is in $QUESTA/questasim/bin
  • cvw folder should be mounted on /home/${USERNAME}/cvw
    • as for cad, it is /home/cad/cvw
• In the current shell environment: checkout the constants in the following script section

TL;DR

Docker Engine or Podman

First and foremost, install either Docker Engine or Podman:

• Docker Engine (More Popular, default): https://docs.docker.com/engine/install/
• Podman: https://podman.io/docs/installation

Here are some common installation commands (not guarantee to be up to date)

# For Ubuntu
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
# Installation
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
# Hello-World Example
docker run hello-world

Use of Start-up Script

Files at this folder can help you to build/fetch environment you need to run wally with the help of Docker.

Here are some common use cases, read the following text for other configuration:

# For HMC students, /opt/riscv is available and nothing needs to be built
TOOLCHAINS_MOUNT=/opt/riscv QUESTA=/cad/mentor/questa_sim-2023.4 ./start.sh

# For those with all the toolchains installed, simply mount the toolchains
TOOLCHAINS_MOUNT=<path-to-toolchains> ./start.sh

# For those have nothing, fetching the builds are easiest thing
./start.sh
# if you want to use Podman instead of Docker Engine
USE_PODMAN=1 ./start.sh

# For other cases, checkout start-up script for building option

New Dockerfile Design

There are two parts of the new docker-related design:

• build proper image(s)
• set up start-up script

Problem Statement

The following 3 problems are to be resolved:

• remove storage of useless files with Dockerfile
  • git build: clean up
  • packages info
    • apt: apt-get clean
    • pip: --no-cache-dir
• reuse storage
  • read-only $RISCV volume across different users with docker image
  • local-built RISCV with start-up script
• use commercial EDA tools: optional environment variable configuration with start-up script

Dockerfiles

There are two Dockerfiles:

• Dockerfile.ubuntu: basic ubuntu system setup and produce ubuntu_wally image in docker
  • corresponds to wallysoc/ubuntu_wally
• Dockerfile.builds: all the required toolchains are built
  • corresponds to wallysoc/toolchains_wally

Because we are going to use the whole environment of ubuntu to get both executables and python packages, we are not going to use multi-stage builds, which runs only executables.

Scripts

There are two scripts:

• get_images.sh: get docker image wallysoc/ubuntu_wally or wallysoc/toolchains_wally
• start.sh: start running the container

Image Building Script

Options (if you want to build the images):

• UBUNTU_BUILD: value other than 0
• TOOLCHAINS_BUILD: value other than 0

Start-up Script

There are two settings:

• build/fetch both ubuntu_wally and toolchains in docker image and use it
• build/fetch only ubuntu_wally and use local toolchains folder

Options:

• use podman instead of docker: USE_PODMAN=1
• ubuntu_wally: fetch by default
  • build: UBUNTU_BUILD=1
• toolchains: fetch by default
  • build: TOOLCHAINS_BUILD=1
  • use local toolchain: TOOLCHAINS_MOUNT

Regression Script

There are two parts for regression:

• Verilator: must be able to run as it is open-sourced
• Questa: OPTIONAL as it is commercial EDA Tool

Options:

• RUN_QUESTA: false by default
  • QUESTA: home folder for mounted QuestaSIM /cad/mentor/questa_sim-xxxx.x_x if enabled
  • for example, if your vsim is in /cad/mentor/questa_sim-2023.4/questasim/bin/vsim then your local QuestaSIM folder is /cad/mentor/questa_sim-2023.4, so you have to add -v /cad/mentor/questa_sim-2023.4:/cad/mentor/questa_sim-xxxx.x_x -e RUN_QUESTA=1

Commercial EDA Tools

This is kind of tricky, because Docker network is a different network from the host. Therefore, it should be carefully handled in order to use the host's license server while minimizing the access of docker container.

There are at least two ways to solve this problem:

• use --network=host in docker-run to use the same network
• (NOT WORKING) use bridge in docker-run while forwarding docker network's traffic to localhost without setting X11UseLocalhost no
  • this idea is from https://stackoverflow.com/a/64284364/10765798

Old Dockerfile Analysis

Refer to 91919150a9/docs/Dockerfile

There are stages in the old Dockerfile:

• debian-based package installtion
  • apt package
  • python3 package
• user and its group configuration
• clone and build toolchain with prefix=$RISCV
  • riscv-gnu-toolchain
  • elf2hex
  • qemu
  • spike
  • sail
  • buildroot
  • verilator

Tool Versions till 20240331

References

• Dockerfile Docs: https://docs.docker.com/reference/dockerfile/
• Multi-stage builds: https://docs.docker.com/build/building/multi-stage/
• Best Practices: https://docs.docker.com/develop/develop-images/guidelines/
• Chinese Reference: https://yeasy.gitbook.io/docker_practice/
• Clean Cache
  • apt cache: https://gist.github.com/marvell/7c812736565928e602c4
  • pip cache: https://stackoverflow.com/questions/50333650/install-python-package-in-docker-file
• Docker Network: https://docs.docker.com/network/