Repository files navigation

This repository contains the Rocket chip generator necessary to instantiatethe RISC-V Rocket Core. For more information on Rocket Chip, please consult ourtechnical report.

RocketChip development meetings happen every 2 weeks on Wednesday 17:00 – 18:00am CST (Pacific Time - Los Angeles) with meeting noteshere:

• Clickhere to subscribe Meeting Schedule(iCal format)
• Clickhere to view Meeting Schedule via Google Calendar
• Clickhere to join Zoom meeting (ID: 93899365000, passcode: 754340)

For possible time adjustments, they will be negotiated in Slack and published in the calendar.

• Quick instructions for those who want to dive directly into the details without knowing exactly what's in the repository.
• What's in the Rocket chip generator repository?
• How should I use the Rocket chip generator?
  • Using the cycle-accurate Verilator simulation
  • Mapping a Rocket core down to an FPGA
  • Pushing a Rocket core through the VLSI tools
• How can I parameterize my Rocket chip?
• Debugging with GDB
• Building Rocket Chip with an IDE
• Contributors

$ git clone https://github.com/ucb-bar/rocket-chip.git$ cd rocket-chip$ git submodule update --init

You may need to install some additional packages to use this repository.Rather than list all dependencies here, please see the appropriate section of the READMEs for each of the subprojects:

• rocket-tools "Ubuntu Packages Needed"
• chisel3 "Installation"

Generating verilog

$ make verilog

Generating verilog for a specific Config

$ make verilog CONFIG=DefaultSmallConfig

If you are trying to keep your repo up to date with this GitHub repo,you also need to keep the submodules and tools up to date.

$ # Get the newest versions of the files in this repo$ git pull origin master$ # Make sure the submodules have the correct versions$ git submodule update --init --recursive

If rocket-tools version changes, you should recompile and install rocket-tools according to the directions in therocket-tools/README.

$ cd rocket-tools$ ./build.sh$ ./build-rv32ima.sh (if you are using RV32)

The rocket-chip repository is a meta-repository that points to severalsub-repositories usingGit submodules.Those repositories contain tools needed to generate and test SoC designs.This respository also contains code that is used to generate RTL.Hardware generation is done usingChisel,a hardware construction language embedded in Scala.The rocket-chip generator is a Scala program that invokes the Chisel compilerin order to emit RTL describing a complete SoC.The following sections describe the components of this repository.

Git submodules allow you to keep a Git repository as a subdirectory of another Git repository.For projects being co-developed with the Rocket Chip Generator, we have often found it expedient to track them as submodules,allowing for rapid exploitation of new features while keeping commit histories separate.As submoduled projects adopt stable public APIs, we transition them to external dependencies.Here are the submodules that are currently being tracked in the rocket-chip repository:

