diff --git a/README.md b/README.md new file mode 100644 index 00000000..ce4911ce --- /dev/null +++ b/README.md @@ -0,0 +1,260 @@ +# 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](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 + │ └── 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](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 + └── 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 [] [debug=1] [snapshot=mybuild] [target=] [TEST=] [TEST_DIR=] +``` +where: +``` + - 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. + - 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. +``` +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 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. + diff --git a/configs/README.md b/configs/README.md index 4835e413..c5f295fd 100644 --- a/configs/README.md +++ b/configs/README.md @@ -41,3 +41,4 @@ high_perf | Large BTB/BHT, AXI4 interface `quasar.config` may be edited to add additional target configurations, or new configurations may be created via the command line `-set` or `-unset` options. **Run `$RV_ROOT/configs/quasar.config -h` for options and settable parameters.** + diff --git a/doc/README.md b/doc/README.md index 8d89ba9b..b2dc8349 100644 --- a/doc/README.md +++ b/doc/README.md @@ -3,7 +3,17 @@ ### PPA Report **Note:** the `default` target is what we base our published PPA numbers. - - - -
SweRV-EL2Combinational CellsSequential CellsSlack (ns)Total Area
IFU671231468844.5841113872
Decode17511293622.548998515
EXU924849546.893851172
LSU14439134630.265652558
QuasarCombinational CellsSequential CellsSlack (ns)Total Area
IFU661161468629.6340654143
Decode17406293424.248996841
EXU994449548.873879864
LSU14750134532.995758686
Core-ComparisonCombinational CellsSequential CellsSlack (ns)Total Area
SweRV1169562084959.6663946233
Quasar1169042084459.7563662238
+|SweRV-EL2|Combinational Cells|Sequential Cells|Critical Path (ns)|Total Area| +|:---:|:---:|:---:|:---:|:---:| +|IFU-TOP|32225|15277|29.597|180540.504| +|DECODE-TOP|10381|3098|24.94|45934.848| +|EXU-TOP|4700|482|28.083|15802.212| +|LSU-TOP|8060|1380|21.005|29784.07| +|**Quasar**|**Combinational Cells**|**Sequential Cells**|**Critical Path (ns)**|**Total Area**| +|IFU-TOP|31086|15277|24.646|176448.192| +|DECODE-TOP|9457|3098|25.586|44259.994| +|EXU-TOP|4432|482|28.311|15249.129| +|LSU-TOP|8065|1380|20.168|29022.715| +|**Cores-Comparison**|**Combinational Cells**|**Sequential Cells**|**Critical Path (ns)**|**Total Area**| +|SweRV-EL2|58695|21658|50.909ns|289371.025| +|Quasar|56696|21586|49.415ns|285669.673| diff --git a/release-notes.md b/release-notes.md new file mode 100644 index 00000000..bda75126 --- /dev/null +++ b/release-notes.md @@ -0,0 +1,35 @@ +# Quasar RISC-V Core 2.0 from Lampro Mellon + +## Release Notes + +* Multiple debug module compliance deviations and bugs reported by Codasip +* Updates to debug module to level compliance to version 0.13.2 of debug spec +* Trigger chaining compliance fixes +* Power optimization improvements and clock gating improvements + * Significantly lower power in sleep as well as normal operation. +* Enhanced debug memory abstract command to access internal as well as external memories +* Added bit-manipulation support for Zba, Zbb, Zbc, Zbe, Zbf, Zbp, Zbr, Zbs (Jan 29, 2020 Draft spec). + * Zbs and Zbb are enabled by default. Use -set=bitmanip+zb*=1 to enable other sub-extensions. +* Enhancements and additional configurations options for a faster divider +* JTAG controller intial state issue fixed +* Branch predictor fully-associative mode for 8,16,32 entries. +* Corner case bugs fixes related to + * Bus protocol corner cases (ahb) + * Fetch bus error recording improved accuracy + * Branch predictor pathological timing cases fixes + * Fast interrupt with DCCM ECC errors priority bug + * MPC & PMU protocol cleanup + * Performance counter bug fixes (counting branch prediction events) + * Triggers and ECC correctable error overflows bug fixes + +* Demo test-bench updates + * Handling bigger test sizes using associative arrays in external memory slaves, + * simplified test building process and CCM loading functions (only program.hex is generated, no data.hex) + * Improved Makefile and example tests (see README) + * Generating crt0 and link.ld from quasar.config + +# Quasar RISC-V Core 1.0 from Lampro Mellon + +## Release Notes + +Initial release diff --git a/testbench/asm/cmark.c b/testbench/asm/cmark.c index b366c80d..7f2bc915 100644 --- a/testbench/asm/cmark.c +++ b/testbench/asm/cmark.c @@ -22,8 +22,6 @@ EEMBC El Dorado Hills, CA, 95762 */ -//#include "/wd/users/jrahmeh/coremark_v1.0/riscv/coremark.h" - /* Author : Shay Gal-On, EEMBC diff --git a/testbench/asm/crt0.s b/testbench/asm/crt0.s index 17878a98..73027388 100644 --- a/testbench/asm/crt0.s +++ b/testbench/asm/crt0.s @@ -1,5 +1,4 @@ # SPDX-License-Identifier: Apache-2.0 -# Copyright 2020 Western Digital Corporation or its affiliates. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/testbench/asm/hello_world.s b/testbench/asm/hello_world.s index 0c74a0dd..8d3ee923 100644 --- a/testbench/asm/hello_world.s +++ b/testbench/asm/hello_world.s @@ -1,5 +1,4 @@ // SPDX-License-Identifier: Apache-2.0 -// Copyright 2019 Western Digital Corporation or its affiliates. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/testbench/asm/hello_world_iccm.s b/testbench/asm/hello_world_iccm.s index c376c819..32020b59 100644 --- a/testbench/asm/hello_world_iccm.s +++ b/testbench/asm/hello_world_iccm.s @@ -1,5 +1,4 @@ // SPDX-License-Identifier: Apache-2.0 -// Copyright 2019 Western Digital Corporation or its affiliates. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/testbench/asm/printf.c b/testbench/asm/printf.c index aab027ba..662413a6 100644 --- a/testbench/asm/printf.c +++ b/testbench/asm/printf.c @@ -1,5 +1,4 @@ // SPDX-License-Identifier: Apache-2.0 -// Copyright 2020 Western Digital Corporation or its affiliates. // // Licensed under the Apache License, Version 2.0 (the "License"); // you may not use this file except in compliance with the License. diff --git a/tracer_logs/README.md b/tracer_logs/README.md new file mode 100644 index 00000000..cbc405c9 --- /dev/null +++ b/tracer_logs/README.md @@ -0,0 +1 @@ +**This directory contains tracer logs** diff --git a/verif/sim/README.md b/verif/sim/README.md index 1992318c..dfc85497 100644 --- a/verif/sim/README.md +++ b/verif/sim/README.md @@ -1 +1 @@ -**Directory containing the test files and simulation logs generated at runtime** +Directory containing the test files and simulation logs generated at runtime