From 9f52f7712ae68f865fab03c3dc9cde33550a27cc Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Wed, 3 Jul 2024 23:42:31 -0700 Subject: [PATCH] Update installation script comments --- bin/wally-distro-check.sh | 3 +- bin/wally-package-install.sh | 15 ++--- bin/wally-tool-chain-install.sh | 99 +++++++++++++++++++++------------ 3 files changed, 73 insertions(+), 44 deletions(-) diff --git a/bin/wally-distro-check.sh b/bin/wally-distro-check.sh index 79a62dfd0..d8c87f2c4 100755 --- a/bin/wally-distro-check.sh +++ b/bin/wally-distro-check.sh @@ -36,7 +36,8 @@ SECTION_COLOR='\033[95m'$BOLD OK_COLOR='\033[94m' WARNING_COLOR='\033[93m' FAIL_COLOR='\033[91m' -ENDC='\033[0m' +ENDC='\033[0m' # Reset to default color + echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" diff --git a/bin/wally-package-install.sh b/bin/wally-package-install.sh index fd9031ccc..d9f668c51 100755 --- a/bin/wally-package-install.sh +++ b/bin/wally-package-install.sh @@ -34,7 +34,7 @@ BOLD='\033[1m' SECTION_COLOR='\033[95m'$BOLD SUCCESS_COLOR='\033[92m' FAIL_COLOR='\033[91m' -ENDC='\033[0m' +ENDC='\033[0m' # Reset to default color # If run standalone, determine distro information. Otherwise, use info from main install script if [ -z "$FAMILY" ]; then @@ -42,11 +42,12 @@ if [ -z "$FAMILY" ]; then source "${dir}"/wally-distro-check.sh fi -# Generate list of packages to install, determined based on distro + +# Generate list of packages to install and package manager commands based on distro +# Packages are grouped by which tool requires them. If multiple tools need a package, it is included in the first tool only if [ "$FAMILY" = rhel ]; then PACKAGE_MANAGER="dnf" UPDATE_COMMAND="sudo dnf update -y" - # Packages are grouped by which tool requires them. If multiple tools need a package, it is included in the first tool only GENERAL_PACKAGES="git make cmake python3.12 python3-pip curl wget ftp tar pkgconf-pkg-config dialog mutt ssmtp" GNU_PACKAGES="autoconf automake libmpc-devel mpfr-devel gmp-devel gawk bison flex texinfo gperf libtool patchutils bc gcc gcc-c++ zlib-devel expat-devel libslirp-devel" QEMU_PACKAGES="glib2-devel libfdt-devel pixman-devel bzip2 ninja-build" @@ -63,7 +64,6 @@ if [ "$FAMILY" = rhel ]; then elif [ "$FAMILY" = ubuntu ]; then PACKAGE_MANAGER=apt UPDATE_COMMAND="sudo apt update -y && sudo apt upgrade -y" - # Packages are grouped by which tool requires them. If multiple tools need a package, it is included in the first tool only GENERAL_PACKAGES="git make cmake python3 python3-pip python3-venv curl wget ftp tar pkg-config dialog mutt ssmtp" GNU_PACKAGES="autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat1-dev ninja-build libglib2.0-dev libslirp-dev" QEMU_PACKAGES="libfdt-dev libpixman-1-dev" @@ -81,7 +81,8 @@ elif [ "$FAMILY" = ubuntu ]; then fi fi -# Check packages are installed or install/update them depending on passed flag. + +# Check if required packages are installed or install/update them depending on passed flag. if [ "${1}" = "--check" ]; then echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" @@ -107,7 +108,7 @@ else echo -e "Installing/Updating Dependencies from Package Manager" echo -e "*************************************************************************" echo -e "*************************************************************************\n${ENDC}" - # Extra red hat commands to set up package manager with extra repos + # Enable extra repos necessary for rhel if [ "$FAMILY" = rhel ]; then sudo dnf install -y dnf-plugins-core sudo dnf group install -y "Development Tools" @@ -126,7 +127,7 @@ else # Update and Upgrade tools eval "$UPDATE_COMMAND" - # Install packages listed above + # Install packages listed above using appropriate package manager sudo "$PACKAGE_MANAGER" install -y $GENERAL_PACKAGES $GNU_PACKAGES $QEMU_PACKAGES $SPIKE_PACKAGES $VERILATOR_PACKAGES $SAIL_PACKAGES $BUILDROOT_PACKAGES $OTHER_PACKAGES echo -e "${SUCCESS_COLOR}Packages successfully installed.${ENDC}" fi diff --git a/bin/wally-tool-chain-install.sh b/bin/wally-tool-chain-install.sh index 09efdc163..bb243ce7a 100755 --- a/bin/wally-tool-chain-install.sh +++ b/bin/wally-tool-chain-install.sh @@ -13,7 +13,7 @@ ## A component of the CORE-V-WALLY configurable RISC-V project. ## https://github.com/openhwgroup/cvw ## -## Copyright (C) 2021-23 Harvey Mudd College & Oklahoma State University +## Copyright (C) 2021-24 Harvey Mudd College & Oklahoma State University ## ## SPDX-License-Identifier: Apache-2.0 WITH SHL-2.1 ## @@ -35,9 +35,6 @@ NUM_THREADS=8 # for >= 32GiB #NUM_THREADS=16 # for >= 64GiB -set -e # break on error -STATUS="setup" # keep track of what part of the installation is running for error messages - # Error handler error() { echo -e "${FAIL_COLOR}Error: $STATUS installation failed$" @@ -45,9 +42,11 @@ error() { exit 1 } -trap error ERR # run error function on error +set -e # break on error +trap error ERR # run error handler on error +STATUS="setup" # keep track of what part of the installation is running for error messages -# Get the directory of the script to find other scripts +# Determine script directory to locate related scripts dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" # Colors @@ -58,7 +57,7 @@ OK_COLOR='\033[94m' SUCCESS_COLOR='\033[92m' WARNING_COLOR='\033[93m' FAIL_COLOR='\033[91m' -ENDC='\033[0m' +ENDC='\033[0m' # Reset to default color # Get Linux distro and version source "${dir}"/wally-distro-check.sh @@ -66,22 +65,27 @@ source "${dir}"/wally-distro-check.sh # Check if root ROOT=$( [ "${EUID:=$(id -u)}" = 0 ] && echo true || echo false); -# All tools will be installed under the $RISCV directory. By default, if run as root (with sudo) this is set to -# /opt/riscv. Otherwise, it is set to ~/riscv. This value can be overridden with an argument passed to the script. +# Set installation directory based on execution privileges +# If the script is run as root, the default installation path is /opt/riscv +# If the script is run as a user, the default installation path is ~/riscv +# The installation path can be overridden with an argument passed to the script. if [ "$ROOT" = true ]; then export RISCV="${1:-/opt/riscv}" else export RISCV="${1:-$HOME/riscv}" fi +# Set environment variables export PATH=$PATH:$RISCV/bin:/usr/bin export PKG_CONFIG_PATH=$RISCV/lib64/pkgconfig:$RISCV/lib/pkgconfig:$RISCV/share/pkgconfig:$RISCV/lib/x86_64-linux-gnu/pkgconfig:$PKG_CONFIG_PATH -mkdir -p "$RISCV" +# Create installation directory +mkdir -p "$RISCV" echo "Running as root: $ROOT" echo "Installation path: $RISCV" -# Install/update packages if root. Otherwise, check that packages are already installed. + +# Install/update system packages if root. Otherwise, check that packages are already installed. STATUS="system packages" if [ "$ROOT" = true ]; then source "${dir}"/wally-package-install.sh @@ -89,10 +93,9 @@ else source "${dir}"/wally-package-install.sh --check fi +# Enable newer version of gcc for older distros (required for QEMU/Verilator) if [ "$FAMILY" = rhel ]; then - # A newer version of gcc is required for qemu - source /opt/rh/gcc-toolset-13/enable # activate gcc13 - # Newer version of gcc needed for Ubuntu 20.04 for Verilator + source /opt/rh/gcc-toolset-13/enable elif [ "$UBUNTU_VERSION" = 20 ]; then mkdir -p "$RISCV"/gcc-10/bin for f in gcc cpp g++ gcc-ar gcc-nm gcc-ranlib gcov gcov-dump gcov-tool lto-dump; do @@ -101,12 +104,13 @@ elif [ "$UBUNTU_VERSION" = 20 ]; then export PATH="$RISCV"/gcc-10/bin:$PATH fi + echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Setting up Python Environment" echo -e "*************************************************************************" echo -e "*************************************************************************\n${ENDC}" -# Create python virtual environment so the python command targets our desired version of python +# Create python virtual environment so the python command targets desired version of python # and installed packages are isolated from the rest of the system. STATUS="python virtual environment" cd "$RISCV" @@ -119,8 +123,9 @@ if [ ! -e "$RISCV"/riscv-python/bin/activate ]; then fi echo -e "${OK_COLOR}Python virtual environment created.\nInstalling pip packages.${ENDC}" else - echo -e "${OK_COLOR}Python virtual environment already exists.\Updating pip packages.${ENDC}" + echo -e "${OK_COLOR}Python virtual environment already exists.\nUpdating pip packages.${ENDC}" fi + source "$RISCV"/riscv-python/bin/activate # activate python virtual environment # Install python packages @@ -129,13 +134,15 @@ pip install -U pip pip install -U sphinx sphinx_rtd_theme matplotlib scipy scikit-learn adjustText lief markdown pyyaml testresources riscv_config pip install -U riscv_isac # to generate new tests, such as quads with fp_dataset.py -# z3 is eeded for sail and not availabe from dnf for rhel 8 +# z3 is needed for sail and not availabe from dnf for rhel 8 if [ "$RHEL_VERSION" = 8 ]; then pip install -U z3-solver fi + source "$RISCV"/riscv-python/bin/activate # reload python virtual environment echo -e "${SUCCESS_COLOR}Python environment successfully configured.${ENDC}" + # Extra dependecies needed for older distros that don't have new enough versions available from package manager if [ "$RHEL_VERSION" = 8 ] || [ "$UBUNTU_VERSION" = 20 ]; then # Newer versin of glib required for Qemu. @@ -147,8 +154,7 @@ if [ "$RHEL_VERSION" = 8 ] || [ "$UBUNTU_VERSION" = 20 ]; then echo -e "Installing glib" echo -e "*************************************************************************" echo -e "*************************************************************************\n${ENDC}" - # Meson is needed to build glib - pip install -U meson + pip install -U meson # Meson is needed to build glib cd "$RISCV" wget https://download.gnome.org/sources/glib/2.70/glib-2.70.5.tar.xz tar -xJf glib-2.70.5.tar.xz @@ -186,7 +192,10 @@ if [ "$RHEL_VERSION" = 8 ]; then fi fi -# gcc cross-compiler (https://github.com/riscv-collab/riscv-gnu-toolchain) + +# RISC-V GNU Toolchain (https://github.com/riscv-collab/riscv-gnu-toolchain) +# The RISC-V GNU Toolchain includes the GNU Compiler Collection (gcc), GNU Binutils, Newlib, +# and the GNU Debugger Project (gdb). It is a collection of tools used to compile RISC-V programs. # To install GCC from source can take hours to compile. # This configuration enables multilib to target many flavors of RISC-V. # This book is tested with GCC 13.2.0 @@ -208,8 +217,9 @@ else echo -e "${SUCCESS_COLOR}RISC-V GNU Toolchain already up to date${ENDC}" fi + # elf2hex (https://github.com/sifive/elf2hex) -#The elf2hex utility to converts executable files into hexadecimal files for Verilog simulation. +# The elf2hex utility to converts executable files into hexadecimal files for Verilog simulation. # Note: The exe2hex utility that comes with Spike doesn’t work for our purposes because it doesn’t # handle programs that start at 0x80000000. The SiFive version above is touchy to install. # For example, if Python version 2.x is in your path, it won’t install correctly. @@ -235,7 +245,9 @@ else echo -e "${SUCCESS_COLOR}elf2hex already up to date${ENDC}" fi + # QEMU (https://www.qemu.org/docs/master/system/target-riscv.html) +# QEMU is an open source machine emulator and virtualizer capable of emulating RISC-V echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Installing/Updating QEMU" @@ -254,9 +266,9 @@ else echo -e "${SUCCESS_COLOR}QEMU already up to date${ENDC}" fi + # Spike (https://github.com/riscv-software-src/riscv-isa-sim) -# Spike also takes a while to install and compile, but this can be done concurrently -# with the GCC installation. +# Spike is a reference model for RISC-V. It is a functional simulator that can be used to run RISC-V programs. echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Installing/Updating SPIKE" @@ -277,8 +289,11 @@ else echo -e "${SUCCESS_COLOR}Spike already up to date${ENDC}" fi -# Wally needs Verilator 5.021 or later. -# Verilator needs to be built from source to get the latest version + +# Verilator (https://github.com/verilator/verilator) +# Verilator is a fast open-source Verilog simulator that compiles synthesizable Verilog code into C++ code. +# It is used for linting and simulation of Wally. +# Verilator needs to be built from source to get the latest version (Wally needs 5.021 or later). echo -e "\n${SECTION_COLOR}*************************************************************************" echo -e "*************************************************************************" echo -e "Installing/Updating Verilator" @@ -287,7 +302,6 @@ echo -e "*********************************************************************** STATUS="Verilator" cd "$RISCV" if [[ ((! -e verilator) && ($(git clone https://github.com/verilator/verilator) || true)) || ($(cd verilator; git fetch; git rev-parse HEAD) != $(cd verilator; git rev-parse origin/master)) || (! -e $RISCV/share/pkgconfig/verilator.pc) ]]; then - # unsetenv VERILATOR_ROOT # For csh; ignore error if on bash unset VERILATOR_ROOT # For bash cd verilator git reset --hard && git clean -f && git checkout master && git pull @@ -300,15 +314,11 @@ else echo -e "${SUCCESS_COLOR}Verilator already up to date${ENDC}" fi -# RISC-V Sail Model (https://github.com/riscv/sail-riscv) -# The RISC-V Sail Model is the golden reference model for RISC-V. It is written in Sail, -# a language designed for expressing the semantics of an ISA. Sail itself is written in -# OCaml, which is an object-oriented extension of ML, which in turn is a functional programming -# language suited to formal verification. The Sail compiler is installed with the opam OCcaml -# package manager. The Sail compiler has so many dependencies that it can be difficult to install, -# but a binary release of it should be available soon, removing the need to use opam. + cd "$RISCV" if [ "$FAMILY" = rhel ]; then + # Install opam from binary disribution on rhel as it is not available from dnf + # Opam is needed to install the sail compiler echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Installing/Updating Opam" @@ -324,6 +334,13 @@ if [ "$FAMILY" = rhel ]; then echo -e "${SUCCESS_COLOR}Opam successfully installed/updated${ENDC}" fi +# Sail Compiler (https://github.com/rems-project/sail) +# Sail is a formal specification language designed for describing the semantics of an ISA. +# It is used to generate the RISC-V Sail Model, which is the golden reference model for RISC-V. +# The Sail Compiler is written in OCaml, which is an object-oriented extension of ML, which in turn +# is a functional programming language suited to formal verification. The Sail compiler is installed +# with the opam OCaml package manager. It has so many dependencies that it can be difficult to install, +# but a binary release of it should be available soon, removing the need to use opam. echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Installing/Updating Sail Compiler" @@ -338,6 +355,8 @@ opam switch create 5.1.0 || opam switch set 5.1.0 opam install sail -y echo -e "${SUCCESS_COLOR}Sail Compiler successfully installed/updated${ENDC}" +# RISC-V Sail Model (https://github.com/riscv/sail-riscv) +# The RISC-V Sail Model is the golden reference model for RISC-V. It is written in Sail (described above) echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Installing/Updating RISC-V Sail Model" @@ -359,7 +378,9 @@ else echo -e "${SUCCESS_COLOR}RISC-V Sail Model already up to date${ENDC}" fi -# riscof + +# RISCOF (https://github.com/riscv/riscof.git) +# RISCOF is a RISC-V compliance test framework that is used to run the RISC-V Arch Tests. echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Installing/Updating RISCOF" @@ -368,7 +389,9 @@ echo -e "*********************************************************************** STATUS="RISCOF" pip3 install git+https://github.com/riscv/riscof.git -# Download OSU Skywater 130 cell library + +# OSU Skywater 130 cell library (https://foss-eda-tools.googlesource.com/skywater-pdk/libs/sky130_osu_sc_t12) +# The OSU Skywater 130 cell library is a standard cell library that is used to synthesize Wally. echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Installing/Updating OSU Skywater 130 cell library" @@ -385,7 +408,10 @@ else echo -e "${SUCCESS_COLOR}OSU Skywater library already up to date${ENDC}" fi -# site-setup script + +# Download site-setup scripts +# The site-setup script is used to set up the environment for the RISC-V tools and EDA tools by setting +# the PATH and other environment variables. It also sources the Python virtual environment. echo -e "${SECTION_COLOR}\n*************************************************************************" echo -e "*************************************************************************" echo -e "Downloading Site Setup Script" @@ -396,6 +422,7 @@ cd "$RISCV" if [ ! -e "${RISCV}"/site-setup.sh ]; then wget https://raw.githubusercontent.com/openhwgroup/cvw/main/site-setup.sh wget https://raw.githubusercontent.com/openhwgroup/cvw/main/site-setup.csh + # Add necessary lines to site-setup script to activate newer version of gcc for older distros if [ "$FAMILY" = rhel ]; then echo "source /opt/rh/gcc-toolset-13/enable" >> site-setup.sh elif [ "$UBUNTU_VERSION" = 20 ]; then