• chisel3(https://github.com/ucb-bar/chisel3):The Rocket Chip Generator usesChisel to generate RTL.
• firrtl(https://github.com/ucb-bar/firrtl):Firrtl (Flexible Internal Representation for RTL)is the intermediate representation of RTL constructions used by Chisel3.The Chisel3 compiler generates a Firrtl representation,from which the final product (Verilog code, C code, etc) is generated.
• hardfloat(https://github.com/ucb-bar/berkeley-hardfloat):Hardfloat holds Chisel code that generates parameterized IEEE 754-2008 compliantfloating-point units used for fused multiply-add operations, conversionsbetween integer and floating-point numbers, and conversions betweenfloating-point conversions with different precision.
• rocket-tools(https://github.com/freechipsproject/rocket-tools):We tag a version of RISC-V software tools that work with the RTL committed in this repository.
• torture(https://github.com/ucb-bar/riscv-torture):This module is used to generate and execute constrained random instruction streams that canbe used to stress-test both the core and uncore portions of the design.

In addition to submodules that track independent Git repositories,the rocket-chip code base is itself factored into a number of Scala packages.These packages are all found within the src/main/scala directory.Some of these packages provide Scala utilities for generator configuration,while other contain the actual Chisel RTL generators themselves.Here is a brief description of what can be found in each package:

• ambaThis RTL package uses diplomacy to generate bus implementations of AMBA protocols, including AXI4, AHB-lite, and APB.
• configThis utility package provides Scala interfaces for configuring a generator via a dynamically-scopedparameterization library.
• coreplexThis RTL package generates a complete coreplex by gluing together a variety of components from other packages,including: tiled Rocket cores, a system bus network, coherence agents, debug devices, interrupt handlers, externally-facing peripherals,clock-crossers and converters from TileLink to external bus protocols (e.g. AXI or AHB).
• devicesThis RTL package contains implementations for peripheral devices, including the Debug module and various TL slaves.
• diplomacyThis utility package extends Chisel by allowing for two-phase hardware elaboration, in which certain parametersare dynamically negotiated between modules. For more information about diplomacy, seethis paper.
• groundtestThis RTL package generates synthesizable hardware testers that emit randomizedmemory access streams in order to stress-tests the uncore memory hierarchy.
• jtagThis RTL package provides definitions for generating JTAG bus interfaces.
• regmapperThis utility package generates slave devices with a standardized interface for accessing their memory-mapped registers.
• rocketThis RTL package generates the Rocket in-order pipelined core,as well as the L1 instruction and data caches.This library is intended to be used by a chip generator that instantiates thecore within a memory system and connects it to the outside world.
• tileThis RTL package contains components that can be combined with cores to construct tiles, such as FPUs and accelerators.
• tilelinkThis RTL package uses diplomacy to generate bus implementations of the TileLink protocol. It also contains a varietyof adapters and protocol converters.
• systemThis top-level utility package invokes Chisel to elaborate a particular configuration of a coreplex,along with the appropriate testing collateral.
• unittestThis utility package contains a framework for generateing synthesizable hardware testers of individual modules.
• utilThis utility package provides a variety of common Scala and Chisel constructs that are re-used acrossmultiple other packages,

Outside of Scala, we also provide a variety of resources to create a complete SoC implementation andtest the generated designs.

• bootromSources for the first-stage bootloader included in the BootROM.
• csrcC sources for use with Verilator simulation.
• docsDocumentation, tutorials, etc for specific parts of the codebase.
• emulatorDirectory in which Verilator simulations are compiled and run.
• regressionDefines continuous integration and nightly regression suites.
• scriptsUtilities for parsing the output of simulations or manipulating the contents of source files.
• vsimDirectory in which Synopsys VCS simulations are compiled and run.
• vsrcVerilog sources containing interfaces, harnesses and VPI.

The Rocket Chip Scala build usesmill as build tool.

IDEs likeIntelliJ andVSCode are popular in the Scala community and work with Rocket Chip.

The Rocket Chip currently usesnix to configure the build and/or development environment, you need to install it first depending on your OS distro.

Then follow the steps:

1. Generate BSP config by running:

   mill mill.bsp.BSP/install

2. Patch theargv in.bsp/mill-bsp.json, from

   {"name":"mill-bsp","argv":["/usr/bin/mill","--bsp","--disable-ticker","--color","false","--jobs","1"],"millVersion":"0.10.9","bspVersion":"2.0.0","languages":["scala","java"]}

   to

   {"name":"mill-bsp","argv":["/usr/bin/nix","develop","-c","mill","--bsp","--disable-ticker","--color","false","--jobs","1"],"millVersion":"0.10.9","bspVersion":"2.0.0","languages":["scala","java"]}

3. Install and configureScala plugin.

4. BSP should be automatically run.If it doesn't, clickbsp on the right bar, then right-click on your project to reload.

3. Install and configureMetals extension.

4. Execute VSCode commandMetals: Import build.

Contributing guidelines can be found inCONTRIBUTING.md.

A list of contributors can be foundhere.

If used for research, please cite Rocket Chip by the technical report:

Krste Asanović, Rimas Avižienis, Jonathan Bachrach, Scott Beamer, David Biancolin, Christopher Celio, Henry Cook, Palmer Dabbelt, John Hauser, Adam Izraelevitz, Sagar Karandikar, Benjamin Keller, Donggyu Kim, John Koenig, Yunsup Lee, Eric Love, Martin Maas, Albert Magyar, Howard Mao, Miquel Moreto, Albert Ou, David Patterson, Brian Richards, Colin Schmidt, Stephen Twigg, Huy Vo, and Andrew Waterman,The Rocket Chip Generator, Technical Report UCB/EECS-2016-17, EECS Department, University of California, Berkeley, April 2016