2021-01-28 01:36:43 +08:00
# EH1 RISC-V SweRV Core<sup>TM</sup> 1.9 from Western Digital
2019-06-02 14:43:28 +08:00
2021-01-28 01:36:43 +08:00
This repository contains the EH1 SweRV Core< sup > TM< / sup > design RTL
2019-06-02 14:45:59 +08:00
## 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.
## Directory Structure
├── configs # Configurations Dir
│ └── snapshots # Where generated configuration files are created
├── design # Design root dir
2020-02-20 10:25:04 +08:00
│ ├── dbg # Debugger
│ ├── dec # Decode, Registers and Exceptions
│ ├── dmi # DMI block
│ ├── exu # EXU (ALU/MUL/DIV)
2021-01-28 01:36:43 +08:00
│ ├── ifu # Fetch & Branch Predictor
2019-06-02 14:45:59 +08:00
│ ├── include
│ ├── lib
2020-02-20 10:25:04 +08:00
│ └── lsu # Load/Store
2019-06-02 14:45:59 +08:00
├── docs
├── tools # Scripts/Makefiles
└── testbench # (Very) simple testbench
2020-02-20 10:25:04 +08:00
2019-06-02 14:45:59 +08:00
## Dependencies
2021-01-28 01:36:43 +08:00
- Verilator ** (4.102 or later)** must be installed on the system if running with verilator
2020-02-20 10:25:04 +08:00
- If adding/removing instructions, espresso must be installed (used by *tools/coredecode* )
- 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.
2019-06-02 14:45:59 +08:00
## Quickstart guide
1. Clone the repository
1. Setup RV_ROOT to point to the path in your local filesystem
1. Determine your configuration {optional}
1. Run make with tools/Makefile
2019-06-04 22:58:40 +08:00
## Release Notes for this version
Please see [release notes ](release-notes.md ) for changes and bug fixes in this version of SweRV
2019-06-02 14:45:59 +08:00
### Configurations
SweRV can be configured by running the `$RV_ROOT/configs/swerv.config` script:
`% $RV_ROOT/configs/swerv.config -h` for detailed help options
2020-02-20 10:25:04 +08:00
For example to build with a DCCM of size 64 Kb:
2019-06-02 14:45:59 +08:00
`% $RV_ROOT/configs/swerv.config -dccm_size=64`
2020-02-20 10:25:04 +08:00
This will update the **default** snapshot in $PWD/snapshots/default/ with parameters for a 64K DCCM. To **unset** a parameter, use `-unset=PARAM` option to swerv.config.
2019-06-02 14:45:59 +08:00
Add `-snapshot=dccm64` , for example, if you wish to name your build snapshot *dccm64* and refer to it during the build.
2020-02-20 10:25:04 +08:00
There are four predefined target configurations: `default` , `default_ahb` , `default_pd` , `high_perf` that can be selected via
the `-target=name` option to swerv.config.
2019-06-02 14:45:59 +08:00
This script derives the following consistent set of include files :
2021-01-28 01:36:43 +08:00
snapshots/default
2019-06-02 14:45:59 +08:00
├── common_defines.vh # `defines for testbench or design
├── defines.h # #defines for C/assembly headers
├── 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
### Building a model
2020-02-20 10:25:04 +08:00
while in a work directory:
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
1. Set the RV_ROOT environment variable to the root of the SweRV directory structure.
Example for bash shell:
`export RV_ROOT=/path/to/swerv`
Example for csh or its derivatives:
`setenv RV_ROOT /path/to/swerv`
1. Create your specific configuration
2019-06-02 14:45:59 +08:00
*(Skip if default is sufficient)*
2020-02-20 10:25:04 +08:00
*(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:
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
`$RV_ROOT/configs/swerv.config [configuration options..] -snapshot=mybuild`
2021-01-28 01:36:43 +08:00
Snapshots are placed in ./snapshots directory
2019-06-02 14:45:59 +08:00
2020-09-19 04:34:02 +08:00
**Building an FPGA speed optimized model:**
Use ``-fpga_optimize=1`` option to ``swerv.config`` to build a model that removes clock gating logic from flop model so that the FPGA builds can run at higher speeds. **This is now the default option for
targets other than ``default_pd``.**
**Building a Power optimized model (ASIC flows):**
Use ``-fpga_optimize=0`` option to ``swerv.config`` to build a model that **enables** clock gating logic into the flop model so that the ASIC flows get a better power footprint. **This is now the default option for
target``default_pd``.**
### Running RTL simulations
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
1. Running a simple Hello World program (verilator)
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
`make -f $RV_ROOT/tools/Makefile`
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
This command will build a verilator model of SweRV EH1 with AXI bus, and
execute a short sequence of instructions that writes out "HELLO WORLD"
to the bus.
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
The simulation produces output on the screen like:
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
````
VerilatorTB: Start of sim
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
----------------------------------
Hello World from SweRV EH1 @WDC !!
----------------------------------
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
Finished : minstret = 443, mcycle = 1372
See "exec.log" for execution trace with register updates..
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
TEST_PASSED
````
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
The simulation generates following files:
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
`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.
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:
` ./obj_dir/Vtb_top `
or
`make -f $RV_ROOT/tools/Makefile verilator`
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
The simulation run/build command has following generic form:
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
```
make -f $RV_ROOT/tools/Makefile [< simulator > ] [debug=1] [snapshot=< snapshot > ] [target=< target > ] [TEST=< test > ] [TEST_DIR=< path_to_test_dir > ] [CONF_PARAMS=< swerv.config option > ]
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
where:
2019-06-02 14:45:59 +08:00
2020-02-27 16:40:53 +08:00
< simulator > - can be 'verilator' (by default) 'irun' - Cadence xrun, 'vcs' - Synopsys VCS, 'vlog' Mentor Questa,
'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, VCS and Riviera-PRO and SHM waves for irun option.
2020-02-20 10:25:04 +08:00
< target > - predefined CPU configurations 'default' ( by default), 'default_ahb', 'default_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
< snapshot > - run and build executable model of custom CPU configuration, remember to provide 'snapshot' argument
for runs on custom configurations.
CONF_PARAMS - configuration parameter for swerv.config : ex: 'CONF_PARAMS=-unset=dccm_enable' to build with no DCCM
```
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
Example:
2019-06-02 14:45:59 +08:00
2020-02-20 10:25:04 +08:00
make -f $RV_ROOT/tools/Makefile verilator TEST=cmark
will simulate testbench/asm/cmark.c program with verilator on default target
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 `$RV_ROOT/testbench/link.ld` file 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` , contaning building instructions
2020-09-19 04:34:02 +08:00
how to create `program.hex` file, used by simulation. The private makefile should be in the same directory
2020-02-20 10:25:04 +08:00
as the test source.
2020-09-19 04:34:02 +08:00
*(`program.hex` file is loaded to instruction and data bus memory slaves and
optionally to DCCM/ICCM at the beginning of simulation)*.
2020-02-20 10:25:04 +08:00
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 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.
2021-01-28 01:36:43 +08:00
hello_world_iccm - the same as above, but CPU copies the code from external memory to ICCM via AXI LSU to DMA bridge
and then jumps there. The test runs only on CPU configurations with ICCM and AXI bus.
2020-02-20 10:25:04 +08:00
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, but with code preloaded to iccm - runs only on CPU with ICCM
use CONF_PARAMS=-set=iccm_enable argument to `make` to build CPU with ICCM
2021-01-28 01:36:43 +08:00
dhry - dhrystone benchmark - example of multi source files program
2020-02-20 10:25:04 +08:00
```
The `$RV_ROOT/testbench/hex` directory contains precompiled hex files of the tests, ready for simulation in case RISCV SW tools are not installed.
2019-06-02 14:45:59 +08:00
----
2020-02-20 10:25:04 +08:00
Western Digital, the Western Digital logo, G-Technology, SanDisk, Tegile, Upthere, WD, SweRV Core, SweRV ISS,
and OmniXtend are registered trademarks or trademarks of Western Digital Corporation or its affiliates in the US
and/or other countries. All other marks are the property of their respective owners.
