How can I find some manuals about rocket-chip?

Question

I'm learning the code of rocket-chip. But I find it difficult to read its code due to the complex relationship. So I need some maunal to help me. Unluckily, it seems that there are few manuals about it. So could anyone provide me with manuals which benifit to read rocket-chip's code?

Answer 1

Working with Rocket-Chip requires you to understand the following things really well:

1. Diplomacy -- how Rocket-Chip implements the Diplomacy framework that's used to negotiate parameters during circuit elaboration and propagate them through the chip. Look at Henry Cook's Ph.D. dissertation at U.C. Berkeley for context on this, or better yet conference talks for instance.

2. TileLink -- specifically the way the Rocket-Chip uses Chisel to implement the TileLink specification

3. Functional programming in Scala -- the Rocket-Chip code base makes extensive use of Scala language features such as case classes, pattern matching, higher-order functions, partial functions, anonymous functions, trait mix-ins, and so on. So you'll see things like important variables defined with a map function, pattern-matched to a case statement, using implicit parameters, that you can't find, or even determine at code-writing time.

4. Chisel -- Specifically the data types and constructors for making circuit components. Chisel is the easy part.

I don't know of any kind of manual, but here are some things to help you understand the architecture:

• Draw pictures of object hierarchies -- the object hierarchies can be 10 to 12 levels deep and there are over a thousand relevant classes and objects to know about (just within Rocket-Chip's src/main/scala folder, grep -rn "class" | wc -l returns 1126, grep -rn "object" | wc -l returns 533, and grep -rn "trait" | wc -l returns 196). There are barely any comments, so you need to see how each class, object, and trait is used. Ctrl+click to follow the superclass (where it says extends RocketSubsystemModuleImp), and draw out the class hierarchies. That will help you build a big-picture sense of where behavior comes from.
• Use IntelliJ's structure panel -- this can help you keep the most relevant objects, classes, and their variables in mind, at least for a given file you have open.
• Look for usage -- Again in IntelliJ, Ctrl+hover on a class to see the hover window that says "show uses for BlahBlahBlah". Ctrl+click that, and then browse to the different places it is used.
• Use grep and find -- If you come across a pattern or construction that's unfamiliar, search for that patterns throughout the code base to see how it's used.
• Break it, then fix it -- If you're using IntelliJ, remove the ._ after the import statements, and replace it with the exact classes that are being imported. To find those classes, you can comment that entire line out, then see what breaks (as in what gets a red squiggly line underneath it). Then replace the line, and Ctrl+click the broken class or constructor to follow each one to where it is implemented in the code. Read the source to determine the parameters and how it works.

// import freechips.rocketchip.tilelink._ 
// change to:
import freechips.rocketchip.tilelink.{TLToAXI4, TLToAHB}

• Debug -- I would say debug, so you could see how the objects go together at runtime, but I don't have a grasp on how to get that information yet since the circuit elaborates through Makefiles, scripts, and sbt, rather than just through sbt.
• Write tests -- Use the scalatest framework or chisel test specs to ask discrete questions about how things get built. This will help you determine properties of individual variables, objects, or configurations, but you'll need to have a lot of structural knowledge first, and then expectation about what each value you're testing against should be. That requires a lot of the above first.

Answer 2

I would recommend you have a look at chisel3. The Rocket-Chip RISCV core is written in this. I've added a couple of links below to get you started: Chisel_Homepage,Chisel_Github,Chisel_Tutorial.

There is also a RISCV mini, which is a three stage riscv that was put together for learning purposes. available below not sure how up to date this on is though.

It may also be worth looking some example project on FPGA when you get comfortable with it, Microsemi, a Microchip company, has a selection of RISC-V cores and an Ecosystem to go with it. I'll link the MiV Ecosystem below too.3_Stage_RISCV_mini,MIV_ECOSYSTEM. Hope this helps, Ciaran