github-mirrors/cvw
1
0
Fork 0
mirror of https://github.com/openhwgroup/cvw.git synced 2025-04-19 11:34:50 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Make the README clear and fix some bugs in scripts.

Browse source
This commit is contained in:
Kunlin Han 2024-04-01 15:50:31 -07:00
parent 3d4b80eb3e
commit afa797e7f2
5 changed files with 127 additions and 47 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/docker/Dockerfile.builds
View file

@ -84,7 +84,7 @@ RUN apt-get install -y \
RUN git clone https://github.com/verilator/verilator && \
cd verilator && \
git pull && \
git checkout master && \
git checkout v5.022 && \
autoconf && \
./configure --prefix=${RISCV} && \
make -j ${NUM_THREADS} && \

113
docs/docker/README.md
View file

@ -7,25 +7,20 @@
- [ ] 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
- [x] Mount the ~~EDA Tools~~QuestaSIM and Path
- USE_QUESTA and QUESTA for path
- [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
Steps:
1. Install either Docker Engine or Podman for container support
2. Run start-up script `docs/docker/start.sh` to start a stateless container to run the toolchains and EDA tool
### Docker Engine or Podman
First and foremost, install either Docker Engine or Podman:
@ -60,9 +55,11 @@ docker run hello-world
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:
Here are some common use cases, it will provides you an environment with RISC-V toolchains that required by this project:
```shell
# By default, we assume that you have cloned the cvw respository and running the script at relative path `docs/docker`
# 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
@ -70,19 +67,31 @@ TOOLCHAINS_MOUNT=/opt/riscv QUESTA=/cad/mentor/questa_sim-2023.4 ./start.sh
TOOLCHAINS_MOUNT=<path-to-toolchains> ./start.sh
# For those have nothing, fetching the builds are easiest thing
./start.sh
CVW_MOUNT=<path-to-cvw> ./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
```
For further usage, please consult the following configuration.
## 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
## New Dockerfile Design
There are two parts of the new docker-related design:
- build proper image(s)
- set up start-up script
- scripts for different purposes
### Problem Statement
@ -111,19 +120,30 @@ Because we are going to use the whole environment of ubuntu to get both executab
### Scripts
There are two scripts:
There are four scripts:
- `start.sh` (most often used): start running the container
- if you don't care about toolchains and running regression automatically, this script is only thing you need to know
- `get_images.sh`: get docker image `wallysoc/ubuntu_wally` or `wallysoc/toolchains_wally`
- `start.sh`: start running the container
- `run_regression.sh`: run regressions with Verilator (and QuestaSIM) on specific CVW
- `test.sh`: a test script to facilitate the above three
#### Image Building Script
All the following options in the corresponding scripts should be set by either:
Options (if you want to build the images):
- define it right before the command: `USE_PODMAN=1 ./start.sh` with USE_PODMAN on start-up script
- the variable is only effective for the current command, not the following environment
- declare it globally and use it any time afterwards:
- UBUNTU_BUILD: value other than 0
- TOOLCHAINS_BUILD: value other than 0
```shell
# declare it globally in the environment
export DOCKER_EXEC=$(which docker)
export UBUNTU_BUILD=1
#### Start-up Script
# run the script with all the above variables
./get_images.sh
```
#### Start-up Script: start.sh
There are two settings:
@ -132,14 +152,27 @@ 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
- USE_PODMAN:
- by default, docker is used
- set USE_PODMAN=1 otherwise
- UBUNTU_BUILD:
- fetch by default
- set UBUNTU_BUILD=1 if you want to build with Dockerfile.ubuntu
- TOOLCHAINS_BUILD:
- fetch by default
- set TOOLCHAINS_BUILD=1 if you want to build with Dockerfile.build
#### Regression Script
#### Image Building Script: get_images.sh
Options (if you want to build the images):
- DOCKER_EXEC:
- docker by default
- if you want to use podman, then set it to $(which podman)
- UBUNTU_BUILD: value other than 0 if you want to build it instead of fetching it
- TOOLCHAINS_BUILD: value other than 0 if you want to build it instead of fetching it
#### Regression Script: run_regression.sh
There are two parts for regression:
@ -173,16 +206,24 @@ There are stages in the old Dockerfile:
- python3 package
- user and its group configuration
- clone and build toolchain with prefix=$RISCV
- riscv-gnu-toolchain
- elf2hex
- qemu
- spike
- sail
- buildroot
- verilator
- riscv-gnu-toolchain: https://github.com/riscv-collab/riscv-gnu-toolchain
- elf2hex: https://github.com/sifive/elf2hex
- qemu: https://github.com/qemu/qemu
- spike: https://github.com/riscv-software-src/riscv-isa-sim
- sail: https://github.com/riscv/sail-riscv/commits/master/
- buildroot: https://github.com/buildroot/buildroot
- verilator: https://github.com/verilator/verilator
### Tool Versions till 20240331
- riscv-gnu-toolchain: `2024.03.01`
- elf2hex: `f28a3103c06131ed3895052b1341daf4ca0b1c9c`
- qemu: not tested
- spike: `3427b459f88d2334368a1abbdf5a3000957f08e8`
- sail: `f601c866153c79a7ae8404f939dc2d66aa2e41f9`
- buildroot: `2021.05`
- verilator: `v5.022`
## References
- Dockerfile Docs: https://docs.docker.com/reference/dockerfile/

13
docs/docker/get_images.sh
View file

@ -1,6 +1,11 @@
UBUNTU_BUILD=${UBUNTU_BUILD:-0}
TOOLCHAINS_BUILD=${TOOLCHAINS_BUILD:-0}
DOCKER_EXEC=${DOCKER_EXEC-$(which podman)}
if [ -n "$USE_PODMAN" ]; then
DOCKER_EXEC=$(which podman)
else
DOCKER_EXEC=$(which docker)
fi
# if UBUNTU_BUILD is 0, then call function fetch_ubuntu_image
# otherwise, call function build_ubuntu_image
@ -14,8 +19,8 @@ fi
# if TOOLCHAINS_BUILD is 0, then call function fetch_toolchains_image
# otherwise, call function build_toolchains_image
if [ $TOOLCHAINS_BUILD -eq 0 ]; then
${DOCKER_EXEC} pull wallysoc/wally_toolchains
${DOCKER_EXEC} pull wallysoc/toolchains_wally
else
${DOCKER_EXEC} build -t wally_toolchains -f Dockerfile.builds .
${DOCKER_EXEC} tag wally_toolchains:latest wallysoc/wally_toolchains:latest
${DOCKER_EXEC} build -t toolchains_wally -f Dockerfile.builds .
${DOCKER_EXEC} tag toolchains_wally:latest wallysoc/toolchains_wally:latest
fi

24
docs/docker/run_regression.sh
View file

@ -2,22 +2,34 @@
# of course, you can run it in the current environment as soon as
# - RISCV is defined
# - QUESTA is defined
QUESTA="/cad/mentor/questa_sim-xxxx.x_x"
# now only main branch is supported
if [ -z "${CVW_GIT+x}" ]; then
echo "No CVW_GIT is provided"
CVW_GIT="https://github.com/openhwgroup/cvw"
fi
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 cvw is not available or new cvw is required
if [ ! -f "/home/${USERNAME}/cvw/setup.sh" ] || [ -z "${CLEAN_CVW+x}" ]; then
cd /home/${USERNAME} && rm -rf /home/${USERNAME}/cvw
git clone --recurse-submodules ${CVW_GIT} /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 ..
if [ -z "${RUN_QUESTA+x}" ] ; then
if [ ! -f "${QUESTA}/questasim/bin/vsim" ]; then
echo "Cannot find vsim with ${QUESTA}/questasim/bin/vsim"
else
export PATH="${QUESTA}/questasim/bin:${PATH}"
cd sim && ./regression-wally 2>&1 > ./regression_questa.out && cd ..
fi
fi
cd sim && verilator -GTEST="\"arch64i\"" -DVERILATOR=1 \

22
docs/docker/test.sh Normal file
View file

@ -0,0 +1,22 @@
# There are three parts in testing as there are three scripts
# It is fine to use either docker or podman as they are equivalent in the context
export USE_PODMAN=1
## build either one of them
UBUNTU_BUILD=1 ./get_image.sh
echo "get images is $?"
## mount toolchian and questa
TOOLCHAINS_MOUNT=/opt/riscv QUESTA=/cad/mentor/questa_sim-2023.4 ./start.sh
# then run
# - `file ${QUESTA}/questasim/vsim` to check if it is properly mount
# - `file $RISCV/bin/riscv64-unknown-elf-gcc` to check the toolchain
## use internal toolchain
./start.sh
# then run
# - `file $RISCV/bin/riscv64-unknown-elf-gcc` to check the toolchain
# - `which verilator | grep riscv` to check the verilator
## mount questa
RUN_QUESTA=true QUESTA=/cad/mentor/questa_sim-2023.4 ./run_regression.sh