# Quasar RISC-V Core 1.0 from Lampro Mellon This repository contains the SweRV-EL2 Core written in CHISEL named "Quasar". ## License By contributing to this project, you agree that your contribution is governed by [Apache-2.0](LICENSE). Files under the [tools](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 ├── tools # Scripts/Makefiles ├── tracer_logs # generated log files └── verif ├── LEC └── sim # Simulation log/dump files ## Dependencies - Verilator **(4.030 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 7.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](release-notes.md) 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 ``` #### 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 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 @LM !! ---------------------------------- 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 ``` The simulation run/build command has following generic form: ``` make -f $RV_ROOT/tools/Makefile [] [debug=1] [snapshot=mybuild] [target=] [TEST=] [TEST_DIR=] ``` where: ``` - can be 'verilator' (by default) , 'vcs' - Synopsys VCS. 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. - predefined CPU configurations 'default' ( by default), 'default_ahb', 'typical_pd', 'high_perf'. TEST - allows to run a C (.c) or assembly (.s) test, hello_world is run by default. TEST_DIR - alternative to test source directory testbench/asm or testbench/tests. - 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. ``` #### 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 ``` 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_DIR=/path/to/dir] ``` The Makefile uses `snapshot//link.ld` file, generated by quasar.conf script by default to build test executable. User can provide test specific linker file in form `.ld` to build the test executable, in the same directory with the test source. User also can create a test specific makefile in form `.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 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 tes 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. ``` The `$RV_ROOT/testbench/hex` directory contains precompiled hex files of the tests, ready for simulation in case RISCV SW tools are not installed. **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.