Quasar RISC-V Core 2.0 from Lampro Mellon

This repository contains the Quasar Core design in CHISEL.

License

By contributing to this project, you agree that your contribution is governed by Apache-2.0.
Files under the tools directory may be available under a different license. Please review individual file for details.

Background

Quasar is a Chiselified version of EL2 SweRV RISC-V Core.

Directory Structure

├── configs                                 # Configurations dir
├── design 
│   ├── project 
│       ├── project 
│       └── target
│   ├── snapshots 
│       └── default                         # Where generated configuration files are created
│   ├── src 
│       ├── main                            
│           ├── resources                   
│               └── vsrc                    # Blackbox files dir
│           └── scala                       # Design root dir
│               ├── dbg                     # Debugger
│               ├── dec                     # Decode, Registers and Exceptions 
│               ├── dmi                     # DMI block
│               ├── exu                     # EXU (ALU/MUL/DIV)
│               ├── ifu                     # Fetch & Branch Prediction
│               ├── include                 # Bundles file
│               ├── lib                     # Bridges and Library
│               └── lsu                     # Load/Store    
│       └── test 
│   ├── target 
│   └── test_run_dir    
├── doc                                     # PPA Report
├── generated_rtl                           # Quasar wrapper
├── testbench 
│   ├── asm                                 # Example assembly files
│   ├── hex                                 # Canned demo hex files   
│   └── tests                               # Example tests
├── tools                                   # Scripts/Makefiles
├── tracer_logs                             # generated log files
└── verif                                     
    ├── LEC 
        ├── formality_work 
            └── formality_log               # LEC log files
        └── setup_files                     # user_match files
    └── sim                                 # Simulation log/dump files

Dependencies

• Verilator (4.102 or later) must be installed on the system if running with verilator.
• Vcs must be installed on the system if running with vcs.
• RISCV tool chain (based on gcc version 8.3 or higher) must be installed so that it can be used to prepare RISCV binaries to run.
• Sbt (1.3.13 or later) must be installed on the system.

Quickstart guide

1. Clone the repository
2. Setup RV_ROOT to point to the path in your local filesystem
3. Determine your configuration {optional}
4. Run make with $RV_ROOT/tools/Makefile

Release Notes for this version

Please see release-notes for changes and bug fixes in this version of Quasar.

Configurations

Quasar can be configured by running the script:

    $RV_ROOT/configs/quasar.config 

For detailed help options.

    $RV_ROOT/configs/quasar.config -h 

For example, to build with a DCCM of size 64Kb:

    $RV_ROOT/configs/quasar.config -dccm_size=64  

This will update the default snapshot in $RV_ROOT/design/snapshots/default/ with parameters for a 64K DCCM.

Add -snapshot=dccm64, for example, if you wish to name your build snapshot dccm64 and refer to it during the build.

There are 4 predefined target configurations: default, default_ahb, typical_pd and high_perf that can be selected via the -target=name option to quasar.config.

This script derives the following consistent set of include files :

$RV_ROOT/design/snapshots/default
    ├── common_defines.vh                       # `defines for testbench or design
    ├── defines.h                               # defines for C/assembly headers
    ├── param.vh                            	# Design parameters
    ├── pdef.vh                             	# Parameter structure
    ├── pd_defines.vh                           # `defines for physical design
    ├── perl_configs.pl                         # Perl %configs hash for scripting
    ├── pic_map_auto.h                          # PIC memory map based on configure size
    ├── whisper.json                            # JSON file for swerv-iss 
    └── link.ld                                 # default linker control file

1. Generate scala parameter

    make -f $RV_ROOT/tools/Makefile conf

This script will run quasar.config and derives the include file:

$RV_ROOT/design/src/main/scala/lib
    └── param.scala                             # Scala design parameters

Running RTL Simulation

while in a work directory:

1. Set the RV_ROOT environment variable to the root of the Quasar directory structure.

Example for bash shell:

    export RV_ROOT=$(pwd)  

Example for csh or its derivatives:

    setenv RV_ROOT /path/to/QUASAR

2. Create your specific configuration

(Skip if default is sufficient)
(Name your snapshot to distinguish it from the default. Without an explicit name, it will update/override the default snapshot). For example, if mybuild is the name for the snapshot:

set BUILD_PATH environment variable:

    setenv BUILD_PATH snapshots/mybuild

    $RV_ROOT/configs/quasar.config [configuration options..] -snapshot=mybuild

Snapshots are placed in $BUILD_PATH directory.

3. Run sbt

    make -f $RV_ROOT/tools/Makefile sbt_

This command will generate the Quasar wrapper in system verilog of Quasar chisel, in the generated_rtl directory and runs the reset_script.py

• In the reset_script we do a post verilog-generation changes, these changes are as follows:

  • Replace posedge reset with negedge reset
  • Replace if (reset) with if (~reset)

