Repository files navigation

Diagrams:Sodor Github wiki

More documentation:Librecores Sodor wiki

Downstream development:Librecores Sodor

This repo has been put together to demonstrate a number of simpleRISC-Vinteger pipelines written inChisel:

• 1-stage (essentially an ISA simulator)
• 2-stage (demonstrates pipelining in Chisel)
• 3-stage (uses sequential memory; supports both Harvard and Princeton versions)
• 5-stage (can toggle between fully bypassed or fully interlocked)
• "bus"-based micro-coded implementation

All of the cores implement the RISC-V 32b integer base user-level ISA (RV32I)version 2.0. None of the cores support virtual memory, and thus only implementthe Machine-level (M-mode) of the Privileged ISA v1.10 .

All processors talk to a simple scratchpad memory (asynchronous,single-cycle), with no backing outer memory (the 3-stage is the exception- its scratchpad is synchronous). Programs are loaded in via a Debug Transport Module(DTM) described inDebug Spec v0.13 while the core is kept in reset.

This repository is set up to use the Verilog file generated by Chisel3 which is fedto Verilator along with a test harness in C++ to generate and run the Sodor emulators.

See doc/ for microarchitecture diagrams which can be viewed usingdraw.io using the following example linkhttps://www.draw.io/?url=https://raw.githubusercontent.com/librecores/riscv-sodor/master/doc/1stage.xml wherein master/doc/1stage.xml needs to be changed as needed

doc - Microarchitecture diagrams for all stages in XML format to be used with draw.io

emulator - C source used as test harness are fed to verilator to generate emulator

install - Compiled binaries of ISA/BENCHMARK tests

project - Scala configuration files fed to Scala Build Tool(sbt)

riscv-fesvr - Frontend Server for the target to load the binaries and execute any requested syscall. It is a forked version to add support for system-bus access

riscv-tests - Recipe to generate ISA/BENCHMARK tests

sbt - sbt_launch.jar which is fed to java to launch sbt

src - Scala Sources

vsrc - Verilog Sources used for blackbox in chisel

Makefile - To automate building the emulators

git clone --recursive https://github.com/librecores/riscv-sodor.gitcd riscv-sodor

Because this repository is designed to be used as RISC-V processorexamples written inChisel3 (and a regressive testsuite for Chisel updates),no externalRISC-V tools are used (with the exception ofthe RISC-Vfront-end server andoptionally, thespike-dasm binary toprovide a disassembly of instructions in the generated *.out files).The assumption is thatriscv-gnu-toolchain is notavailable on the local system. Thus, RISC-V unit tests and benchmarks werecompiled and committed to the sodor repository in the ./install directory (as are the .dump files).

Install verilator using any of the following possible waysFor Ubuntu 17.04

sudo apt install pkg-config verilator#optionally gtkwave to view waveform dumps

For Ubuntu 16.10 and lower

sudo apt install pkg-configwget http://mirrors.kernel.org/ubuntu/pool/universe/v/verilator/verilator_3.900-1_amd64.debsudo dpkg -i verilator_3.900-1_amd64.deb

If you don't have enough permissions to use apt on your machine

# make autoconf g++ flex bison should be availablewget https://www.veripool.org/ftp/verilator-3.906.tgztar -xzf verilator-3.906.tgzcd verilator-3.906unset VERILATOR_ROOT./configuremakeexport VERILATOR_ROOT=$PWDexport PATH=$PATH:$VERILATOR_ROOT/bin

Install the RISC-V front-end server to talk between the host and RISC-V target processors.

cd riscv-fesvrmkdir build;cd build../configure --prefix=/usr/localmake install

Build the sodor emulators

make# To run the all the stages with the given tests available in ./installmake run-emulator# Clean all generated filesmake clean

$ make run-emulator

make run-emulator-debug

When run in debug mode, all processors will generate .vcd information (viewableby your favorite waveform viewer). All processors can also spit out cycle-by-cyclelog information.Although already done for you by the build system, to generate .vcd files, seeemulator/common/Makefile.include to add the "-v${vcdfilename}" flag to theemulator-debug binary.

