diff --git a/docs/docker/README.md b/docs/docker/README.md index c5c89ab64..65ca3ac5c 100644 --- a/docs/docker/README.md +++ b/docs/docker/README.md @@ -2,6 +2,11 @@ `Dockerfile.*` contains a ~~multi-stage~~ build for all the toolchains that are required for Wally's open-source features. +Hazards: + +- If there is any change in `${CVW_HOME}/linux/buildroot-config-src` folder with main.config, you have to copy it to the current folder to `buildroot-config-src` +- If there is any change in `${CVW_HOME}/linux/testvector-generation` folder with main.config, you have to copy it to the current folder to `testvector-generation` + ## TODOs - [ ] Pinning the tools version @@ -12,8 +17,10 @@ - [x] Enable X11 forwarding for docker - `--network=host` for docker run - `xhost +localhost:${USER}` for host -- [ ] Regression Script -- [ ] Configure the license for Questa +- [x] Regression Script +- [x] Configure the license for Questa +- [ ] Change the condition from empty string to 1 +- [ ] Add linux testvector-generation ## TL;DR @@ -56,7 +63,7 @@ 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, it will provides you an environment with RISC-V toolchains that required by this project: +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` @@ -76,6 +83,42 @@ USE_PODMAN=1 ./start.sh ``` For further usage, please consult the following configuration. +### Regression on Master Branch + +The regression script is used by image `wallysoc/regression_wally` to run regressions on the master branch of a specific repository. + +If you are using docker, then replace the following podman with docker. + +```shell +# create volume for permanent storage +podman volume create cvw_temp + +# run regression on the OpenHW/cvw +podman run \ + -e CLEAN_CVW= -e BUILD_RISCOF= -e RUN_QUESTA= \ + -v cvw_temp:/home/cad/cvw \ + -v /cad/mentor/questa_sim-2023.4:/cad/mentor/questa_sim-xxxx.x_x \ + --privileged --network=host \ + --rm wallysoc/regression_wally + +# run regression on the Karl-Han/cvw +podman run \ + -e CLEAN_CVW= -e BUILD_RISCOF= -e RUN_QUESTA= \ + -e CVW_GIT=https://github.com/Karl-Han/cvw \ + -v cvw_temp:/home/cad/cvw \ + -v /cad/mentor/questa_sim-2023.4:/cad/mentor/questa_sim-xxxx.x_x \ + --privileged --network=host \ + --rm wallysoc/regression_wally + +# get into the container command line to debug or reading files +podman run -it \ + -e RUN_QUESTA= \ + -v cvw_temp:/home/cad/cvw \ + -v /cad/mentor/questa_sim-2023.4:/cad/mentor/questa_sim-xxxx.x_x \ + --privileged --network=host \ + wallysoc/regression_wally /bin/bash +``` + ## Conventions - In the container @@ -127,6 +170,8 @@ There are four scripts: - 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` - `run_regression.sh`: run regressions with Verilator (and QuestaSIM) on specific CVW + - this script is not intended to be run directly, but inside the container + - However, it is a good resource to look into to know what is happening - `test.sh`: a test script to facilitate the above three All the following options in the corresponding scripts should be set by either: @@ -170,8 +215,12 @@ 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 +- UBUNTU_BUILD: + - fetch by default + - set it to 1 if you want to build it instead of fetching it +- TOOLCHAINS_BUILD: + - fetch by default + - set it to 1 if you want to build it instead of fetching it #### Regression Script: run_regression.sh @@ -180,9 +229,19 @@ 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 + +There are three main knobs: + +1. CLEAN_CVW: remove the `/home/${USERNAME}/cvw` inside the container (it can be a volume) and clone the `${CVW_GIT}`. +2. BUILD_RISCOF: build RISCOF in the `/home/${USERNAME}/cvw`, sometimes you don't want to rebuild if there is no change in the test suite. +3. RUN_QUESTA: enable the QuestaSIM in regression + Options: -- RUN_QUESTA: false by default +- CVW_GIT: git clone address, only main branch supported +- CLEAN_CVW: declared with empty string to clone +- BUILD_RISCOF: declared with empty string to rebuild RISCOF +- RUN_QUESTA: declared with empty string to run vsim to check - 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` diff --git a/docs/docker/get_images.sh b/docs/docker/get_images.sh index 17b1567c9..145028aaf 100755 --- a/docs/docker/get_images.sh +++ b/docs/docker/get_images.sh @@ -7,20 +7,16 @@ else DOCKER_EXEC=$(which docker) fi -# if UBUNTU_BUILD is 0, then call function fetch_ubuntu_image -# otherwise, call function build_ubuntu_image -if [ $UBUNTU_BUILD -eq 0 ]; then - ${DOCKER_EXEC} pull wallysoc/ubuntu_wally -else +if [ $UBUNTU_BUILD -eq 1 ]; then ${DOCKER_EXEC} build -t ubuntu_wally -f Dockerfile.ubuntu . ${DOCKER_EXEC} tag ubuntu_wally:latest wallysoc/ubuntu_wally:latest +else + ${DOCKER_EXEC} pull wallysoc/ubuntu_wally 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/toolchains_wally -else +if [ $TOOLCHAINS_BUILD -eq 1 ]; then ${DOCKER_EXEC} build -t toolchains_wally -f Dockerfile.builds . ${DOCKER_EXEC} tag toolchains_wally:latest wallysoc/toolchains_wally:latest +else + ${DOCKER_EXEC} pull wallysoc/toolchains_wally fi \ No newline at end of file diff --git a/docs/docker/run_regression.sh b/docs/docker/run_regression.sh index ecb4a33d8..6bea790c3 100755 --- a/docs/docker/run_regression.sh +++ b/docs/docker/run_regression.sh @@ -3,6 +3,14 @@ # of course, you can run it in the current environment as soon as # - RISCV is defined # - QUESTA is defined +# declare with empty string: export ABC= + +# Options: +# - CVW_GIT: git clone address, only main branch supported +# - CLEAN_CVW: declared with empty string to clone +# - BUILD_RISCOF: declared with empty string to rebuild RISCOF +# - RUN_QUESTA: declared with empty string to run vsim to check + # now only main branch is supported if [ -z "${CVW_GIT}" ]; then echo "No CVW_GIT is provided" @@ -31,25 +39,28 @@ chmod +x ${CVW_HOME}/site-setup.sh && source ${CVW_HOME}/site-setup.sh # Overwriting export QUESTAPATH=/cad/mentor/questa_sim-xxxx.x_x/questasim/bin -# if you are making it alone, it works -make +# # if you are making it alone, it works +# make +cd ${CVW_HOME} # build it only if BUILD_RISCOF is defined with empty string -# if [[ -z "${BUILD_RISCOF-x}" ]]; then -# make install && make riscof && make testfloat -# fi +if [[ -z "${BUILD_RISCOF-x}" ]]; then + make install && make riscof && make testfloat +fi -# if [[ -z "${RUN_QUESTA-x}" ]] ; then -# if [ ! -f "${QUESTA}/questasim/bin/vsim" ]; then -# echo "Cannot find vsim with ${QUESTA}/questasim/bin/vsim" -# else -# # cd sim && ./regression-wally 2>&1 > ./regression_questa.out && cd .. -# make verify -# fi -# fi +if [[ -z "${RUN_QUESTA-x}" ]] ; then + if [ ! -f "${QUESTA}/questasim/bin/vsim" ]; then + echo "Cannot find vsim with ${QUESTA}/questasim/bin/vsim" + else + # cd sim && ./regression-wally 2>&1 > ./regression_questa.out && cd .. + make verify + fi +fi -# make coverage -# make benchmarks +make coverage +make benchmarks -cd ${CVW_HOME}/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 -${CVW_HOME}/sim/obj_dir/Vtestbench > ${CVW_HOME}/sim/regression_verilator.out +if [[ ! NO_VERILATOR -eq 1 ]]; then + cd ${CVW_HOME}/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 + ${CVW_HOME}/sim/obj_dir/Vtestbench > ${CVW_HOME}/sim/regression_verilator.out +fi