4. Running a simple Hello World program (verilator)

    make -f $RV_ROOT/tools/Makefile

This command will build a verilator model of Quasar with AXI bus, and execute a short sequence of instructions that writes out "HELLO WORLD" to the bus.

The simulation produces output on the screen like:

VerilatorTB: Start of sim

----------------------------------
 Hello World from QUASAR @LMDC !!
----------------------------------
TEST_PASSED

Finished : minstret = 437, mcycle = 922
See "exec.log" for execution trace with register updates..

The simulation generates following files in $RV_ROOT/verif/sim:

console.log contains what the cpu writes to the console address of 0xd0580000.
exec.log shows instruction trace with GPR updates.
trace_port.csv contains a log of the trace port.

Other log files are dec.log, exu.log, ifu.log, lsu.log and pic.log, generates in $RV_ROOT/tracer_logs.

When debug=1 is provided, a vcd file sim.vcd is created and can be browsed by gtkwave or similar waveform viewers.

You can re-execute simulation using:

    make -f $RV_ROOT/tools/Makefile verilator

5. Default for VCS/Verilotor

If you want to run default configuration on verilator use the following command

make -f $RV_ROOT/tools/Makefile

For VCS use

make -f $RV_ROOT/tools/Makefile vcs_all

The simulation run/build command has following generic form:

    make -f $RV_ROOT/tools/Makefile [<simulator>] [debug=1] [snapshot=mybuild] [target=<target>] [TEST=<test>] [TEST_DIR=<path_to_test_dir>]

where:

<simulator> -  can be 'verilator' (by default) , 'vcs' - Synopsys VCS, 'riviera'- Aldec Riviera-PRO. If not provided, 'make' cleans work directory, builds verilator executable and runs a test.
debug=1     -  allows VCD generation for verilator and VCS and SHM waves for irun option.
<target>    -  predefined CPU configurations 'default' ( by default), 'default_ahb', 'typical_pd', 'high_perf'. 
TEST        -  allows to run a C (<test>.c) or assembly (<test>.s) test, hello_world is run by default. 
TEST_DIR    -  alternative to test source directory testbench/asm or testbench/tests.
<snapshot>  -  run and build executable model of custom CPU configuration, remember to provide 'snapshot' argument for runs on custom configurations.
CONF_PARAMS -  allows to provide -set options to quasar.conf script to alter predefined targets parameters.

Example:

    make -f $RV_ROOT/tools/Makefile verilator TEST=cmark

will build and simulate testbench/asm/cmark.c program with verilator.

If you want to compile a test only, you can run:

    make -f $RV_ROOT/tools/Makefile program.hex TEST=<test> [TEST_DIR=/path/to/dir]

The Makefile uses snapshot/<target>/link.ld file, generated by quasar.conf script by default to build test executable. User can provide test specific linker file in form <test_name>.ld to build the test executable, in the same directory with the test source.

User also can create a test specific makefile in form <test_name>.makefile, containing building instructions how to create program.hex file used by simulation. The private makefile should be in the same directory as the test source. See examples in testbench/asm directory.

(program.hex file is loaded to instruction and LSU bus memory slaves and optionally to DCCM/ICCM at the beginning of simulation).

User can build program.hex file by any other means and then run simulation with following command:

make -f $RV_ROOT/tools/Makefile <simulator>

Note: You may need to delete program.hex file from work directory, when run a new test.

The $RV_ROOT/testbench/asm directory contains following tests ready to simulate:

hello_world      -  default test program to run, prints Hello World message to screen and console.log
hello_world_dccm  - the same as above, but takes the string from preloaded DCCM.
hello_world_iccm  - the same as hello_world, but loads the test code to ICCM via LSU to DMA bridge and then executes it from there. Runs on QUASAR with AXI4 buses only. 
cmark             - coremark benchmark running with code and data in external memories
cmark_dccm        - the same as above, running data and stack from DCCM (faster)
cmark_iccm        - the same as above with preloaded code to ICCM.

dhry              - Run dhrystone. (Scale by 1757 to get DMIPS/MHZ)

The $RV_ROOT/testbench/hex directory contains precompiled hex files of the tests, ready for simulation in case RISCV SW tools are not installed.

6. Logical Equivalence Checking of Quasar

If you want to perform LEC on quasar, use the following command

make -f $RV_ROOT/tools/Makefile lec

This command will call the LEC Makefile to clone Quasar along with the SweRV-EL2 and run sbt for chisel-generated RTL. Then, this will take file for user-match the ports, blockbox pins, latches, flops and perform the LEC of Quasar. Following log files are created in $RV_ROOT/verif/LEC/formality_work/formality_log : fm_shell_command.log gives the detail of instructions formality.log gives the detail of undriven nets

Note: The testbench has a simple synthesizable bridge that allows you to load the ICCM via load/store instructions. This is only supported for AXI4 builds.