# riscv-sodor

**Repository Path**: RV4Kids/riscv-sodor

## Basic Information

- **Project Name**: riscv-sodor
- **Description**: 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-stag

- **Primary Language**: Verilog
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-08-16
- **Last Updated**: 2022-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

About The Sodor Processor Collection
====================================

**Note: This repo has been updated to be used with the [Chipyard](https://github.com/ucb-bar/chipyard) SoC Generator.**
**For the old self-contained version of Sodor (which is no longer maintained), see https://github.com/ucb-bar/riscv-sodor/tree/sodor-old.**

Diagrams: [Sodor Github wiki](https://github.com/ucb-bar/riscv-sodor/wiki)

More documentation: [Librecores Sodor wiki](https://github.com/librecores/riscv-sodor/wiki)

Downstream development: [Librecores Sodor](https://github.com/librecores/riscv-sodor)


This repo has been put together to demonstrate a number of simple [RISC-V](http://riscv.org)
integer pipelines written in [Chisel](http://chisel.eecs.berkeley.edu):

* 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 JTAG or TSI,
scratchpads 3-port memories (instruction, data, debug).

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.

This repo works great as an undergraduate lab (and has been used by Berkeley's
CS152 class for 3 semesters and counting). See doc/ for an example, as well as
for some processor diagrams. Be careful though - admittedly some of those
documents may become dated as things like the Privileged ISA evolve.



Getting the repo and Building the processor emulators
=====================================================

This repo is **NOT** a self-running repository. Please follow the instruction in 
https://chipyard.readthedocs.io/en/latest/ to set up Chipyard and simulate Sodor cores.

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](http://riscv.org) and to the hardware construction language
[Chisel3](http://chisel.eecs.berkeley.edu).

*Are there any diagrams of these cores?*

Diagrams of some of the processors can be found either in the
[Sodor Github wiki](https://github.com/ucb-bar/riscv-sodor/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](http://inst.eecs.berkeley.edu/~cs152/sp12/handouts/microcode.pdf).


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

Chisel3 outputs verilog by default which can be generated by
```bash
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](https://gitter.im/librecores/riscv-sodor). Downstream development is also taking place at [Librecores](https://github.com/librecores/riscv-sodor). 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 HTIF port
  share one of the cpu ports.
* Provide a Verilog test harness, and put the 3-stage on a FPGA.
* Add support for the ma_addr, ma_fetch ISA tests. This requires detecting
  misaligned address exceptions.
* Greatly cleanup the common/csr.scala file, to make it clearer and more
  understandable.
* Refactor the stall, kill, fencei, and exception logic of the 5-stage to be
  more understandable.
* Update the u-code to properly handle illegal instructions (rv32mi-p-illegal)
  and to properly handle exceptions generated by the CSR file (rv32mi-p-csr).