cvw/docs/D-Docker-Install.md

D Wally Toolchain Docker Container

Installing RISC-V tools from source gives you maximum control, but has several disadvantages:

• Building the executables takes several hours.
• Linux is poorly standardized, and the build steps might not work on your version
• The source files are constantly changing, and the versions you download might not be compatible with this textbook flow.

Docker is a tools to run applications in a prepackaged container including all of the operating system support required. Wally offers a ~30GB container image with the open-source tools pre-installed from Section D.1. In particular, using the container solves the long build time for gcc and the fussy installation of sail. The container runs on any platform supporting Docker, including Windows and Mac as well as Linux. It can access files outside the container, including local installation of CAD tools such as Questa, and a local clone of the core-v-wally repository.

Docker can be run on most operating systems, including Linux, Windows, and Mac. The Wally Docker container is hosted at DockerHub (http://docker.io).

Podman is a more secure and easier-to-use variation of Docker for Linux developed by RedHat. Both Docker and Podman run the same containers.

D.3.1 Podman Installation on Linux

A system administrator must install Podman if it is not already present.

For Ubuntu 20.10 or later:

$ sudo apt-get -y install podman

For RedHat / Rocky:

$ sudo yum -y install podman

D.3.2 Pulling the Wally Container

Once Podman is installed, a user can pull the Wally container image. The user must sign up for a free account at docker.io, and will be prompted for the credentials when running podman login.

$ podman login docker.io $ podman pull docker.io/wallysoc/wally-docker:latest

D.3.3 Running the Docker Container in Podman

To activate podman with GUI support, first identify your display port in the /tmp/.X11-unix file as shown below. For example, the user ben is on port X51.

$ ls -la /tmp/.X11-unix/ drwxrwxrwt 2 root root 4096 Jan 6 05:01 . drwxrwxrwt 122 root root 40960 Jan 17 08:09 .. srwxrwxrwx 1 root root 0 Jan 5 08:48 X0 srwxrwxrwx 1 xwalter xwalter 0 Jan 5 09:21 X50 srwxrwxrwx 1 ben ben 0 Jan 6 05:01 X51

Then run podman with the display number after the X (51 in this case). The -v options also mount the user’s home directory (/home/ben) and cad tools (/cad) to be visible from the container. Change these as necessary based on your local system configuration.

$ podman run -it --net=host -e DISPLAY=:51 -v /tmp/.X11-unix:/tmp/.X11-unix -v /home/ben:/home/ben -v /cad:/cad -p 8080:8080 docker.io/wallysoc/wally-docker

Podman sets up all the RISC-V software in the same location of /opt/riscv as the cad user as discussed previously. This shared directory is called $RISCV. This environmental variable should also be set up within the Docker container automatically and ready to use once the container is run. It is important to understand that Docker containers are self-contained, and any data created within your container is lost when you exit the container. Therefore, be sure to work in your mounted home directory (e.g. /home/ben) to permanently save your work outside the container.

To have permission to write to your mounted home directory, you must become root inside the Wally container. This is an acceptable practice as the security will be maintained within podman for the user that runs podman. To become root once inside your container:

$ su # when prompted for password, enter wally

D.3.4 Cleaning up a Podman Container

The Docker container image is large, so users may need to clean up a container when they aren’t using it anymore. The images that are loaded can be examined, once you pull the Wally container, by typing:

$ podman images

To remove individual podman images, the following Linux command will remove the specific podman image where the image name is obtained from the podman images command (this command also works equally well using the <Image_ID> instead of the <Image_name>, as well).

$ podman rmi -f <Image_name>

D.3.5 Running the Docker Container on Windows or MacOS

Docker Desktop is easiest to use for Mac OS or Windows and can be installed by downloading from http://docker.com. Once the desktop application is installed, users can log into their DockerHub account through the Docker Desktop application and manage their containers easily.

*** with Questa *** questa unavailable native on Mac

D.3.6 Regenerating the Docker File

We use the following steps to generate the Docker file. You can adapt them is you wish to make your own custom Docker image, such as one with commercial CAD tools installed in your local environment.

*** how to use this

Compliance Development Environment Image

FROM debian

UPDATE / UPGRADE

RUN apt update

INSTALL

RUN apt install -y git gawk make texinfo bison flex build-essential python libz- dev libexpat-dev autoconf device-tree-compiler ninja-build libpixman-1-dev build -essential ncurses-base ncurses-bin libncurses5-dev dialog curl wget ftp libgmp- dev python3-pip pkg-config libglib2.0-dev opam build-essential z3 pkg-config zl ib1g-dev verilator cpio bc vim emacs gedit nano

RUN pip3 install chardet==3.0.4 RUN pip3 install urllib3==1.22 RUN pip3 install testresources RUN pip3 install riscof --ignore-installed PyYAML RUN echo "root:wally" | chpasswd

ADD RISCV

WORKDIR /opt/riscv

Create a user group 'xyzgroup'

ARG USERNAME=cad ARG USER_UID=1000 ARG USER_GID=$USER_UID

Create the user

RUN groupadd --gid $USER_GID $USERNAME
&& useradd --uid $USER_UID --gid $USER_GID -m $USERNAME
# [Optional] Add sudo support. Omit if you don't need to install software af ter connecting. && apt-get update
&& apt-get install -y sudo
&& echo $USERNAME ALL=root NOPASSWD:ALL > /etc/sudoers.d/$USERNAME
&& chmod 0440 /etc/sudoers.d/$USERNAME

Change RISCV user

run chown -Rf cad:cad /opt

Add cad user

USER $USERNAME

SET ENVIRONMENT VARIABLES

ENV RISCV=/opt/riscv ENV PATH=$PATH:$RISCV/bin

TOOLCHAIN

RUN git clone https://github.com/riscv/riscv-gnu-toolchain &&
cd riscv-gnu-toolchain &&
./configure --prefix=${RISCV} --enable-multilib --with-multilib-generator="r v32e-ilp32e--;rv32i-ilp32--;rv32im-ilp32--;rv32iac-ilp32--;rv32imac-ilp32--;rv32 imafc-ilp32f--;rv32imafdc-ilp32d--;rv64i-lp64--;rv64ic-lp64--;rv64iac-lp64--;rv6 4imac-lp64--;rv64imafdc-lp64d--;rv64im-lp64--;" &&
make --jobs &&
make install

elf2hex

ENV PATH=$RISCV/riscv-gnu-toolchain/bin:$PATH WORKDIR /opt/riscv RUN git clone https://github.com/sifive/elf2hex.git &&
cd elf2hex &&
autoreconf -i &&
./configure --target=riscv64-unknown-elf --prefix=$RISCV &&
make &&
make install

QEMU

WORKDIR /opt/riscv RUN git clone --recurse-submodules https://github.com/qemu/qemu &&
cd qemu &&
./configure --target-list=riscv64-softmmu --prefix=$RISCV &&
make --jobs &&
make install

Spike

WORKDIR /opt/riscv RUN git clone https://github.com/riscv-software-src/riscv-isa-sim &&
mkdir riscv-isa-sim/build &&
cd riscv-isa-sim/build &&
../configure --prefix=$RISCV --enable-commitlog &&
make --jobs &&
make install &&
cd ../arch_test_target/spike/device &&
sed -i 's/--isa=rv32ic/--isa=rv32iac/' rv32i_m/privilege/Makefile.include &&
sed -i 's/--isa=rv64ic/--isa=rv64iac/' rv64i_m/privilege/Makefile.include

SAIL

WORKDIR /opt/riscv RUN opam init -y --disable-sandboxing RUN opam switch create ocaml-base-compiler.4.06.1 RUN opam install sail -y RUN eval $(opam config env) &&
cd $RISCV &&
git clone https://github.com/riscv/sail-riscv.git &&
cd sail-riscv &&
make &&
ARCH=RV32 make &&
ARCH=RV64 make &&
ln -s $RISCV/sail-riscv/c_emulator/riscv_sim_RV64 $RISCV/bin/riscv_sim_RV64 &&
ln -s $RISCV/sail-riscv/c_emulator/riscv_sim_RV32 $RISCV/bin/riscv_sim_RV32

Buildroot

WORKDIR /opt/riscv RUN git clone --recurse-submodules https://stineje:ghp_kXIHqiMSv4tFec2BCAvrhSrIh 3KNUD06IejU@github.com/davidharrishmc/riscv-wally.git ENV export WALLY=/opt/riscv/riscv-wally RUN git clone https://github.com/buildroot/buildroot.git &&
cd buildroot &&
git checkout 2021.05 &&
cp -r /opt/riscv/riscv-wally/linux/buildroot-config-src/wally ./board &&
cp ./board/wally/main.config .config &&
make --jobs

change to cad's hometown

WORKDIR /home/cad

D.3.7 Integrating Commercial CAD Tools into a Local Docker Container

RISC-V System-on-Chip Design Lecture Notes © 2023 D. Harris, J. Stine, , R. Thompson, and S. Harris These notes may be used and modified for educational and/or non-commercial purposes so long as the source is attributed.