Streamline installation process (Spike and toolchain variables, READM…

…E file). (#1468)

.gitlab-ci.yml

@@ -485,7 +485,7 @@ fpga-boot:
     DASHBOARD_SORT_INDEX: 10
     DASHBOARD_JOB_CATEGORY: "Synthesis"
     VERILATOR_INSTALL_DIR: "NO" # Skip install and checks of verilator
-    SPIKE_ROOT: "NO"  # Skip install and checks of spike
+    SPIKE_INSTALL_DIR: "NO"  # Skip install and checks of spike
   script:
     - source verif/regress/install-cva6.sh
     - source $VIVADO2022_SETUP

Makefile

@@ -58,8 +58,8 @@ ifndef RISCV
 $(error RISCV not set - please point your RISCV variable to your RISCV installation)
 endif
 
-# By default assume spike resides at the RISCV prefix.
-SPIKE_ROOT     ?= $(RISCV)
+# By default assume spike resides at $(root-dir)/tools/spike prefix.
+SPIKE_INSTALL_DIR     ?= $(root-dir)/tools/spike
 
 # setting additional xilinx board parameters for the selected board
 ifeq ($(BOARD), genesys2)
@@ -122,7 +122,7 @@ dpi_hdr := $(addprefix $(root-dir), $(dpi_hdr))
 CFLAGS += -I$(QUESTASIM_HOME)/include         \
           -I$(VCS_HOME)/include               \
           -I$(RISCV)/include                  \
-          -I$(SPIKE_ROOT)/include             \
+          -I$(SPIKE_INSTALL_DIR)/include      \
           -std=c++17 -I../corev_apu/tb/dpi -O3
 
 ifdef XCELIUM_HOME
@@ -312,7 +312,7 @@ $(dpi-library)/%.o: corev_apu/tb/dpi/%.cc $(dpi_hdr)
 $(dpi-library)/ariane_dpi.so: $(dpi)
 	mkdir -p $(dpi-library)
 	# Compile C-code and generate .so file
-	$(CXX) -shared -m64 -o $(dpi-library)/ariane_dpi.so $? -L$(RISCV)/lib -L$(SPIKE_ROOT)/lib -Wl,-rpath,$(RISCV)/lib -Wl,-rpath,$(SPIKE_ROOT)/lib -lfesvr
+	$(CXX) -shared -m64 -o $(dpi-library)/ariane_dpi.so $? -L$(RISCV)/lib -L$(SPIKE_INSTALL_DIR)/lib -Wl,-rpath,$(RISCV)/lib -Wl,-rpath,$(SPIKE_INSTALL_DIR)/lib -lfesvr
 
 # single test runs on Questa can be started by calling make <testname>, e.g. make towers.riscv
 # the test names are defined in ci/riscv-asm-tests.list, and in ci/riscv-benchmarks.list
@@ -324,32 +324,32 @@ generate-trace-vsim:
 
 sim: build
 	$(VSIM) +permissive $(questa-flags) $(questa-cmd) -lib $(library) +MAX_CYCLES=$(max_cycles) +UVM_TESTNAME=$(test_case) \
-	+BASEDIR=$(riscv-test-dir) $(uvm-flags) $(QUESTASIM_FLAGS) -gblso $(SPIKE_ROOT)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi  \
+	+BASEDIR=$(riscv-test-dir) $(uvm-flags) $(QUESTASIM_FLAGS) -gblso $(SPIKE_INSTALL_DIR)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi  \
 	${top_level}_optimized +permissive-off ++$(elf-bin) ++$(target-options) | tee sim.log
 
 $(riscv-asm-tests): build
 	$(VSIM) +permissive $(questa-flags) $(questa-cmd) -lib $(library) +max-cycles=$(max_cycles) +UVM_TESTNAME=$(test_case) \
-	+BASEDIR=$(riscv-test-dir) $(uvm-flags) +jtag_rbb_enable=0  -gblso $(SPIKE_ROOT)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi        \
+	+BASEDIR=$(riscv-test-dir) $(uvm-flags) +jtag_rbb_enable=0  -gblso $(SPIKE_INSTALL_DIR)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi        \
 	${top_level}_optimized $(QUESTASIM_FLAGS) +permissive-off ++$(riscv-test-dir)/$@ ++$(target-options) | tee tmp/riscv-asm-tests-$@.log
 
 $(riscv-amo-tests): build
 	$(VSIM) +permissive $(questa-flags) $(questa-cmd) -lib $(library) +max-cycles=$(max_cycles) +UVM_TESTNAME=$(test_case) \
-	+BASEDIR=$(riscv-test-dir) $(uvm-flags) +jtag_rbb_enable=0  -gblso $(SPIKE_ROOT)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi        \
+	+BASEDIR=$(riscv-test-dir) $(uvm-flags) +jtag_rbb_enable=0  -gblso $(SPIKE_INSTALL_DIR)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi        \
 	${top_level}_optimized $(QUESTASIM_FLAGS) +permissive-off ++$(riscv-test-dir)/$@ ++$(target-options) | tee tmp/riscv-amo-tests-$@.log
 
 $(riscv-mul-tests): build
 	$(VSIM) +permissive $(questa-flags) $(questa-cmd) -lib $(library) +max-cycles=$(max_cycles) +UVM_TESTNAME=$(test_case) \
-	+BASEDIR=$(riscv-test-dir) $(uvm-flags) +jtag_rbb_enable=0  -gblso $(SPIKE_ROOT)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi        \
+	+BASEDIR=$(riscv-test-dir) $(uvm-flags) +jtag_rbb_enable=0  -gblso $(SPIKE_INSTALL_DIR)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi        \
 	${top_level}_optimized $(QUESTASIM_FLAGS) +permissive-off ++$(riscv-test-dir)/$@ ++$(target-options) | tee tmp/riscv-mul-tests-$@.log
 
 $(riscv-fp-tests): build
 	$(VSIM) +permissive $(questa-flags) $(questa-cmd) -lib $(library) +max-cycles=$(max_cycles) +UVM_TESTNAME=$(test_case) \
-	+BASEDIR=$(riscv-test-dir) $(uvm-flags) +jtag_rbb_enable=0  -gblso $(SPIKE_ROOT)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi        \
+	+BASEDIR=$(riscv-test-dir) $(uvm-flags) +jtag_rbb_enable=0  -gblso $(SPIKE_INSTALL_DIR)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi        \
 	${top_level}_optimized $(QUESTASIM_FLAGS) +permissive-off ++$(riscv-test-dir)/$@ ++$(target-options) | tee tmp/riscv-fp-tests-$@.log
 
 $(riscv-benchmarks): build
 	$(VSIM) +permissive $(questa-flags) $(questa-cmd) -lib $(library) +max-cycles=$(max_cycles) +UVM_TESTNAME=$(test_case) \
-	+BASEDIR=$(riscv-benchmarks-dir) $(uvm-flags) +jtag_rbb_enable=0 -gblso $(SPIKE_ROOT)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi   \
+	+BASEDIR=$(riscv-benchmarks-dir) $(uvm-flags) +jtag_rbb_enable=0 -gblso $(SPIKE_INSTALL_DIR)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi   \
 	${top_level}_optimized $(QUESTASIM_FLAGS) +permissive-off ++$(riscv-benchmarks-dir)/$@ ++$(target-options) | tee tmp/riscv-benchmarks-$@.log
 
 # can use -jX to run ci tests in parallel using X processes
@@ -551,7 +551,7 @@ verilate_command := $(verilator) verilator_config.vlt
                     $(if $(DEBUG), --trace-structs,)                                                             \
                     $(if $(TRACE_COMPACT), --trace-fst $(VL_INC_DIR)/verilated_fst_c.cpp)                        \
                     $(if $(TRACE_FAST), --trace $(VL_INC_DIR)/include/verilated_vcd_c.cpp)                       \
-                    -LDFLAGS "-L$(RISCV)/lib -L$(SPIKE_ROOT)/lib -Wl,-rpath,$(RISCV)/lib -Wl,-rpath,$(SPIKE_ROOT)/lib -lfesvr$(if $(PROFILE), -g -pg,) -lpthread $(if $(TRACE_COMPACT), -lz,)" \
+                    -LDFLAGS "-L$(RISCV)/lib -L$(SPIKE_INSTALL_DIR)/lib -Wl,-rpath,$(RISCV)/lib -Wl,-rpath,$(SPIKE_INSTALL_DIR)/lib -lfesvr$(if $(PROFILE), -g -pg,) -lpthread $(if $(TRACE_COMPACT), -lz,)" \
                     -CFLAGS "$(CFLAGS)$(if $(PROFILE), -g -pg,) -DVL_DEBUG"                                      \
                     --cc  --vpi                                                                                  \
                     $(list_incdir) --top-module ariane_testharness                                               \
@@ -628,12 +628,12 @@ torture-rtest-verilator: verilate
 
 run-torture: build
 	$(VSIM) +permissive $(questa-flags) $(questa-cmd) -lib $(library) +max-cycles=$(max_cycles)+UVM_TESTNAME=$(test_case)                                  \
-	+BASEDIR=$(riscv-torture-dir) $(uvm-flags) +jtag_rbb_enable=0 -gblso $(SPIKE_ROOT)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi                                      \
+	+BASEDIR=$(riscv-torture-dir) $(uvm-flags) +jtag_rbb_enable=0 -gblso $(SPIKE_INSTALL_DIR)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi                                      \
 	${top_level}_optimized +permissive-off +signature=$(riscv-torture-dir)/$(test-location).rtlsim.sig ++$(riscv-torture-dir)/$(test-location) ++$(target-options)
 
 run-torture-log: build
 	$(VSIM) +permissive $(questa-flags) $(questa-cmd) -lib $(library) +max-cycles=$(max_cycles)+UVM_TESTNAME=$(test_case)                                  \
-	+BASEDIR=$(riscv-torture-dir) $(uvm-flags) +jtag_rbb_enable=0 -gblso $(SPIKE_ROOT)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi                                      \
+	+BASEDIR=$(riscv-torture-dir) $(uvm-flags) +jtag_rbb_enable=0 -gblso $(SPIKE_INSTALL_DIR)/lib/libfesvr.so -sv_lib $(dpi-library)/ariane_dpi                                      \
 	${top_level}_optimized +permissive-off +signature=$(riscv-torture-dir)/$(test-location).rtlsim.sig ++$(riscv-torture-dir)/$(test-location) ++$(target-options)
 	cp vsim.wlf $(riscv-torture-dir)/$(test-location).wlf
 	cp trace_hart_0000.log $(riscv-torture-dir)/$(test-location).trace

README.md

@@ -129,18 +129,44 @@ This BSP is used by both `core` testbench and `uvmt_cva6` UVM verification envir
 There are README files in each directory with additional information.
 
 #### Prerequisites
-To execute tests on CVA6 core, you need a RISC-V toolchain.
 
-To build and install RISC-V GCC compiler locally, you can use the toolchain generation scripts
-located under `util/gcc-toolchain-builder`.
+In brief, you will need:
+- a native C/C++ development environment to build simulation tools and models;
+- a RISC-V toolchain to build the CVA6 test programs;
+- optionally, an EDA tool that supports building and running simulation models of designs expressed in SystemVerilog.
+
+To build the open-source tools used by CVA6 and to run CVA6 simulations, you will need
+a native compilation toolchain for C and C++.  Such toolchains are available on virtually
+all Linux distributions as pre-installed or optional packages.   If unsure, ask your system
+administrator to install one on your system.
+
+To build test programs for the CVA6 core, you need a RISC-V toolchain.
+For GCC-based toolchains, only GCC versions above 11.1.0 are supported;
+it is recommended to use GCC 13.1.0 or above.
+
+You can use a pre-built toolchain (available for most common Linux/macOS
+distributions from a variety of providers) or build one from scratch using
+publicly available source code repositiores.  The second approach may prove
+necessary on older or unsupported Linux installations.
+
+To use a pre-built RISC-V toolchain, download and install the package(s) for your
+Linux distribution as per instructions from the toolchain provider, and set the
+`RISCV` environment variable to the installation location of the toolchain:
+
+```sh
+# Set environment variable RISCV to the location of the installed toolchain.
+export RISCV=/path/to/toolchain/installation/directory
+```
+
+To build and install RISC-V GCC toolchain locally, you can use the toolchain generation scripts
+located under `util/gcc-toolchain-builder`.  Please make sure beforehand that you have
+installed all the required *toolchain build* dependencies (see
+[the toolchain README file](file:util/gcc-toolchain-builder/README.md).)
 
 ```sh
-# Set environment variables. The toolchain can be installed
-# in any user-writable directory.
+# Set environment variable RISCV to the desired installation location.
+# The toolchain can be installed in any user-writable directory.
 export RISCV=/path/to/toolchain/installation/directory
-export CV_SW_PREFIX=riscv-none-elf-
-export RISCV_PREFIX=$RISCV/bin/$CW_SW_PREFIX
-export RISCV_GCC=$RISCV_PREFIXgcc
 
 # Get the source code of toolchain components from public repositiories.
 cd util/gcc-toolchain-builder
@@ -155,8 +181,7 @@ bash ./build-toolchain.sh $RISCV
 cd -
 ```
 
-These four variables will ensure you use correctly the new gcc compiler you have just installed.
-You will now be able to run the test scripts.
+You will now be able to run the CVA6 test scripts.
 
 #### Environent setup
 

verif/README.md

@@ -59,7 +59,7 @@ The default values are:
 - `RISCV_GCC`: `$RISCV/bin/riscv-none-elf-gcc`
 - `RISCV_OBJCOPY`: `$RISCV/bin/riscv-none-elf-objcopy`
 - `VERILATOR_ROOT`: `../tools/verilator-4.110` to install in core-v-verif/tools
-- `SPIKE_ROOT`: `../tools/spike` to install in core-v-verif/tools
+- `SPIKE_INSTALL_DIR`: `../tools/spike` to install in core-v-verif/tools
 
 - `CVA6_REPO`: `https://github.com/openhwgroup/cva6.git`
 - `CVA6_BRANCH`: `master`

verif/regress/install-cva6.sh

@@ -17,14 +17,17 @@ if [ -z "$RISCV" ]; then
   return
 fi
 
+# Auto-detect RISC-V tool name prefix if not explicitly given.
 if [ -z "$CV_SW_PREFIX" ]; then
     export CV_SW_PREFIX="$(ls -1 -r $RISCV/bin/riscv*-gcc | head -n 1| grep gcc | rev | cut -d '/' -f 1 | cut -d '-' -f 2- | rev)-"
 fi
 
+# Default to auto-detected GCC name if not explicitly given.
 if [ -z "$RISCV_GCC" ]; then
     export RISCV_GCC=$RISCV/bin/${CV_SW_PREFIX}gcc
 fi
 
+# Default to auto-detected OBJCOPY name if not explicitly given.
 if [ -z "$RISCV_OBJCOPY" ]; then
     export RISCV_OBJCOPY=$RISCV/bin/${CV_SW_PREFIX}objcopy
 fi
@@ -76,7 +79,7 @@ echo $CVA6_HASH
 echo $CVA6_PATCH
 
 # install Spike
-if [ -z "$SPIKE_ROOT" ]; then
-  export SPIKE_ROOT=$TOP/spike/
+if [ -z "$SPIKE_INSTALL_DIR" ]; then
+  export SPIKE_INSTALL_DIR=$TOP/spike/
 fi
 source verif/regress/install-spike.sh

verif/regress/install-riscv-dv.sh

@@ -15,7 +15,7 @@ fi
 if [ -z "$RISCV_OBJCOPY" ]; then
   export RISCV_OBJCOPY="$RISCV_TOOLCHAIN/bin/riscv-none-elf-objcopy"
 fi
-export SPIKE_PATH=$SPIKE_ROOT/bin
+export SPIKE_PATH=$SPIKE_INSTALL_DIR/bin
 export RTL_PATH=$ROOT_PROJECT/
 export TB_PATH=$ROOT_PROJECT/verif/tb/core
 export TESTS_PATH=$ROOT_PROJECT/verif/tests

verif/regress/install-spike.sh

@@ -8,53 +8,60 @@
 # Original Author: Jean-Roch COULON - Thales
 
 if [ -z ${NUM_JOBS} ]; then
-    NUM_JOBS=1
+  NUM_JOBS=1
 fi
 
-# Set SPIKE_ROOT to 'NO' to skip the installation/checks of Spike altogether.
-# This is useful for CI jobs not depending on Spike in any way.
-# Otherwise expect/perform Spike installation in directory $SPIKE_ROOT
-# which defaults to $ROOT_PROJECT/tools/spike.
-if [ -z "$SPIKE_ROOT" ]; then
-  # Set the default location if not provided by caller.
-  export SPIKE_ROOT=$ROOT_PROJECT/tools/spike
+# Make sure we know the path to the top of the CVA6 tree.
+if [ -z "$ROOT_PROJECT" ]; then
+  echo "ERROR: Variable ROOT_PROJECT not set, cannot continue!"
+  return 1
 fi
 
-if [ "$SPIKE_ROOT" = "NO" ]; then
-  echo "NOTE: Skipping Spike setup on user's request (\$SPIKE_ROOT = \"NO\")."
+# Set default installation location of Spike if not specified so far.
+if [ -z "$SPIKE_INSTALL_DIR" ]; then
+  export SPIKE_INSTALL_DIR=$ROOT_PROJECT/tools/spike
+fi
+
+# Set SPIKE_INSTALL_DIR to 'NO' to skip the installation/checks of Spike
+# altogether. This is useful for CI jobs not depending on Spike in any way.
+if [ "$SPIKE_INSTALL_DIR" = "NO" ]; then
+  echo "NOTE: Skipping Spike setup on user's request (\$SPIKE_INSTALL_DIR = \"NO\")."
 else
-  # Export the location of Spike source code.
-  export SPIKE_SRC_DIR=$ROOT_PROJECT/vendor/riscv/riscv-isa-sim
-
-  # Check if a local copy of Spike should be built/used ($SPIKE_INSTALL_DIR non empty).
-  # A value equal to '__local__' means $ROOT_PROJECT/tools/spike (same as $TOP/spike).
-  if [ -n "$SPIKE_INSTALL_DIR" ]; then
-      # Handle the 'default' value.
-      if [ "$SPIKE_INSTALL_DIR" = "__local__" ]; then
-        export SPIKE_INSTALL_DIR="$ROOT_PROJECT/tools/spike"
-      fi
-      # Override SPIKE_ROOT value with $SPIKE_INSTALL_DIR (the latter takes priority.)
-      echo "NOTE: Overriding SPIKE_ROOT value ('$SPIKE_ROOT') with \$SPIKE_INSTALL_DIR ('$SPIKE_INSTALL_DIR')."
-      export SPIKE_ROOT="$SPIKE_INSTALL_DIR"
-      # Do not clean up the destination directory: leave that to the user (real or CI job).
+  # Expect/perform Spike installation in directory $SPIKE_INSTALL_DIR.
+  # which defaults to $ROOT_PROJECT/tools/spike.
+
+  # Set the location of Spike source code.
+  # Use the in-tree vendorized Spike if SPIKE_SRC_DIR is not set
+  # or when a fully local installation was requested.
+  if [ -z "$SPIKE_SRC_DIR" -o "$SPIKE_INSTALL_DIR" = "__local__" ]; then
+    export SPIKE_SRC_DIR=$ROOT_PROJECT/vendor/riscv/riscv-isa-sim
   fi
 
+  # Set the installation location of Spike.
+  # A value equal to '__local__' means $ROOT_PROJECT/tools/spike.
+  if [ -n "$SPIKE_INSTALL_DIR" -o "$SPIKE_INSTALL_DIR" = "__local__" ]; then
+    export SPIKE_INSTALL_DIR="$ROOT_PROJECT/tools/spike"
+  fi
+
+  # Do not clean up the destination directory: leave that to the user (real or CI job).
+
   # Rebuild Spike or reuse an existing Spike build.
-  if [ ! -d "$SPIKE_ROOT" -o ! -f "$SPIKE_ROOT/bin/spike" ]; then
-    echo "Installing Spike in '$SPIKE_ROOT'..."
+  if ! [ -f "$SPIKE_INSTALL_DIR/bin/spike" ]; then
     # Keep track of current working dir.
-    CALLER_DIR=$(readlink -f $(pwd))
+    CALLER_DIR="$(pwd)"
     # Enter the vendorized tree.  It already captures the desired Spike config.
     cd $SPIKE_SRC_DIR
+    echo "Building Spike sources in $SPIKE_SRC_DIR..."
     # Build and install Spike (including extensions).
     mkdir -p build
     cd build
-    ../configure --enable-commitlog --prefix="$SPIKE_ROOT"
+    ../configure --prefix="$SPIKE_INSTALL_DIR"
     make -j${NUM_JOBS}
+    echo "Installing Spike in '$SPIKE_INSTALL_DIR'..."
     make install
     cd $CALLER_DIR
   else
-    echo "Using Spike from cached directory '$SPIKE_ROOT'."
+    echo "Using pre-installed Spike from '$SPIKE_INSTALL_DIR'."
   fi
 fi
 

verif/sim/Makefile

@@ -211,7 +211,7 @@ endif
 dpi-library = $(VCS_WORK_DIR)/work-dpi
 dpi_build:
 	mkdir -p $(dpi-library)
-	g++ -shared -fPIC -std=c++17 -Bsymbolic -I../corev_apu/tb/dpi -O3 -I$(SPIKE_ROOT)/include \
+	g++ -shared -fPIC -std=c++17 -Bsymbolic -I../corev_apu/tb/dpi -O3 -I$(SPIKE_INSTALL_DIR)/include \
 	-I$(VCS_HOME)/include -I$(RISCV)/include -c $(CVA6_REPO_DIR)/corev_apu/tb/dpi/elfloader.cc \
 	-o $(dpi-library)/elfloader.o
 	g++ -shared -m64 -o $(dpi-library)/ariane_dpi.so $(dpi-library)/elfloader.o -L$(RISCV)/lib -Wl,-rpath,$(RISCV)/lib

verif/sim/cva6.py

@@ -1001,7 +1001,7 @@ def main():
       sys.exit(RET_FAIL)
     #print environment softwares
     logging.info("GCC Version : %s" % (gcc_version))
-    spike_version=get_env_var("SPIKE_ROOT")
+    spike_version=get_env_var("SPIKE_INSTALL_DIR")
     logging.info("Spike Version : %s" % (spike_version))
     verilator_version=run_cmd("verilator --version")
     logging.info("Verilator Version : %s" % (verilator_version))