About The Sodor Processor Collection

(Notes for the branched repository)

Getting the repo

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

Software/Tools Dependency

• Chisel3 (and a regressive testsuite for Chisel updates),

• RISC-V tools should be installed to $RISCV in $PATH (usually assumign /opt/riscv).

• riscv-gnu-toolchain.

• verilator. Install verilator using any of the following possible ways: For 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-config
wget http://mirrors.kernel.org/ubuntu/pool/universe/v/verilator/verilator_3.900-1_amd64.deb
sudo 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 available
wget https://www.veripool.org/ftp/verilator-3.906.tgz
tar -xzf verilator-3.906.tgz
cd verilator-3.906
unset VERILATOR_ROOT
./configure
make
export VERILATOR_ROOT=$PWD
export PATH=$PATH:$VERILATOR_ROOT/bin

Build submodules as prerequesites to run any tests

• RISC-V fesvr (front-end server): Install the tool from local submodule to communicate between the host and RISC-V target processors.

cd riscv-fesvr
mkdir build; cd build
../configure --prefix=/usr/local
make install # Please be noticed this will install into your host system directories. 

• Compiling the riscv-tests (make sure you have multilib compilation when buildng riscv-gnu-tools toolchain to allow 32bit ABI) Append to line in isa/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 in benchmarks/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 in emulator/common/Makefile.include:138 to indicate the appropriate path to ELF's and similarly for benchmarks by editing emulator/common/Makefile.include:191

Building the processor emulators

Build the sodor emulators

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

Running the RISC-V tests

$ make run-emulator

(Optional) Running debug version to produce signal traces

make run-emulator-debug

When run in debug mode, all processors will generate .vcd information (viewable by your favorite waveform viewer). All processors can also spit out cycle-by-cycle log information.

Although already done for you by the build system, to generate .vcd files, see emulator/common/Makefile.include to add the "-v${vcdfilename}" flag to the emulator-debug binary.

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

You might want to run an individual test as below:

cd emulator/rv32_1stage
./emulator +max-cycles=10000000 +verbose +loadmem=/work/experimental/riscv-sodor/riscv-tests/isa/rv32ui-p-add none
./emulator-debug +max-cycles=10000000 +verbose +loadmem=/work/experimental/riscv-sodor/riscv-tests/benchmarks/qsort.riscv -vtest.vcd

Below are cleaned-up original README contents

---

Diagrams: Sodor Github wiki

More documentation: Librecores Sodor wiki

Downstream development: Librecores Sodor

This repo has been put together to demonstrate a number of simple RISC-V integer pipelines written in Chisel:

• 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 implement the 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 in Debug 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 fed to Verilator along with a test harness in C++ to generate and run the Sodor emulators.

See doc/ for microarchitecture diagrams which can be viewed using draw.io using the following example link https://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

Directory Structure

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

The riscv-test Collection

Sodor includes a submodule link to the "riscv-tests" repository. See above contents on how to compile tests before running any.

The generated assembly code looks too complex!

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

Unittests

Unittests are added to src/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

FAQ

What is the goal of these cores?

First and foremost, to provide a set of easy to understand cores that users can easily modify and play with. Sodor is useful both as a quick introduction to the RISC-V ISA and to the hardware construction language Chisel3.

Are there any diagrams of these cores?

Diagrams of some of the processors can be found either in the Sodor Github wiki, in doc/, or in doc/lab1.pdf. A more comprehensive write-up on the micro-code implementation can be found at the CS152 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_1stage
make generated-src/Top.v

I want to help! Where do I go?

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

TODO

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

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