Update installation script comments

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 "*************************************************************************"

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

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
+# Set installation directory based on execution privileges
-# /opt/riscv. Otherwise, it is set to ~/riscv. This value can be overridden with an argument passed to the script.
+# 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
-    source /opt/rh/gcc-toolset-13/enable  # activate gcc13
-    # Newer version of gcc needed for Ubuntu 20.04 for Verilator
 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 # Meson is needed to build glib
-        pip install -U meson
         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
+# Spike is a reference model for RISC-V. It is a functional simulator that can be used to run RISC-V programs.
-# with the GCC installation.
 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