diff --git a/docs/docker/Dockerfile.regression b/docs/docker/Dockerfile.regression new file mode 100644 index 000000000..50579723b --- /dev/null +++ b/docs/docker/Dockerfile.regression @@ -0,0 +1,13 @@ +FROM wallysoc/toolchains_wally + +ENV QUESTA=/cad/mentor/questa_sim-xxxx.x_x +ENV RUN_QUESTA=false +ENV USERNAME=cad + +VOLUME [ "/home/${USERNAME}/cvw" ] + +COPY . /home/${USERNAME} +USER ${USERNAME} +WORKDIR /home/${USERNAME}/cvw + +CMD [ "/bin/sh", "-c", "/home/${USERNAME}/run_regression.sh" ] \ No newline at end of file diff --git a/docs/docker/Dockerfile.ubuntu b/docs/docker/Dockerfile.ubuntu index 3347c6ce9..cc98bd5c5 100644 --- a/docs/docker/Dockerfile.ubuntu +++ b/docs/docker/Dockerfile.ubuntu @@ -1,10 +1,5 @@ FROM ubuntu:22.04@sha256:aa772c98400ef833586d1d517d3e8de670f7e712bf581ce6053165081773259d -# Create a user group 'xyzgroup' -ARG USERNAME=cad -ARG USER_UID=1000 -ARG USER_GID=$USER_UID - RUN apt update && \ apt install -y \ git gawk make texinfo bison flex build-essential python3 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 z3 zlib1g-dev automake autotools-dev libmpc-dev libmpfr-dev gperf libtool patchutils verilator cpio bc vim emacs gedit nano && \ @@ -16,6 +11,11 @@ RUN pip3 install --no-cache-dir \ RUN ln -s /usr/bin/python3 /usr/bin/python +# Create a user group 'xyzgroup' +ENV 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} \ diff --git a/docs/docker/README.md b/docs/docker/README.md index 81d16d593..4b61b63e4 100644 --- a/docs/docker/README.md +++ b/docs/docker/README.md @@ -11,21 +11,68 @@ - [x] 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) + +```shell +# 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: ```shell -# For HMC students, /opt/riscv is available and nothing needs to be built, skip this file +# 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= ./start +TOOLCHAINS_MOUNT= ./start.sh # For those have nothing, fetching the builds are easiest thing -./start +./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 ``` @@ -85,12 +132,26 @@ There are two settings: 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. @@ -120,6 +181,8 @@ There are stages in the old Dockerfile: - buildroot - verilator +### Tool Versions till 20240331 + ## References - Dockerfile Docs: https://docs.docker.com/reference/dockerfile/ diff --git a/docs/docker/run_regression.sh b/docs/docker/run_regression.sh new file mode 100755 index 000000000..0224c7c02 --- /dev/null +++ b/docs/docker/run_regression.sh @@ -0,0 +1,25 @@ +# this script is used to run regression inside the Dockerfile.regression +# of course, you can run it in the current environment as soon as +# - RISCV is defined +# - QUESTA is defined + +export PATH="${RISCV}/bin:${PATH}" +git config --global http.version HTTP/1.1 + +if [ ! -f "/home/${USERNAME}/cvw/setup.sh" ] || [ -n "${CLEAN_CVW+x}" ]; then + cd /home/${USERNAME} && rm -rf /home/${USERNAME}/cvw/* + git clone --recurse-submodules https://github.com/openhwgroup/cvw /home/${USERNAME}/cvw + # if failed to clone submodules for some reason, please run `git submodule update` +fi + +cd /home/${USERNAME}/cvw && chmod +x ./setup.sh && ./setup.sh +make install && make riscof && make testfloat + +if [ "${RUN_QUESTA}" != "false" ] && [ -f "${QUESTA}/questasim/bin/vsim" ]; then + export PATH="${QUESTA}/questasim/bin:${PATH}" + cd sim && ./regression-wally 2>&1 > ./regression_questa.out && cd .. +fi + +cd sim && verilator -GTEST="\"arch64i\"" -DVERILATOR=1 \ + --timescale "1ns/1ns" --timing --binary --top-module testbench -I../config/shared -I../config/rv64gc ../src/cvw.sv ../testbench/testbench.sv ../testbench/common/*.sv ../src/*/*.sv ../src/*/*/*.sv --relative-includes +./obj_dir/Vtestbench 2>&1 > ./regression_verilator.out diff --git a/docs/docker/start.sh b/docs/docker/start.sh index 50ea9ecf9..504433267 100755 --- a/docs/docker/start.sh +++ b/docs/docker/start.sh @@ -1,4 +1,8 @@ -DOCKER_EXEC=${DOCKER_EXEC-$(which podman)} +if [ -n "$USE_PODMAN" ]; then + DOCKER_EXEC=$(which podman) +else + DOCKER_EXEC=$(which docker) +fi CVW_MOUNT=${CVW_MOUNT:$(pwd)/../../} UBUNTU_WALLY_HASH=$(${DOCKER_EXEC} images --quiet wallysoc/ubuntu_wally) @@ -13,7 +17,11 @@ else fi if [ ! -z $TOOLCHAINS_MOUNT ]; then - ${DOCKER_EXEC} run -it --rm -v ${TOOLCHAINS_MOUNT}:/opt/riscv -v ${CVW_MOUNT}:/home/${USERNAME}/cvw wallysoc/ubuntu_wally + if [ -n "$QUESTA" ]; then + ${DOCKER_EXEC} run -it --rm -v ${TOOLCHAINS_MOUNT}:/opt/riscv -v ${CVW_MOUNT}:/home/${USERNAME}/cvw -v ${QUESTA}:/cad/mentor/questa_sim-xxxx.x_x wallysoc/ubuntu_wally + else + ${DOCKER_EXEC} run -it --rm -v ${TOOLCHAINS_MOUNT}:/opt/riscv -v ${CVW_MOUNT}:/home/${USERNAME}/cvw wallysoc/ubuntu_wally + fi elif [ -z $TOOLCHAINS_HASH ]; then echo "CANNOT FIND wallysoc/toolchains_wally, please get the image first with \`get_image.sh\`"; exit 1