From a0245622dc5b351ec78838dc654545acf415c211 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Tue, 15 Oct 2024 22:26:27 -0700 Subject: [PATCH 01/15] Make zsbl in Installation CI because it is used in standard regression tests --- .github/workflows/install.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml index dfa449526..15f41b36b 100644 --- a/.github/workflows/install.yml +++ b/.github/workflows/install.yml @@ -121,11 +121,11 @@ jobs: with: name: installation-logs-${{ matrix.name }} path: ${{ env.RISCV }}/logs/ - # Make riscof only as that is the only testsuite used by standard regression + # Make riscof and zsbl only as that is the only testsuite used by standard regression - name: make tests run: | source setup.sh - make riscof --jobs $(nproc --ignore 1) + make riscof zsbl --jobs $(nproc --ignore 1) # Only the linux-testvectors are needed, so remove the rest of the buildroot to save space - name: Remove Buildroot to Save Space run: | From 658a57a2dde99cc76d2cd04f6e9e77c285ccd20b Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Tue, 15 Oct 2024 22:44:19 -0700 Subject: [PATCH 02/15] Run lint for distros that Verilator fails sim in Installation CI --- .github/workflows/install.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml index 15f41b36b..e80bb4ef1 100644 --- a/.github/workflows/install.yml +++ b/.github/workflows/install.yml @@ -137,6 +137,11 @@ jobs: run: | source setup.sh regression-wally + - name: Lint Only (for distros with broken Verilator sim) + if: ${{ matrix.name == 'ubuntu-20.04' || matrix.name == 'rocky-8' || matrix.name == 'almalinux-8'}} + run: | + source setup.sh + lint-wally # Upload regression logs for debugging - name: Upload regression logs uses: actions/upload-artifact@v4 From 2e774aa0558a6395eb027b62dc63d298a2851f47 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Wed, 16 Oct 2024 00:47:26 -0700 Subject: [PATCH 03/15] Run wsim on broken distros --- .github/workflows/install.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml index e80bb4ef1..6ada085c7 100644 --- a/.github/workflows/install.yml +++ b/.github/workflows/install.yml @@ -142,6 +142,7 @@ jobs: run: | source setup.sh lint-wally + wsim rv32i arch32i --sim verilator # Upload regression logs for debugging - name: Upload regression logs uses: actions/upload-artifact@v4 From 2f22b236fcfd749899a86f48c6cfca438ecb9027 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Wed, 16 Oct 2024 00:48:27 -0700 Subject: [PATCH 04/15] Save wsim to log --- .github/workflows/install.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml index 6ada085c7..0c4f5d2d3 100644 --- a/.github/workflows/install.yml +++ b/.github/workflows/install.yml @@ -142,7 +142,7 @@ jobs: run: | source setup.sh lint-wally - wsim rv32i arch32i --sim verilator + wsim rv32i arch32i --sim verilator | tee $WALLY/sim/verilator/logs/rv32i_arch32i.log # Upload regression logs for debugging - name: Upload regression logs uses: actions/upload-artifact@v4 From 9d941b7f2eab23819d10ab45652cadfb9bae0754 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 00:22:51 -0700 Subject: [PATCH 05/15] Fix missing directory in installation CI --- .github/workflows/install.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/install.yml b/.github/workflows/install.yml index 0c4f5d2d3..8a7733c2e 100644 --- a/.github/workflows/install.yml +++ b/.github/workflows/install.yml @@ -137,10 +137,11 @@ jobs: run: | source setup.sh regression-wally - - name: Lint Only (for distros with broken Verilator sim) + - name: Lint + wsim Test Only (for distros with broken Verilator sim) if: ${{ matrix.name == 'ubuntu-20.04' || matrix.name == 'rocky-8' || matrix.name == 'almalinux-8'}} run: | source setup.sh + mkdir -p $WALLY/sim/verilator/logs/ lint-wally wsim rv32i arch32i --sim verilator | tee $WALLY/sim/verilator/logs/rv32i_arch32i.log # Upload regression logs for debugging From b10f46713ee86e0b73a8d3e0729c72d786efc386 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 00:27:47 -0700 Subject: [PATCH 06/15] Add installation status badge to README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index f5dfe0f47..b77024a5b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ +![Installation CI](https://github.com/jordancarlin/cvw/actions/workflows/install.yml/badge.svg?branch=main) # core-v-wally Wally is a 5-stage pipelined processor configurable to support all the standard RISC-V options, including RV32/64, A, B, C, D, F, M, Q, and Zk* extensions, virtual memory, PMP, and the various privileged modes and CSRs. It provides optional caches, branch prediction, and standard RISC-V peripherals (CLINT, PLIC, UART, GPIO). Wally is written in SystemVerilog. It passes the [RISC-V Arch Tests](https://github.com/riscv-non-isa/riscv-arch-test) and boots Linux on an FPGA. Configurations range from a minimal RV32E core to a fully featured RV64GC application processor with all of the RVA22S64 profile extensions. Wally is part of the OpenHWGroup family of robust open RISC-V cores. From 58e093c9be824344cba9014902e2b5f1dabbce77 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 00:33:28 -0700 Subject: [PATCH 07/15] Add warning regarding broken Verilator on Ubuntu 20.04 and Red Hat 8 to compatibility section of README --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index b77024a5b..a1dca4fd1 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,11 @@ This section describes the open source toolchain installation. ### Compatibility The current version of the toolchain has been tested on Ubuntu (versions 20.04 LTS, 22.04 LTS, and 24.04 LTS) and on Red Hat/Rocky/AlmaLinux (versions 8 and 9). -NOTE: Ubuntu 22.04LTS is incompatible with Synopsys Design Compiler. +> [!WARNING] +> Ubuntu 22.04LTS is incompatible with Synopsys Design Compiler. + +> [!WARNING] +> Verilator currently fails to simulate correctly on Ubuntu 20.04 LTS and Red Hat/Rocky/AlmaLinux 8. ### Overview The toolchain installation script installs the following tools: @@ -75,7 +79,6 @@ The toolchain installation script installs the following tools: - [QEMU](https://www.qemu.org/docs/master/system/target-riscv.html): emulator - [Spike](https://github.com/riscv-software-src/riscv-isa-sim): functional RISC-V model - [Verilator](https://github.com/verilator/verilator): open-source Verilog simulator - - NOTE: Verilator does not currently work reliably for simulating Wally on Ubuntu 20.04 LTS and Red Hat 8 - [RISC-V Sail Model](https://github.com/riscv/sail-riscv): golden reference model for RISC-V - [OSU Skywater 130 cell library](https://foss-eda-tools.googlesource.com/skywater-pdk/libs/sky130_osu_sc_t12): standard cell library - [RISCOF](https://github.com/riscv-software-src/riscof.git): RISC-V compliance test framework From aa4304cb6c08d744fc02bd3cfa52e1a93f5420f5 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 00:34:49 -0700 Subject: [PATCH 08/15] Document --no-buildroot flag for installation script --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a1dca4fd1..e4f7602e2 100644 --- a/README.md +++ b/README.md @@ -83,7 +83,7 @@ The toolchain installation script installs the following tools: - [OSU Skywater 130 cell library](https://foss-eda-tools.googlesource.com/skywater-pdk/libs/sky130_osu_sc_t12): standard cell library - [RISCOF](https://github.com/riscv-software-src/riscof.git): RISC-V compliance test framework -Additionally, Buildroot Linux is built for Wally and linux test-vectors are generated for simulation. See the [Linux README](linux/README.md) for more details. +Additionally, Buildroot Linux is built for Wally and linux test-vectors are generated for simulation. See the [Linux README](linux/README.md) for more details. This can be skipped using the `--no-buildroot` flag. ### Installation From 0830cbb8d151e73135203017348671c376678939 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 02:14:37 -0700 Subject: [PATCH 09/15] README formatting updates --- README.md | 204 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 119 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index e4f7602e2..631949463 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ ![Installation CI](https://github.com/jordancarlin/cvw/actions/workflows/install.yml/badge.svg?branch=main) + # core-v-wally Wally is a 5-stage pipelined processor configurable to support all the standard RISC-V options, including RV32/64, A, B, C, D, F, M, Q, and Zk* extensions, virtual memory, PMP, and the various privileged modes and CSRs. It provides optional caches, branch prediction, and standard RISC-V peripherals (CLINT, PLIC, UART, GPIO). Wally is written in SystemVerilog. It passes the [RISC-V Arch Tests](https://github.com/riscv-non-isa/riscv-arch-test) and boots Linux on an FPGA. Configurations range from a minimal RV32E core to a fully featured RV64GC application processor with all of the RVA22S64 profile extensions. Wally is part of the OpenHWGroup family of robust open RISC-V cores. @@ -15,62 +16,66 @@ Wally is presently at Technology Readiness Level 4, passing the RISC-V compatibi New users may wish to do the following setup to access the server via a GUI and use a text editor. - Git started with Git configuration and authentication: B.1 (replace with your name and email) - $ git config --global user.name "Ben Bitdiddle" - $ git config --global user.email "ben_bitdiddle@wally.edu" - $ git config --global pull.rebase false - Optional: Download and install x2go - A.1.1 - Optional: Download and install VSCode - A.4.2 - Optional: Make sure you can log into your server via x2go and via a terminal - Terminal on Mac, cmd on Windows, xterm on Linux - See A.1 about ssh -Y login from a terminal +- Git started with Git configuration and authentication: B.1 (replace with your name and email) + ```bash + $ git config --global user.name "Ben Bitdiddle" + $ git config --global user.email "ben_bitdiddle@wally.edu" + $ git config --global pull.rebase false + ``` +- Optional: Download and install x2go - A.1.1 +- Optional: Download and install VSCode - A.4.2 +- Optional: Make sure you can log into your server via x2go and via a terminal + - Terminal on Mac, cmd on Windows, xterm on Linux + - See A.1 about ssh -Y login from a terminal Then fork and clone the repo, source setup, make the tests and run regression - If you don't already have a Github account, create one - In a web browser, visit https://github.com/openhwgroup/cvw - In the upper right part of the screen, click on Fork - Create a fork, choosing the owner as your github account - and the repository as cvw. - - On the Linux computer where you will be working, log in - -Clone your fork of the repo. Change `` to your github id. - +1. If you don't already have a Github account, create one +2. In a web browser, visit https://github.com/openhwgroup/cvw +3. In the upper right part of the screen, click on Fork +4. Create a fork, choosing the owner as your github account and the repository as cvw. +5. On the Linux computer where you will be working, log in. +6. Clone your fork of the repo. Change `` to your github id. + ```bash $ git clone --recurse-submodules https://github.com//cvw $ cd cvw $ git remote add upstream https://github.com/openhwgroup/cvw + ``` -If you are installing on a new system without any tools installed, please jump to the next section, Toolchain Installation then come back here. +> [!NOTE] +> If you are installing on a new system without any tools installed, please jump to the next section, [Toolchain Installation](#toolchain-installation-and-configuration-sys-admin), then come back here. -Run the setup script to update your `PATH` and activate the python virtual environment. +7. Run the setup script to update your `PATH` and activate the python virtual environment. + ```bash $ source ./setup.sh + ``` -Add the following lines to your `.bashrc` or `.bash_profile` to run the setup script each time you log in. +8. Add the following lines to your `.bashrc` or `.bash_profile` to run the setup script each time you log in. + ```bash if [ -f ~/cvw/setup.sh ]; then source ~/cvw/setup.sh fi + ``` +9. Build the tests and run a regression simulation to prove everything is installed. Building tests may take a while. -Build the tests and run a regression simulation to prove everything is installed. Building tests will take a while. - + ```bash $ make --jobs $ regression-wally + ``` # Toolchain Installation and Configuration (Sys Admin) -This section describes the open source toolchain installation. +> This section describes the open source toolchain installation. ### Compatibility The current version of the toolchain has been tested on Ubuntu (versions 20.04 LTS, 22.04 LTS, and 24.04 LTS) and on Red Hat/Rocky/AlmaLinux (versions 8 and 9). > [!WARNING] -> Ubuntu 22.04LTS is incompatible with Synopsys Design Compiler. - -> [!WARNING] -> Verilator currently fails to simulate correctly on Ubuntu 20.04 LTS and Red Hat/Rocky/AlmaLinux 8. +> - Ubuntu 22.04LTS is incompatible with Synopsys Design Compiler. +> - Verilator currently fails to simulate correctly on Ubuntu 20.04 LTS and Red Hat/Rocky/AlmaLinux 8. ### Overview The toolchain installation script installs the following tools: @@ -89,21 +94,27 @@ Additionally, Buildroot Linux is built for Wally and linux test-vectors are gene The tools can be installed by running - $ $WALLY/bin/wally-tool-chain-install.sh - +```bash +$ $WALLY/bin/wally-tool-chain-install.sh +``` If this script is run as root or using `sudo`, it will also install all of the prerequisite packages using the system package manager. The default installation directory when run in this manner is `/opt/riscv`. If a user-level installation is desired, the script can instead be run by any user without `sudo` and the installation directory will be `~/riscv`. In this case, the prerequisite packages must first be installed by running - $ sudo $WALLY/bin/wally-package-install.sh +```bash +$ sudo $WALLY/bin/wally-package-install.sh +``` In either case, the installation directory can be overridden by passing the desired directory as the last argument to the installation script. For example, - $ sudo $WALLY/bin/wally-tool-chain-install.sh /home/riscv +```bash +$ sudo $WALLY/bin/wally-tool-chain-install.sh /home/riscv +``` See `wally-tool-chain-install.sh` for a detailed description of each component, or to issue the commands one at a time to install on the command line. -**NOTE:** The complete installation process requires ~55 GB of free space. If the `--clean` flag is passed as the first argument to the installation script then the final consumed space is only ~26 GB, but upgrading the tools requires reinstalling from scratch. +> [!NOTE] +> The complete installation process requires ~55 GB of free space. If the `--clean` flag is passed to the installation script then the final consumed space is only ~26 GB, but upgrading the tools will reinstall everything from scratch. ### Configuration `$WALLY/setup.sh` sources `$RISCV/site-setup.sh`. If the toolchain was installed in either of the default locations (`/opt/riscv` or `~/riscv`), `$RISCV` will automatically be set to the correct path when `setup.sh` is run. If a custom installation directory was used, then `$WALLY/setup.sh` must be modified to set the correct path. @@ -112,12 +123,13 @@ See `wally-tool-chain-install.sh` for a detailed description of each component, Change the following lines to point to the path and license server for your Siemens Questa and Synopsys Design Compiler and VCS installations and license servers. If you only have Questa or VCS, you can still simulate but cannot run logic synthesis. If Questa, VSC, or Design Compiler are already setup on this system then don't set these variables. - export MGLS_LICENSE_FILE=.. # Change this to your Siemens license server - export SNPSLMD_LICENSE_FILE=.. # Change this to your Synopsys license server - export QUESTA_HOME=.. # Change this for your path to Questa - export DC_HOME=.. # Change this for your path to Synopsys Design Compiler - export VCS_HOME=.. # Change this for your path to Synopsys VCS - +```bash +export MGLS_LICENSE_FILE=.. # Change this to your Siemens license server +export SNPSLMD_LICENSE_FILE=.. # Change this to your Synopsys license server +export QUESTA_HOME=.. # Change this for your path to Questa +export DC_HOME=.. # Change this for your path to Synopsys Design Compiler +export VCS_HOME=.. # Change this for your path to Synopsys VCS +``` # Installing EDA Tools @@ -131,39 +143,48 @@ Although most EDA tools are Linux-friendly, they tend to have issues when not in ### Siemens Questa -Siemens Questa simulates behavioral, RTL and gate-level HDL. To install Siemens Questa first go to a web browser and navigate to -https://eda.sw.siemens.com/en-US/ic/questa/simulation/advanced-simulator/. Click Sign In and log in with your credentials and the product can easily be downloaded and installed. Some Windows-based installations also require gcc libraries that are typically provided as a compressed zip download through Siemens. +Siemens Questa simulates behavioral, RTL and gate-level HDL. To install Siemens Questa first go to a web browser and navigate to https://eda.sw.siemens.com/en-US/ic/questa/simulation/advanced-simulator/. Click Sign In and log in with your credentials and the product can easily be downloaded and installed. Some Windows-based installations also require gcc libraries that are typically provided as a compressed zip download through Siemens. ### Synopsys Design Compiler (DC) -Many commercial synthesis and place and route tools require a common installer. These installers are provided by the EDA vendor and Synopsys has one called Synopsys Installer. To use Synopsys Installer, you will need to acquire a license through Synopsys that is typically Called Synopsys Common Licensing (SCL). Both the Synopsys Installer, license key file, and Design Compiler can all be downloaded through Synopsys Solvnet. First open a web browser, log into Synsopsy Solvnet, and download the installer and Design Compiler installation files. Then, install the Installer +Many commercial synthesis and place and route tools require a common installer. These installers are provided by the EDA vendor and Synopsys has one called Synopsys Installer. To use Synopsys Installer, you will need to acquire a license through Synopsys that is typically Called Synopsys Common Licensing (SCL). Both the Synopsys Installer, license key file, and Design Compiler can all be downloaded through Synopsys Solvnet. First open a web browser, log into Synsopsy Solvnet, and download the installer and Design Compiler installation files. Then, install the Installer. - $ firefox & -Navigate to https://solvnet.synopsys.com -Log in with your institution’s username and password -Click on Downloads, then scroll down to Synopsys Installer -Select the latest version (currently 5.4). Click Download Here, agree, -Click on SynopsysInstaller_v5.4.run -Return to downloads and also get Design Compiler (synthesis) latest version, and any others you want. - Click on all parts and the .spf file, then click Download Files near the top -move the SynopsysInstaller into /cad/synopsys/Installer_5.4 with 755 permission for cad, -move other files into /cad/synopsys/downloads and work as user cad from here on +```bash +$ firefox & +``` - $ cd /cad/synopsys/installer_5.4 - $ ./SynopsysInstaller_v5.4.run - Accept default installation directory - $ ./installer - Enter source path as /cad/synopsys/downloads, and installation path as /cad/synopsys - When prompted, enter your site ID - Follow prompts +- Navigate to https://solvnet.synopsys.com +- Log in with your institution’s username and password +- Click on Downloads, then scroll down to Synopsys Installer +- Select the latest version (currently 5.4). Click Download Here, agree, +- Click on SynopsysInstaller_v5.4.run +- Return to downloads and also get Design Compiler (synthesis) latest version, and any others you want. +- Click on all parts and the .spf file, then click Download Files near the top +- Move the SynopsysInstaller into `/cad/synopsys/Installer_5.4` with 755 permission for cad, +- move other files into `/cad/synopsys/downloads` and work as user cad from here on + +```bash +$ cd /cad/synopsys/installer_5.4 +$ ./SynopsysInstaller_v5.4.run +``` +- Accept default installation directory +```bash +$ ./installer +``` +- Enter source path as `/cad/synopsys/downloads`, and installation path as `/cad/synopsys` +- When prompted, enter your site ID +- Follow prompts Installer can be utilized in graphical or text-based modes. It is far easier to use the text-based installation tool. To install DC, navigate to the location where your downloaded DC files are and type installer. You should be prompted with questions related to where you wish to have your files installed. -The Synopsys Installer automatically installs all downloaded product files into a single top-level target directory. You do not need to specify the installation directory for each product. For example, if you specify /import/programs/synopsys as the target directory, your installation directory structure might look like this after installation: +The Synopsys Installer automatically installs all downloaded product files into a single top-level target directory. You do not need to specify the installation directory for each product. For example, if you specify `/import/programs/synopsys` as the target directory, your installation directory structure might look like this after installation: - /import/programs/synopsys/syn/S-2021.06-SP1 +```bash +/import/programs/synopsys/syn/S-2021.06-SP1 +``` -Note: Although most parts of Wally, including the Questa simulator, will work on most modern Linux platforms, as of 2022, the Synopsys CAD tools for SoC design are only supported on RedHat Enterprise Linux 7.4 or 8 or SUSE Linux Enterprise Server (SLES) 12 or 15. Moreover, the RISC-V formal specification (sail-riscv) does not build gracefully on RHEL7. +> [!Note] +> Although most parts of Wally, including the Questa simulator, will work on most modern Linux platforms, as of 2022, the Synopsys CAD tools for SoC design are only supported on RedHat Enterprise Linux 7.4 or 8 or SUSE Linux Enterprise Server (SLES) 12 or 15. Moreover, the RISC-V formal specification (sail-riscv) does not build gracefully on RHEL7. The Verilog simulation has been tested with Siemens Questa/ModelSim. This package is available to universities worldwide as part of the Design Verification Bundle through the Siemens Academic Partner Program members for $990/year. @@ -178,7 +199,7 @@ If you want to add a cronjob you can do the following: 1) Set up the email client `mutt` for your distribution 2) Enter `crontab -e` into a terminal 3) add this code to test building CVW and then running `regression-wally --nightly` at 9:30 PM each day -``` +```bash 30 21 * * * bash -l -c "source ~/PATH/TO/CVW/setup.sh; PATH_TO_CVW/cvw/bin/wrapper_nightly_runs.sh --path {PATH_TO_TEST_LOCATION} --target all --tests nightly --send_email harris@hmc.edu,kaitlin.verilog@gmail.com" ``` @@ -186,44 +207,57 @@ If you want to add a cronjob you can do the following: wsim runs one of multiple simulators, Questa, VCS, or Verilator using a specific configuration and either a suite of tests or a specific elf file. The general syntax is -wsim [--options] +`wsim [--options]` Parameters and options: - -h, --help show this help message and exit - --sim {questa,verilator,vcs}, -s {questa,verilator,vcs} Simulator - --tb {testbench,testbench_fp}, -t {testbench,testbench_fp} Testbench - --gui, -g Simulate with GUI - --coverage, -c Code & Functional Coverage - --fcov, -f Code & Functional Coverage - --args ARGS, -a ARGS Optional arguments passed to simulator via $value$plusargs - --vcd, -v Generate testbench.vcd - --lockstep, -l Run ImperasDV lock, step, and compare. - --locksteplog LOCKSTEPLOG, -b LOCKSTEPLOG Retired instruction number to be begin logging. - --covlog COVLOG, -d COVLOG Log coverage after n instructions. - --elfext ELFEXT, -e ELFEXT When searching for elf files only includes ones which end in this extension +``` +-h, --help show this help message and exit +--sim {questa,verilator,vcs}, -s {questa,verilator,vcs} Simulator +--tb {testbench,testbench_fp}, -t {testbench,testbench_fp} Testbench +--gui, -g Simulate with GUI +--coverage, -c Code & Functional Coverage +--fcov, -f Code & Functional Coverage +--args ARGS, -a ARGS Optional arguments passed to simulator via $value$plusargs +--vcd, -v Generate testbench.vcd +--lockstep, -l Run ImperasDV lock, step, and compare. +--locksteplog LOCKSTEPLOG, -b LOCKSTEPLOG Retired instruction number to be begin logging. +--covlog COVLOG, -d COVLOG Log coverage after n instructions. +--elfext ELFEXT, -e ELFEXT When searching for elf files only includes ones which end in this extension +``` Run basic test with questa - wsim rv64gc arch64i +```bash +wsim rv64gc arch64i +``` Run Questa with gui - wsim rv64gc wally64priv --gui +```bash +wsim rv64gc wally64priv --gui +``` -Run lockstep against ImperasDV with a single elf file in the --gui. Lockstep requires single elf. +Run lockstep against ImperasDV with a single elf file in the gui. Lockstep requires single elf. - wsim rv64gc ../../tests/riscof/work/riscv-arch-test/rv64i_m/I/src/add-01.S/ref/ref.elf --lockstep --gui +```bash +wsim rv64gc ../../tests/riscof/work/riscv-arch-test/rv64i_m/I/src/add-01.S/ref/ref.elf --lockstep --gui +``` Run lockstep against ImperasDV with a single elf file. Compute coverage. - wsim rv64gc ../../tests/riscof/work/riscv-arch-test/rv64i_m/I/src/add-01.S/ref/ref.elf --lockstep --coverage +```bash +wsim rv64gc ../../tests/riscof/work/riscv-arch-test/rv64i_m/I/src/add-01.S/ref/ref.elf --lockstep --coverage +``` Run lockstep against ImperasDV with directory file. - wsim rv64gc ../../tests/riscof/work/riscv-arch-test/rv64i_m/I/src/ --lockstep +```bash +wsim rv64gc ../../tests/riscof/work/riscv-arch-test/rv64i_m/I/src/ --lockstep +``` Run lockstep against ImperasDV with directory file and specify specific extension. - wsim rv64gc ../../tests/riscof/work/riscv-arch-test/rv64i_m/I/src/ --lockstep --elfext ref.elf - +```bash +wsim rv64gc ../../tests/riscof/work/riscv-arch-test/rv64i_m/I/src/ --lockstep --elfext ref.elf +``` From 336a178da0429c43be8904f45b5a49fe2c253e5b Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 02:15:45 -0700 Subject: [PATCH 10/15] Fix appendix refs --- README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 631949463..62a59d5a2 100644 --- a/README.md +++ b/README.md @@ -16,17 +16,17 @@ Wally is presently at Technology Readiness Level 4, passing the RISC-V compatibi New users may wish to do the following setup to access the server via a GUI and use a text editor. -- Git started with Git configuration and authentication: B.1 (replace with your name and email) +- Git started with Git configuration and authentication: C.1 (replace with your name and email) ```bash $ git config --global user.name "Ben Bitdiddle" $ git config --global user.email "ben_bitdiddle@wally.edu" $ git config --global pull.rebase false ``` -- Optional: Download and install x2go - A.1.1 -- Optional: Download and install VSCode - A.4.2 +- Optional: Download and install x2go - B.1.1 +- Optional: Download and install VSCode - B.4.2 - Optional: Make sure you can log into your server via x2go and via a terminal - Terminal on Mac, cmd on Windows, xterm on Linux - - See A.1 about ssh -Y login from a terminal + - See B.1 about ssh -Y login from a terminal Then fork and clone the repo, source setup, make the tests and run regression From 05d86fc6cee21dfbfd20684d24bb9dd5cfac4a7f Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 15:08:32 -0700 Subject: [PATCH 11/15] Update fpga README formatting --- fpga/README.md | 52 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 33 insertions(+), 19 deletions(-) diff --git a/fpga/README.md b/fpga/README.md index 236bc7ddb..249df565b 100644 --- a/fpga/README.md +++ b/fpga/README.md @@ -6,29 +6,39 @@ Wally supports the following boards # Quick Start -## build FPGA +## Build FPGA -`cd generator -make ` +```bash +cd generator +make +``` -example -`make vcu108` +Example: +```bash +make vcu108 +``` ## Make flash card image -ls /dev/sd* or ls /dev/mmc* to see which flash card devices you have. -Insert the flash card into the reader and ls /dev/sd* or /dev/mmc* again. The new device is the one you want to use. Make sure you select the root device (i.e. /dev/sdb) not the partition (i.e. /dev/sdb1). +`ls /dev/sd*` or `ls /dev/mmc*` to see which flash card devices you have. +Insert the flash card into the reader and `ls /dev/sd*` or `/dev/mmc*` again. The new device is the one you want to use. Make sure you select the root device (i.e. `/dev/sdb`) not the partition (i.e. `/dev/sdb1`). -`cd $WALLY/linux/sd-card` +```bash +cd $WALLY/linux/sd-card +``` This following script requires root. -`./flash-sd.sh -b -d ` +```bash +./flash-sd.sh -b -d +``` -example with vcu108, buildroot installed to /opt/riscv/buildroot, and the flash card is device /dev/sdc +Example with vcu108, buildroot installed to `/opt/riscv/buildroot`, and the flash card is device `/dev/sdc` -`./flash-sd.sh -b /opt/riscv/buildroot -d /opt/riscv/buildroot/output/images/wally-vcu108.dtb /dev/sdc` +```bash +./flash-sd.sh -b /opt/riscv/buildroot -d /opt/riscv/buildroot/output/images/wally-vcu108.dtb /dev/sdc +``` -Wait until the the script completes then remove the car. +Wait until the the script completes then remove the card. ## FPGA setup @@ -36,22 +46,26 @@ For the Arty A7 insert the PMOD daughter board into the right most slot and inse For the VCU108 and VCU118 boards insert the PMOD daughter board into the only PMOD slot on the right side of the boards. -Power on the boards. Arty A7 just plug in the USB connector. For the VCU boards make sure the power supply is connected and the two usb cables are connected. Flip on the switch. +Power on the boards. For Arty A7 just plug in the USB connector. For the VCU boards make sure the power supply is connected and the two usb cables are connected. Flip on the switch. The VCU118's on board UART converter does not work. Use a spark fun FTDI usb to UART adapter and plug into the mail PMOD on the right side of the board. Also the level sifters on the VCU118 do not work correctly with the digilent sd PMOD board. We have a custom board which works instead. -`cd $WALLY/fpga/generator -vivado &` +```bash +cd $WALLY/fpga/generator +vivado & +``` -open the design in the current directory WallyFPGA.xpr. +Open the design in the current directory `WallyFPGA.xpr`. Then click "Open Target" under "PROGRAM AND DEBUG". Then Program the device. ## Connect to UART -In another terminal ls /dev/ttyUSB*. One of these devices will be the UART connected to Wally. You may have to experiment by the running the following command multiple times. +In another terminal `ls /dev/ttyUSB*`. One of these devices will be the UART connected to Wally. You may have to experiment by the running the following command multiple times. -`screen /dev/ttyUSB1 115200` +```bash +screen /dev/ttyUSB1 115200 +``` -Swap out the USB1 for USB0 or USB1 as needed. +Swap out the `USB1` for `USB0` or `USB1` as needed. From c69f83224d7e87cbd072f5ab6183faa8de9118e6 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 15:18:04 -0700 Subject: [PATCH 12/15] Update SynthDC README formatting --- synthDC/README.md | 85 +++++++++++++++++++++++------------------------ 1 file changed, 42 insertions(+), 43 deletions(-) diff --git a/synthDC/README.md b/synthDC/README.md index 30a98a76b..f0177d369 100644 --- a/synthDC/README.md +++ b/synthDC/README.md @@ -1,42 +1,39 @@ -Synthesis for RISC-V Microprocessor System-on-Chip Design +# Synthesis for RISC-V Microprocessor System-on-Chip Design This subdirectory contains synthesis scripts for use with Synopsys (snps) Design Compiler (DC). Synthesis commands are found in -scripts/synth.tcl. +`scripts/synth.tcl`. -Example Usage +## Example Usage +```bash make synth DESIGN=wallypipelinedcore FREQ=500 CONFIG=rv32e +``` -environment variables +## Environment Variables -DESIGN - Design provides the name of the output log. Default is synth. +- `DESIGN` + - Design provides the name of the output log. Default is synth. +- `FREQ` + - Frequency in MHz. Default is 500 +- `CONFIG` + - The Wally configuration file. The default is rv32e. + - Examples: rv32e, rv64gc, rv32gc +- `TECH` + - The target standard cell library. The default is sky130. + - Options: + - sky90: skywater 90nm TT 25C + - sky130: skywater 130nm TT 25C +- `SAIFPOWER` + - Controls if power analysis is driven by switching factor or RTL modelsim simulation. When enabled requires a saif file named power.saif. The default is 0. + - Options: + - 0: switching factor power analysis + - 1: RTL simulation driven power analysis. -FREQ - Frequency in MHz. Default is 500 - -CONFIG - The Wally configuration file. The default is rv32e. - Examples: rv32e, rv64gc, rv32gc - -TECH - The target standard cell library. The default is sky130. - sky90: skywater 90nm TT 25C - sky130: skywater 130nm TT 25C - -SAIFPOWER - Controls if power analysis is driven by switching factor or - RTL modelsim simulation. When enabled requires a saif file - named power.saif. The default is 0. - 0: switching factor power analysis - 1: RTL simulation driven power analysis. - ------ -Extra Tool (PPA) +## Extra Tool (PPA) To run ppa analysis that hones into target frequency, you can type: -python3 ppa/ppaSynth.py from the synthDC directory. This runs a sweep -across all modules listed at the bottom of the ppaSynth.py file. +`python3 ppa/ppaSynth.py` from the synthDC directory. This runs a sweep +across all modules listed at the bottom of the `ppaSynth.py` file. Two options for running the sweep. The first run runs all modules for all techs around a given frequency (i.e., freqs). The second option @@ -44,19 +41,21 @@ will run all designs for the specific module based on bestSynths.csv values. Since the second option is 2nd, it has priority. If the second set of values is commented out, it will run all widths. -WARNING: The first option may runs lots of runs that could expend all -the licenses available for a license. Therefore, care must be taken -to be sure that enough licenses are available for this first option. +**WARNING:** The first option may runs lots of runs that could expend all the licenses available for a license. Therefore, care must be taken to be sure that enough licenses are available for this first option. -##### Run specific syntheses - widths = [8, 16, 32, 64, 128] - modules = ['mul', 'adder', 'shifter', 'flop', 'comparator', 'binencoder', 'csa', 'mux2', 'mux4', 'mux8'] - techs = ['sky90', 'sky130', 'tsmc28', 'tsmc28psyn'] - freqs = [5000] - synthsToRun = allCombos(widths, modules, techs, freqs) +### Run specific syntheses +```python +widths = [8, 16, 32, 64, 128] +modules = ['mul', 'adder', 'shifter', 'flop', 'comparator', 'binencoder', 'csa', 'mux2', 'mux4', 'mux8'] +techs = ['sky90', 'sky130', 'tsmc28', 'tsmc28psyn'] +freqs = [5000] +synthsToRun = allCombos(widths, modules, techs, freqs) +``` -##### Run a sweep based on best delay found in existing syntheses - module = 'adder' - width = 32 - tech = 'tsmc28psyn' - synthsToRun = freqSweep(module, width, tech) \ No newline at end of file +### Run a sweep based on best delay found in existing syntheses +```python +module = 'adder' +width = 32 +tech = 'tsmc28psyn' +synthsToRun = freqSweep(module, width, tech) +``` From 1e204f3c1223889dc19a4315cdfae8a30104d662 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 15:21:37 -0700 Subject: [PATCH 13/15] Update testfloat README formatting --- tests/fp/README.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/tests/fp/README.md b/tests/fp/README.md index 440f5eea8..c4cd2b97b 100644 --- a/tests/fp/README.md +++ b/tests/fp/README.md @@ -1,7 +1,7 @@ -james.stine@okstate.edu 14 Jan 2022 +james.stine@okstate.edu 14 Jan 2022\ jcarlin@hmc.edu Sept 2024 -## TestFloat for CVW +# TestFloat for CVW The CVW floating point unit is tested using testvectors from the Berkeley TestFloat suite, written originally by John Hauser. @@ -9,7 +9,7 @@ TestFloat and SoftFloat can be found as submodules in the addins directory, and - TestFloat: https://github.com/ucb-bar/berkeley-testfloat-3 - SoftFloat: https://github.com/ucb-bar/berkeley-softfloat-3 -### Compiling SoftFloat/TestFloat and Generating Testvectors +## Compiling SoftFloat/TestFloat and Generating Testvectors The entire testvector generation process can be performed by running make in this directory. @@ -17,7 +17,7 @@ The entire testvector generation process can be performed by running make in thi make --jobs ``` -This compiles SoftFloat for an x86_64 environment in its build/Linux-x86_64-GCC directory using the `SPECIALIZE_TYPE=RISCV` flag to get RISC-V behavior. TestFloat is then compiled in its build/Linux-x86_64-GCC directory using this SoftFloat library. +This compiles SoftFloat for an x86_64 environment in its `build/Linux-x86_64-GCC` directory using the `SPECIALIZE_TYPE=RISCV` flag to get RISC-V behavior. TestFloat is then compiled in its `build/Linux-x86_64-GCC` directory using this SoftFloat library. The Makefile in the vectors subdirectory of this directory is then called to generate testvectors for each rounding mode and operation. It also puts an underscore between each vector instead of a space to allow SystemVerilog `$readmemh` to read correctly. @@ -25,7 +25,7 @@ Testvectors for the combined integer floating-point divider are also generated. Although not needed, a `case.sh` script is included to change the case of the hex output. This is for those that do not like to see hexadecimal capitalized :P. -### Running TestFloat Vectors on Wally +## Running TestFloat Vectors on Wally TestFloat is run using the standard Wally simulation commands. @@ -40,15 +40,15 @@ wsim --tb testbench_fp ``` The choices for `` are as follows: ->cvtint - test integer conversion unit (fcvtint) -cvtfp - test floating-point conversion unit (fcvtfp) -cmp - test comparison unit's LT, LE, EQ opperations (fcmp) -add - test addition -fma - test fma -mul - test mult with fma -sub - test subtraction -div - test division -sqrt - test square root + cvtint - test integer conversion unit (fcvtint) + cvtfp - test floating-point conversion unit (fcvtfp) + cmp - test comparison unit's LT, LE, EQ opperations (fcmp) + add - test addition + fma - test fma + mul - test mult with fma + sub - test subtraction + div - test division + sqrt - test square root Any config that includes floating point support can be used. Each test will test all its vectors for all precisions supported by the given config. From 6d00ae98ea93aaa0cf066addede417bcf222be69 Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 15:29:39 -0700 Subject: [PATCH 14/15] Update linux README formatting --- linux/README.MD | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/linux/README.MD b/linux/README.MD index ba7fb8dd4..7eb50dd9f 100644 --- a/linux/README.MD +++ b/linux/README.MD @@ -14,21 +14,27 @@ In order to generate the Linux and boot stage binaries compatible with Wally, Bu To set up a Buildroot directory, configuration files for Buildroot, Linux, and Busybox must be copied into the correct locations inside the main Buildroot directory. Buildroot and device tree binaries must be generated as well. This can all be done automatically using the Makefile inside Wally's Linux subdirectory (this one). To install a new buildroot directory, build the Buildroot binaries, generate the device tree binaries, generate test-vectors for simulation, and install the buildroot package needed to build the SD card driver for Linux, run: - $ make +```bash +$ make +``` This installs to the `$RISCV` directory. Buildroot itself is installed to `$RISCV/buildroot` and the test-vectors are installed to `$RISCV/linux-testvectors`. Optionally, you can override the `BUILDROOT` variable to install a different buildroot source directory. - $ make install BUILDROOT=path/to/buildroot +``` +$ make install BUILDROOT= +``` ## Generating Device Tree Binaries -The device tree files for the various FPGA's Wally supports, as well as QEMU's device tree for the virt machine, are located in the `./devicetree` subdirectory. These device tree files are necessary for the boot process. +The device tree files for the various FPGAs Wally supports, as well as QEMU's device tree for the virt machine, are located in the `./devicetree` subdirectory. These device tree files are necessary for the boot process. They are built automatically using the main `make` command. To build the device tree binaries (.dtb) from the device tree sources (.dts) separately, we can build all of them at once using: - $ make generate #optionally override BUILDROOT +```bash +$ make generate # optionally override BUILDROOT +``` The .dts files will end up in the `/output/images` folder of your chosen buildroot directory. @@ -38,23 +44,30 @@ By using the `riscv64-unknown-elf-objdump` utility, we can disassemble the binar The disassembled binaries are built automatically using the main `make` command. To create the disassembled binaries separately, run: - $ make disassemble #optionally override BUILDROOT +```bash +$ make disassemble # optionally override BUILDROOT +``` You'll find the resulting disassembled files in `/output/images/disassembly`. ## Generate Memory Files for Linux Boot -Running a linux boot simulation uses a preloaded bootrom and ram memory. We use QEMU to generate these preloaded memory files. The files are output to $RISCV/linux-testvectors. The memory files are generated automatically when using the main `make` command. Alternatively, they can be generated by running +Running a linux boot simulation uses a preloaded bootrom and ram memory. We use QEMU to generate these preloaded memory files. The files are output to `$RISCV/linux-testvectors`. The memory files are generated automatically when using the main `make` command. Alternatively, they can be generated by running - make dumptvs +```bash +$ make dumptvs +``` ## Creating a Bootable SD Card To flash a bootable sd card for Wally's bootloader, use the `flash-sd.sh` script located in `/linux/sdcard`. The script allows you to specify which buildroot directory you would like to use and to specify the device tree. By default it is set up for the default location of buildroot in `$RISCV` and uses the vcu108 device tree. To use the script with your own buildroot directory and device tree, type: - $ cd sdcard - $ ./flash-sd.sh -b -d +```bash +$ cd sdcard +$ ./flash-sd.sh -b -d +``` for example - - $ ./flash-sd.sh -b ~/repos/buildroot -d wally-vcu118.dtb /dev/sdb +```bash +$ ./flash-sd.sh -b ~/repos/buildroot -d wally-vcu118.dtb /dev/sdb +``` From 34ccd5a3912db43b84cdf4c5deb5d22d6612a24f Mon Sep 17 00:00:00 2001 From: Jordan Carlin Date: Thu, 17 Oct 2024 15:38:58 -0700 Subject: [PATCH 15/15] Update and combine Linux READMEs --- docs/README-linux.md | 41 ----------------------------------------- linux/README.MD | 6 ++++-- 2 files changed, 4 insertions(+), 43 deletions(-) delete mode 100644 docs/README-linux.md diff --git a/docs/README-linux.md b/docs/README-linux.md deleted file mode 100644 index 63a3f5e2b..000000000 --- a/docs/README-linux.md +++ /dev/null @@ -1,41 +0,0 @@ -### Cross-Compile Buildroot Linux - -Building Linux is only necessary for exploring the boot process in Chapter 17. Building and generating a trace is a time-consuming operation that could be skipped for now; you can return to this section later if you are interested in the Linux details. - -Buildroot depends on configuration files in riscv-wally, so the cad user must install Wally first according to the instructions in Section 2.2.2. However, don’t source ~/wally-riscv/setup.sh because it will set LD_LIBRARY_PATH in a way to cause make to fail on buildroot. - -To configure and build Buildroot: - - $ cd $RISCV - $ export WALLY=~/riscv-wally # make sure you haven’t sourced ~/riscv-wally/setup.sh by now - $ git clone https://github.com/buildroot/buildroot.git - $ cd buildroot - $ git checkout 2021.05 # last tested working version - $ cp -r $WALLY/linux/buildroot-config-src/wally ./board - $ cp ./board/wally/main.config .config - $ make --jobs - -To generate disassembly files and the device tree, run another make script. Note that you can expect some warnings about phandle references while running dtc on wally-virt.dtb. -Depending on your system configuration this makefile may need a bit of tweaking. It places the output buildroot images in $RISCV/linux-testvectors and the buildroot object dumps in $RISCV/buildroot/output/images/disassembly. If these directories are owned by root then the makefile will likely fail. You can either change the makefile's target directories or change temporarily change the owner of the two directories. - -$ source ~/riscv-wally/setup.sh -$ cd $WALLY/linux/buildroot-scripts -$ make all - -Note: When the make tasks complete, you’ll find source code in $RISCV/buildroot/output/build and the executables in $RISCV/buildroot/output/images. - -### Generate load images for linux boot - -The Questa linux boot uses preloaded bootram and ram memory. We use QEMU to generate these preloaded memory files. Files output in $RISCV/linux-testvectors - - cd cvw/linux/testvector-generation - ./genInitMem.sh - -This may require changing file permissions to the linux-testvectors directory. - -### Generate QEMU linux trace - -The linux testbench can instruction by instruction compare Wally's committed instructions against QEMU. To do this QEMU outputs a log file consisting of all instructions executed. Interrupts are handled by forcing the testbench to generate an interrupt at the same cycle as in QEMU. Generating this trace will take more than 24 hours. - - cd cvw/linux/testvector-generation - ./genTrace.sh diff --git a/linux/README.MD b/linux/README.MD index 7eb50dd9f..b7a031ce6 100644 --- a/linux/README.MD +++ b/linux/README.MD @@ -12,7 +12,9 @@ In order to generate the Linux and boot stage binaries compatible with Wally, Buildroot is used for cross-compilation. -To set up a Buildroot directory, configuration files for Buildroot, Linux, and Busybox must be copied into the correct locations inside the main Buildroot directory. Buildroot and device tree binaries must be generated as well. This can all be done automatically using the Makefile inside Wally's Linux subdirectory (this one). To install a new buildroot directory, build the Buildroot binaries, generate the device tree binaries, generate test-vectors for simulation, and install the buildroot package needed to build the SD card driver for Linux, run: +To set up a Buildroot directory, configuration files for Buildroot, Linux, and Busybox must be copied into the correct locations inside the main Buildroot directory. Buildroot and device tree binaries must be generated as well. + +This can all be done automatically using the Makefile inside Wally's Linux subdirectory (this one). The main Wally installation script (`bin/wally-tool-chain-install.sh`) runs this by default, so buildroot is likely already setup. Otherwise, to install a new buildroot directory, build the Buildroot binaries, generate the device tree binaries, and generate testvectors for simulation run: ```bash $ make @@ -22,7 +24,7 @@ This installs to the `$RISCV` directory. Buildroot itself is installed to `$RISC Optionally, you can override the `BUILDROOT` variable to install a different buildroot source directory. -``` +```bash $ make install BUILDROOT= ```