RISC-V fesvr allows you to use elf as input to sodor cores so no need to generatethe hex files

Have fun!

Sodor includes a submodule link to the "riscv-tests" repository. To help Sodorusers, the tests and benchmarks have been pre-compiled and placed in the./install directory.

If you would like to compile your own tests, you will need to build anRISC-V compiler. Set $RISCV to where you would like to install RISC-V relatedtools generally/opt/riscv, and make sure that $RISCV/bin is in your path.

git clone --recursive https://github.com/riscv/riscv-gnu-toolchain.gitcd riscv-gnu-toolchainmkdir build;cd build../configure --prefix=$RISCV --enable-multilibmake -j4

This will install a compiler named riscv64-unknown-elf-gcc

Sifive provides prebuilt toolchain found herehttps://www.sifive.com/products/tools/ which can be used to generate ELF's for Sodor

#Before dowloading(~326MB) the archive do check if 20171231 is latest available on their websitewget https://static.dev.sifive.com/dev-tools/riscv64-unknown-elf-gcc-20171231-x86_64-linux-centos6.tar.gztar -xzf riscv64-unknown-elf-gcc-20171231-x86_64-linux-centos6.tar.gz -C /optrm riscv64-unknown-elf-gcc-20171231-x86_64-linux-centos6.tar.gzmv /opt/riscv64-unknown-elf-gcc-20171231-x86_64-linux-centos6 /opt/riscvexport PATH=/opt/riscv/bin:$PATHexport RISCV=/opt/riscv

Append to line inisa/Makefile:33-march=rv32i -mabi=ilp32

cd riscv-tests/isa    make rv32ui    make rv32mi

Sodor only supports the rv32ui-p (user-level) and rv32mi-p (machine-level) physical memory tests.

Append to line inbenchmarks/Makefile:40-march=rv32i -mabi=ilp32

cd riscv-tests/benchmarks    make#will fail at compiling mm which is not supported and not needed    make dhrystone.riscv

After compiling the tests and benchmarks, for the tests edit line inemulator/common/Makefile.include:138 to indicate the appropriate path to ELF's and similarly for benchmarks by editingemulator/common/Makefile.include:191

If you would like to run tests yourself, you can use the Spike ISA simulator(found in riscv-tools on the riscv.org webpage). By default, Spike executes inRV64G mode. To execute RV32I binaries, for example:

cd ./installspike --isa=RV32I rv32ui-p-simplespike --isa=RV32I dhrystone.riscv

For Sodor, the assembly tests rely on macros that can be found in theriscv-tests/env/p directory. You can simplify these macros as desired.

Unittests are added tosrc/test directory. Currently tests are for Debug and ScratchpadMemory only

  $ sbt"project common" shell> testOnly tests.MemoryTester> testOnly tests.DebugTests

or

  $ make MK_TARGET_PROC=common shell> testOnly tests.MemoryTester> testOnly tests.DebugTests

Inorder to write unittests for modules from other projects(eg. rv32_1stage,rv32_ucode)build.scala needs to be modified appropriately

What is the goal of these cores?

First and foremost, to provide a set of easy to understand cores that users caneasily modify and play with. Sodor is useful both as a quick introduction totheRISC-V ISA and to the hardware construction languageChisel3.

Are there any diagrams of these cores?

Diagrams of some of the processors can be found either in theSodor Github wiki, in doc/,or in doc/lab1.pdf. A more comprehensive write-up on the micro-code implementation canbe found at theCS152 website.

How do I generate Verilog code for use on a FPGA?

Chisel3 outputs verilog by default which can be generated by

cd emulator/rv32_1stagemake generated-src/Top.v

I want to help! Where do I go?

You can participate in the Sodor conversation ongitter. Downstream development is also taking place atLibrecores. Major milestones will be pulled back here. Check it out! We also accept pull requests here!

Here is an informal list of things that would be nice to get done. Feel free tocontribute!

• Reduce the port count on the scratchpad memory by having the Debug Module portshare one of the cpu ports.
• Refactor the stall, kill, fencei, and exception logic of the 5-stage to bemore understandable.
• Big Tasks