Readme added

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 [<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.
+

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.**
+

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

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
 

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.

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.

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.

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.

tracer_logs/README.md

@@ -0,0 +1 @@
+**This directory contains tracer logs**

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