Lab3: Construct a single-cycle RISC-V CPU with Chisel

Computer Architecture 2023 Fall

Development Objectives of this Project

Our goal is to create a RISC-V CPU that prioritizes simplicity while assuming a foundational understanding of digital circuits and the C programming language among its readers. The CPU should strike a balance between simplicity and sophistication, and we intend to maximize its functionality. This project encompasses the following key aspects, which will be prominently featured in the technical report:

1. Implementation in Chisel.
2. RV32I instruction set support.
3. Execution of programs compiled from the C programming language.
4. Successful completion of RISC-V Architectural Tests, also known as riscv-arch-test.

Prerequisites

Operating Systems

Ensure that you have a functioning GNU/Linux or macOS system with the necessary permissions to install software packages.

:warning: Notice

1. Consider using Linux or macOS instead of Microsoft Windows, as resolving any potential issues on Windows would be your responsibility.
2. Ubuntu Linux 22.04 is recommended.

   Please note that certain packages, such as Verilator, which are available in older Ubuntu distributions, may be too outdated to follow the instructions provided below.

3. If you are using an Apple Silicon-based MacBook, you may encounter some problems. Please record them and discuss them with the instructor.

Install the dependent packages

• For macOS
  ​​​​$ brew install verilator gtkwave
  

• For Ubuntu Linux
  ​​​​$ sudo apt install build-essential verilator gtkwave
  

Install sbt

sbt, short for Scala Build Tool, relies on Scala, a JVM (Java Virtual Machine) language that combines object-oriented and functional programming paradigms into a highly concise, logical, and exceptionally robust language. Therefore, before using sbt, you must ensure that a functional JVM is accessible in your environment.

• macOS

  Ensure that Homebrew is installed.

# Uninstall everything
$ brew uninstall sbt
$ brew uninstall jenv

# Install sdkman
$ curl -s "https://get.sdkman.io" | bash
$ source "$HOME/.sdkman/bin/sdkman-init.sh"

# Install Eclipse Temurin JDK 11
$ sdk install java 11.0.21-tem 
$ sdk install sbt

:warning: The version number 11 is crucial; otherwise, you may encounter unexpected issues with sbt.

• Linux

• Follow the instructions. You MUST install Eclipse Temurin JDK 11. You can follow the instructions mentioned above, starting with the curl step.

  Another approach is to utilize Apptainer. See champ's node.

Fundamental Concepts behind Chisel

Chisel is a domain specific language (DSL) implemented using Scala's macro features. Therefore, all programming related to circuit logic must be implemented using the macro definitions provided in the Chisel library, rather than directly using Scala language keywords. Specifically, when you want to use a constant in a circuit, such as 12, and compare it with a circuit value, you cannot write if (value == 12) but instead must write when(value === 12.U). Memorizing this fundamental concept is essential to correctly write valid Chisel code.

Chisel Cheatsheet

Relationship Between Chisel and Verilog

Chisel is not strictly an equivalent replacement for Verilog but rather a generator language. Hardware circuits written in Chisel need to be compiled into Verilog files and then synthesized into actual circuits through EDA (Electronic Design Automation) software. Furthermore, for the sake of generality, some features found in Verilog, such as negative-edge triggering and multi-clock simulation, are not fully supported or not supported at all in Chisel.

Illustration of Simple Combinational Logic

Let's explore a simple combinational logic example.

// simple logic expression
(a & ~b) | (~a & b) 

Unlike traditional execution models, the logic circuits associated with Chisel are continuously active, somewhat akin to continuous assignment in Verilog. However, Chisel takes a departure from Verilog's built-in logic gates and opts for expressions to define logic.

In the above example, we introduce "variables" a and b, which essentially serve as "named wires" due to their roles as inputs to the circuit. It is important to note that other wires within the circuit do not necessitate explicit names. While we have assumed one-bit-wide inputs and generated wires in this instance, these expressions can seamlessly adapt to wider wires, with Chisel's logic operators inherently operating in a "bitwise" manner. Furthermore, Chisel boasts a powerful wire width inference mechanism, enhancing its versatility and simplifying its use in designing complex logic circuits.

In the preceding example, the named wires a and b offer the advantage of reusability across multiple locations within the circuit. Likewise, it is possible to assign a name to the output of the circuit:

// simple logic expression
val out =(a & ~b) | (~a & b)

The keyword val is derived from Scala and serves as a means to declare a program variable that can only be assigned once, essentially creating a constant. This approach allows for the generation of a single output value at a specific location within the circuit and subsequently distributes it to other locations where the same output is required.

// fan-out
val z = (a & out) | (out & b)

Assigning names to wires and employing fanout mechanisms provide a means to reuse a single output value in multiple locations within the generated circuit.

Function abstraction enables us to reuse a circuit description effectively. Here is an example of a simple logic function:

def XOR(a: Bits, b: Bits) = (a & ~b) | (~a & b)

In this case, the function inputs and output are specified with the type Bits. We will delve deeper into types shortly. When we use the XOR function elsewhere, we essentially create a duplicate of the corresponding logic. You can think of the function as a "constructor" for this logic.

// Constructing multiple copies
val z = (x & XOR(x, y)) | (XOR(x, y) & y)

Basic Types

Chisel datatypes are employed to define the type of values that reside in state elements or flow through wires. While hardware circuits fundamentally manipulate vectors of binary digits, employing more abstract representations for values enables clearer specifications and aids in the generation of more efficient circuits by the tools.

The basic types:

Types	meaning
Bits	Raw collection of bits
SInt	Signed integer number
UInt	Unsigned integer number
Bool	Boolean

All signed numbers are represented using 2's complement in Chisel. Chisel also provides support for several higher-order types, including Bundles and Vecs.

• Unsigned and Signed Integers

The unsigned integer type is UInt, and the signed integer type is SInt. When declaring integers, you can specify the bit width using .W, for example, UInt(8.W). If you want to convert an integer from Scala to Chisel's hardware integer, you can use the .U operator, for example, 12.U. The .U operator also supports specifying the bit width, for example, 12.U(8.W).

• Booleans

The boolean type is Bool, and you can use .B to convert Scala boolean values to hardware boolean values, for example, true.B.

Type Inference

While it's useful to keep track of wire types, Scala's type inference allows you to omit type declarations when they are not necessary. For example, in our previous example:

// simple logic expression
val out = (a & ~b) | (~a & b)

the type of out was deduced based on the types of a and b as well as the operators used. If you want to ensure type clarity or if there is insufficient context for the inference engine, you can always explicitly specify the type like this:

// simple logic expression
val out: Bits =(a & ~b) | (~a & b)

Additionally, as we will explore later, explicit type declaration becomes necessary in certain situations.

Bundles and Vecs

Chisel Bundles are used to represent groups of wires that have named fields. They function in a manner similar to C's struct. In Chisel, Bundles are defined as a class, which is analogous to how classes are defined in languages like C++ and Java.

class FIFOInput extends Bundle {
  val rdy = Bool(OUTPUT) // Indicates if FIFO has space
  val data = Bits(INPUT, 32) // The value to be enqueued
  val enq = Bool(INPUT) // Assert to enqueue data
}

Chisel provides class methods for Bundles, which means that user-created bundles should "extend" the Bundle class to benefit from automatic connection creation (more on this later). In a Bundle, each field is assigned a name and defined using a constructor of the appropriate type, along with parameters that specify its width and direction. This allows you to create instances of FIFOInput, for example.

val jonsIO = new FIFOInput;

You can create nested Bundle definitions and construct hierarchies with them. These Bundles are typically used to define the interface of modules. The Bundle "flip" operator is employed to create an "opposite" Bundle concerning its direction.

class MyFloat extends Bundle {
  val sign = Bool()
  val exponent = Bits(width = 8)
  val significant = Bits(width = 23)
}
val x = new MyFloat()
Val xs = x.sign

class BigBundle extends Bundle {
  val myVec = Vec(5) { SInt(width = 23) } // Vector of 5 23-bit signed integers.
  val flag = Bool()
  val f = new MyFloat() // Previously defined bundle.
}

Bundle and Vec are class types used for organizing and grouping other types. The Vec class, in particular, represents an array of objects of the same type that can be indexed:

val myVec = Vec(5) { SInt(width = 23) } // Vec of 5 23-bit signed integers.
val third = myVec(3) // Name one of the 23-bit signed integers

Note: Vec is not a memory array; it functions as a collection of wires (or registers).
Both Vec and Bundle inherit from the class Data. Any object that ultimately inherits from Data can be represented as a bit vector in a hardware design.

Literals

Literals are values that you specify directly in your source code. Chisel provides type-specific constructors for defining literals.

Bits("ha") // hexadecimal 4-bit literal of type Bits
Bits("o12") // octal 4-bit literal of type Bits
Bits("b1010") // binary 4-bit literal of type Bits
SInt(5) // signed decimal 4-bit literal of type Fix
SInt(-8) // negative decimal 4-bit literal of type Fix
UInt(5) // unsigned decimal 3-bit literal of type UFix
Bool(true) // literals for type Bool, from Scala boolean literals
Bool(false)

By default, Chisel will determine the width of your literal to be the minimum necessary. Alternatively, you can provide a width value as a second argument if needed.

Bits("ha", 8) // hexadecimal 8-bit literal of type Bits, 0-extended
SInt(-5, 32) // 32-bit decimal literal of type Fix, sign-extended
SInt(-5, width = 32) // handy if lots of parameters

An error will be reported if the specified width value is insufficient.

Ports

A port refers to any Data object whose members have directions assigned to them. Port constructors enable the addition of directions during construction:

class FIFOInput extends Bundle {
  val rdy = Bool(OUTPUT)
  val data = Bits(width = 32, OUTPUT)
  val enq = Bool(INPUT)
}

The direction of an object can also be set during instantiation:

class ScaleIO extends Bundle {
  val in = new MyFloat().asInput
  val scale = new MyFloat().asInput
  val out = new MyFloat().asOutput
}

The methods asInput and asOutput ensure that all components of the data object are set to the specified direction. There are also other methods available for tasks like reversing direction, among others.

Modules

Modules are employed to establish hierarchy within the generated circuit, resembling modules in Verilog. Each module defines a port interface and interconnects subcircuits. These module definitions are essentially class definitions that extend the Chisel Module class.

class Mux2 extends Module {
  val io = new Bundle {
    val select = Bits(width=1, dir=INPUT);
    val in0 = Bits(width=1, dir=INPUT);
    val in1 = Bits(width=1, dir=INPUT);
    val out = Bits(width=1, dir=OUTPUT);
  };
  io.out := (io.select & io.in1) | (~io.select & io.in0);
}

The Module slot io is utilized to store the interface definition, which is of type Bundle. In the above example, io is associated with an unnamed Bundle using the := assignment operator. This Chisel operator connects the input on the left-hand side to the output of the circuit on the right-hand side .

Each module implicitly includes clock and reset signals in addition to the declared I/O ports.

Combinational Logic:

val wire = Wire(UInt(8.W))
val wireinit = WireInit(0.U(8.W))

The most basic type of state element that Chisel supports is a positive-edge-triggered register, which can be functionally instantiated as follows:

val reg = Reg(UInt(8.W))
val reginit = RegInit(0.U(8.W))

This circuit generates an output that replicates the input signal but with a one-clock-cycle delay. It is important to note that we do not need to explicitly specify the type of the register (Reg) because Chisel automatically infers it from the input when instantiated in this manner. In Chisel, the clock and reset signals are global and are implicitly included where necessary.

Hello World in Chisel

class Hello extends Module {
  val io = IO(new Bundle {
    val led = Output(UInt(1.W))
  })
  val CNT_MAX = (50000000 / 2 - 1).U;
  val cntReg  = RegInit(0.U(32.W))
  val blkReg  = RegInit(0.U(1.W))
  cntReg := cntReg + 1.U
  when(cntReg === CNT_MAX) {
    cntReg := 0.U
    blkReg := ~blkReg                                                                                                                                         
  }
  io.led := blkReg
}

---

Chisel Tutorial

Getting the Repository:

$ git clone https://github.com/ucb-bar/chisel-tutorial
$ cd chisel-tutorial
$ git checkout release

Before testing your system, ensure that you have sbt (the Scala build tool) installed.

$ sbt run

When running for the first time, an internet connection is needed to automatically download necessary components. Reference output:

[info] Set current project to chisel-tutorial (in build file:/tmp/chisel-tutorial/)
[info] Updating 
https://repo1.maven.org/maven2/edu/berkeley/cs/chisel-iotesters_2.12/maven-metadata.xml
  100.0% [##########] 2.1 KiB (8.7 KiB / s)
https://repo1.maven.org/maven2/edu/berkeley/cs/chisel-iotesters_2.12/1.4.1/chisel-iotesters_2.12-1.4.1.pom
  100.0% [##########] 2.9 KiB (16.1 KiB / s)
...
https://repo1.maven.org/maven2/edu/berkeley/cs/firrtl-interpreter_2.12/1.3.1/firrtl-interpreter_2.12-1.3.1.jar
  100.0% [##########] 444.2 KiB (1.5 MiB / s)
[info] Fetched artifacts of 
[info] Compiling 56 Scala sources to /tmp/chisel-tutorial/target/scala-2.12/classes ...
https://repo1.maven.org/maven2/org/scala-sbt/util-interface/1.3.0/util-interface-1.3.0.pom
  100.0% [##########] 2.7 KiB (16.4 KiB / s)
[info] Non-compiled module 'compiler-bridge_2.12' for Scala 2.12.10. Compiling...

This will generate and test a basic block called Hello that consistently produces the number 42 (represented as 0x2a). You should observe [success] in the final line of the output (from sbt) and PASSED on the preceding line, indicating that the block has successfully passed the test case.

Reference output:

test Hello Success: 1 tests passed in 6 cycles taking 0.004980 seconds

[info] [0.002] RAN 1 CYCLES PASSED
[success] Total time: 2 s, completed

source code: src/main/scala/hello/Hello.scala

Then, you can run the examples:

$ ./run-examples.sh FullAdder
$ ./run-examples.sh Adder4

source code: src/main/scala/examples/FullAdder.scala, src/main/scala/examples/Adder4.scala

$ ./run-examples.sh SimpleALU 

source code: src/main/scala/examples/SimpleALU.scala

Alternatively, you can go through all examples:

$ ./run-examples.sh all

Chisel Bootcamp

Take your hardware design to the next level, transitioning from instances to generators! This bootcamp will introduce you to Chisel, a hardware construction DSL developed at Berkeley and written in Scala. It will also provide you with a grasp of Scala as you progress, and it will focus on teaching Chisel through the concept of hardware generators.

Read the following materials: (required)

• From Chisel to Chips in Fully Open-Source
• Chisel Introduction
• Chisel Best Practices Intensive

Learn Chisel online!

• Please run the cell blocks by either pressing SHIFT+ENTER on your keyboard
• Caution: You might encounter unforeseen connectivity issues during the exercises. Therefore, it is advisable to install the required packages on your personal computer.

Method 1: Using Docker or nerdctl

:warning: The prebuilt Docker image ucbbar/chisel-bootcamp mentioned in Local Installation - Mac/Linux is only valid to x86-64 machines. Therefore, we have rebuilt the Docker image sysprog21/chisel-bootcamp to address known issues and support both x86-64 and Arm64.

Make sure you have Docker installed on your system.

• For Ubuntu Linux users, read Install Docker Engine on Ubuntu carefully.

  Alternatively, use nerdctl.

• For macOS users, if you prefer not to install Docker Desktop, which can be slow and resource-intensive, you can install the lima package. Lima provides access to a full Linux system and comes with built-in integration for nerdctl, offering Docker-compatible commands. Simply setup via the following commands:
  ​​​​$ brew install lima
  ​​​​$ limactl start
  

Run the following command: (for Linux and macOS + Docker Desktop)

$ docker run -it --rm -p 8888:8888 sysprog21/chisel-bootcamp

For macOS users who have already installed lima and run limactl start, you can run the command.

$ lima nerdctl run -it --rm -p 127.0.0.1:8888:8888 sysprog21/chisel-bootcamp

This will download a Dokcer image for the bootcamp and run it. The output will end in the following message:

    To access the notebook, open this file in a browser:
        file:///home/bootcamp/.local/share/jupyter/runtime/nbserver-6-open.html
    Or copy and paste one of these URLs:
        http://79b8df8411f2:8888/?token=LONG_RANDOM_TOKEN
     or http://127.0.0.1:8888/?token=LONG_RANDOM_TOKEN

Next, you can copy the URL provided above, which starts with http://127.0.0.1:8888/?, and paste it into your web browser to access the Jupyter Notebook-based interactive computing platform.

Method 2: Install packages manually

See Local Installation - Mac/Linux

:warning: You might suffer from unexpected problems with this method. Record and write down the issues accordingly.

Learning Chisel by doing!

:information_source: You should go through the following and complete the exercises:

• 1_intro_to_scala
• 2.1_first_module
• 2.2_comb_logic
• 2.3_control_flow
• 2.4_sequential_logic
• 2.5_exercise
• 2.6_chiseltest
• 3.1_parameters
• 3.2_collections
• 3.2_interlude
• 3.3_higher-order_functions
• 3.4_functional_programming
• 3.5_object_oriented_programming
• 3.6_types

---

Single-cycle RISC-V CPU

Single-cycle CPU completes the execution of one instruction within a single clock cycle. Because the clock cycle is fixed, all instructions must take the same amount of time to execute as the slowest instruction. This results in poor performance for a single-cycle CPU. A single-cycle CPU runs only one instruction at a time, and there are no conflicts between instructions, making it the simplest to implement.

The purpose of this experiment is to help everyone understand the basic structure of the CPU and how it executes instructions. We will first introduce some fundamental concepts, then proceed to build the data path and control unit step by step for instruction execution (there will be coding tasks to complete along the way, please remember to do so), ultimately constructing a simple single-cycle RISC-V processor, named MyCPU.

Implementation

Get the repository:

$ git clone https://github.com/sysprog21/ca2023-lab3
$ cd ca2023-lab3

:warning: Please be aware that the Scala code in this repository is not entirely complete, as the instructor has omitted certain sections for students to work on independently.

To simulate and run tests for this project, execute the following commands under the ca2023-lab3 directory.

$ sbt test

Alternately, run make.

If you have successfully filled in the implementation with your own efforts, you should encounter the following messages:

[info] FibonacciTest:
[info] Single Cycle CPU
[info] InstructionFetchTest:
[info] ByteAccessTest:
[info] InstructionDecoderTest:
[info] ExecuteTest:
[info] InstructionDecoder of Single Cycle CPU
[info] Single Cycle CPU
[info] InstructionFetch of Single Cycle CPU
[info] - should recursively calculate Fibonacci(10)
[info] - should fetch instruction
[info] - should store and load a single byte
[info] - should produce correct control signal
[info] Execution of Single Cycle CPU
[info] - should execute correctly
[info] QuicksortTest:
[info] Single Cycle CPU
[info] - should perform a quicksort on 10 numbers
[info] RegisterFileTest:
[info] Register File of Single Cycle CPU
[info] - should read the written content
[info] - should x0 always be zero
[info] - should read the writing content
[info] Run completed in 31 seconds, 280 milliseconds.

Naturally, if you have not made any efforts to improve this implementation, all test cases will fail as shown below:

[info] *** 6 TESTS FAILED ***
[error] Failed tests:
[error] 	riscv.singlecycle.InstructionDecoderTest
[error] 	riscv.singlecycle.ByteAccessTest
[error] 	riscv.singlecycle.InstructionFetchTest
[error] 	riscv.singlecycle.ExecuteTest
[error] 	riscv.singlecycle.FibonacciTest
[error] 	riscv.singlecycle.QuicksortTest
[error] (Test / test) sbt.TestsFailedException: Tests unsuccessful

If you want to run a single test, such as running only InstructionDecoderTest, execute the following command:

$ sbt "testOnly riscv.singlecycle.InstructionDecoderTest"

Single-cycle CPU architecture diagram

• Full
  

• Simplifed
  

Data Path

The path through which data moves between functional units is known as the data path. The elements situated along this route that perform operations on or hold data are called data path components, which include the ALU (Arithmetic-Logic Unit), general-purpose registers, memory, and so on. The data path illustrates the various pathways through which data transitions from one component to another.

The processor employs synchronous logic design with a clock.

Control Signals

As the name implies, control signals govern the data path. Whenever a choice must be made, the control unit is responsible for making the correct decision and dispatching control signals to the relevant data path components. For instance, should the ALU perform addition or subtraction? Are we reading from or writing to memory?

So, how does the controller determine what action to take? This primarily relies on the instruction currently in execution. In the RISC-V instruction format, the controller discerns the appropriate decisions by examining the opcode, funct3, and funct7 fields of the instruction, thus emitting the correct control signals. In the CPU schematic, the Decoder, ALUControl, and JumpJudge components can all be regarded as constituents of the control unit. They receive instructions and generate control signals. These control signals serve as guides within the data path to ensure the precise execution of instructions.

Combinational Units and State Units

In digital circuits, there are two main types of circuits: combinational logic and sequential logic. In CPU design, units composed of these two types of circuits are called combinational units and state units, respectively. In this experiment, only the registers belong to the sequential logic (memory is not within the scope of the CPU core), while the rest are combinational units.

• Combinational Logic

The output depends only on the current input and does not require a clock as a triggering condition. Inputs are reflected immediately in the outputs (ignoring delay).

Combinational logic processes data during clock cycles:

1. Between clock edges.
2. Taking input from state elements and providing output to state elements.
3. The clock period is determined by the longest delay in this process.

• Sequential (state) Logic

These units store state and use the clock as a triggering condition. Inputs are reflected in the outputs when the clock's rising edge arrives.

Register with write control:

• Only updates on the clock edge when the write control input is 1.
• Used when the stored value is required later

Overview of Implementation

The RISC-V CPU we are designing can execute a core subset of RISC-V instructions (RV32I):

1. Arithmetic and Logic Instructions: add, sub, slt, etc.
2. Memory Access Instructions: lb, lw, sb, etc.
3. Branch Instructions: beq, jar, etc.

We will divide the instruction execution into five different stages:

1. Instruction Fetch: Fetching the instruction data from memory.
2. Decode: Understanding the meaning of the instruction and reading register data.
3. Execute: Calculating the result using the ALU.
4. Memory Access (load/store instructions): Reading from and writing to memory.
5. Write-back (for all instructions except store): Writing the result back to registers.

Now, let's build data path components step by step according to the above stages, and then instantiate and connect these data path components in the CPU's top-level module. (The code related to this is located in the src/main/scala/riscv directory.)

Instruction Fetch

Code can be found in src/main/scala/riscv/core/InstructionFetch.scala.

What the instruction fetch stage does:

• Fetch the instruction from memory based on the current address in the PC register.
• Modify the value of the PC register to point to the next instruction.

  val pc = RegInit(ProgramCounter.EntryAddress)

  when(io.instruction_valid) {
    io.instruction := io.instruction_read_data
    // lab3(InstructionDecode)
    // ...

First, the value of the PC (program counter) register is initialized to the entry address of the program. When an instruction is valid, the current instruction pointed to by the PC is fetched. If a jump is required, the PC is directed to the jump address; otherwise, it is incremented to PC + 4.

:information_source: Please fill in the code at the // lab3(InstructionFetch) comment section in src/main/scala/riscv/core/InstructionFetch.scala so that it can pass the InstructionFetchTest unit test.

Instruction Decode

The code is located in src/main/scala/riscv/core/InstructionDecode.scala.

What the decode stage does:

• Read the opcode to determine instruction type and field lengths
• Read in data from all necessary registers
  • for add, read two registers
  • for addi, read one register
  • for jal, no reads are necessary
• Output control signals.

val rs1 = io.instruction(19, 15)
val rs2 = io.instruction(24, 20)

io.regs_reg1_read_address := Mux(opcode === Instructions.lui, 0.U(Parameters.PhysicalRegisterAddrWidth), rs1)
io.regs_reg2_read_address := rs2

The above code extracts the register operand numbers from the instruction. In all cases, except when the instruction is lui, register 1 is set to register 0, and register 2 is set to the values from the rs1_(19:15) and rs2_(24:20) fields of the instruction, respectively.

:information_source: Allocating a separate register for the constant 0 simplifies the RISC-V ISA, for example, allowing assignment instructions to be replaced with addition instructions using an operand of 0.

val immediate = MuxLookup(
  opcode,
  Cat(Fill(20, io.instruction(31)), io.instruction(31, 20)),
  IndexedSeq(
    InstructionTypes.I -> Cat(Fill(21, io.instruction(31)), io.instruction(30, 20)),
    InstructionTypes.L -> Cat(Fill(21, io.instruction(31)), io.instruction(30, 20)),

The above code extracts immediate values. Since the position of immediate values varies for different instruction types, it is necessary to differentiate instruction types using the opcode and then extract the corresponding immediate value.

object ALUOp1Source {
  val Register = 0.U(1.W)
  val InstructionAddress = 1.U(1.W)
}
// ...

io.ex_aluop1_source := Mux(
  opcode === Instructions.auipc || opcode === InstructionTypes.B || opcode === Instructions.jal,
  ALUOp1Source.InstructionAddress,  
  ALUOp1Source.Register
)

Taking ex_aluop1_source control signal as an example, this control signal determines the input for the first operand of the ALU. It assigns a value to ex_aluop1_source based on the opcode. When the instruction type is either auipc, jal, or B, ex_aluop1_source is set to 0, controlling the ALU's first operand input to be the instruction address. In other cases, ex_aluop1_source is set to 1, controlling the ALU's first operand input to be a register.

As you can see, the design of the decoding unit is also simple combinational logic. Knowing the mapping relationship between control signals and instructions is sufficient to complete it. Next, please complete the code for assigning values to the four control signals: ex_aluop2_source, io.memory_read_enable, io.memory_write_enable, and io.wb_reg_write_source.

control signals	meanings
ex_aluop2_source	ALU Input Source Selection
memory_read_enable	Memory Read Enable
memory_write_enable	Memory Write Enable
wb_reg_write_source	Write-Back Data Source Selection

:information_source: Please insert the code at the // lab3(InstructionDecode) comment section in src/main/scala/riscv/core/InstructionDecode.scala to make it pass the InstructionDecoderTest unit test.

Execution

The code is located in src/main/scala/riscv/core/Execute.scala.

What the execution stage does:

• Perform ALU computation.
• Determine if there is a branch.

val alu = Module(new ALU)
val alu_ctrl = Module(new ALUControl)
// ...
io.mem_alu_result := alu.io.result

The above code instantiates ALU and ALUControl within the Execute module. The specific ALU computation logic is implemented in the ALU module, and here, you only need to assign values to the input ports of ALU. The code for ALU can be found in src/main/scala/riscv/core/ALU.scala.

:information_source: Please insert the code at the // lab3(Execute) comment section in src/main/scala/riscv/core/Execute.scala to make it pass the ExecuteTest unit test.

io.if_jump_flag := 
  (opcode === Instructions.jal) ||
  (opcode === Instructions.jalr) ||
  (opcode === InstructionTypes.B) && 
  MuxLookup(
    funct3,
    false.B,
    IndexedSeq(
      InstructionsTypeB.beq -> (io.reg1_data === io.reg2_data),
      // ...
  )

The above code determines whether a jump should be taken. The logic for determining a jump is as follows: if it is an unconditional jump instruction, it jumps directly (e.g., jal and jalr instructions in the code above). If it is a branch instruction, it checks the corresponding jump condition to decide whether to jump (e.g., the beq instruction in the code above, which jumps when io.reg1_data is equal to io.reg2_data). When a jump is taken, the control signal if_jump_flag is set to 1.

Memory Access

The code is located in src/main/scala/riscv/core/MemoryAccess.scala.

Only load/store instructions have a memory access stage. The other instructions remain idle during this stage or skip it all together. In this stage, reading loads data from memory into registers, and writing stores data from registers into memory.

In the decode stage, if it is an L-type (I-type subtype) instruction, memory_read_enable is set to 1, and if it is an S-type instruction, memory_write_enable is set to 1. These two control signals determine whether reading or writing should occur in this stage.

val mem_address_index = io.alu_result(log2Up(Parameters.WordSize) - 1, 0).asUInt

First, the address for reading or writing memory is obtained.

When io.memory_read_enable is true:
The code reads data from the memory bus and processes it differently based on the instruction type (e.g., lb sign-extends, lbu zero-extends, lh reads two bytes, etc.). The processed data is then assigned to io.wb_memory_read_data for writing back.

.elsewhen(io.memory_write_enable) {
    io.memory_bundle.write_data := io.reg2_data
    io.memory_bundle.write_enable := true.B
    io.memory_bundle.write_strobe := VecInit(Seq.fill(Parameters.WordSize)(false.B))
    when(io.funct3 === InstructionsTypeS.sb) {
      io.memory_bundle.write_strobe(mem_address_index) := true.B
      io.memory_bundle.write_data := io.reg2_data(Parameters.ByteBits, 0) << (mem_address_index << log2Up(Parameters.ByteBits).U)
    }.elsewhen(io.funct3 === InstructionsTypeS.sh) {
    // ...

When io.memory_write_enable is true:
The code writes data to memory, and the data is processed differently based on the instruction type (e.g., sw takes 32 bits, sh takes 16 bits, and sb takes 8 bits).

Write-Back

The code is located in src/main/scala/riscv/core/WriteBack.scala.

In the write-back stage, the computed data or data read from memory is written into registers.

The write-back module is essentially a multiplexer, and the code is very simple. However, it raises an interesting question: the write-enable signal is generated in the decode stage, but at that point, the correct write-back data has not been calculated (or read from memory). So, will incorrect write-back data be written into the register file, and why?

Combining into a CPU

The code is located in src/main/scala/riscv/core/CPU.scala.

We have implemented all the components required to build the CPU. Now, we need to instantiate and connect these components together according to the single-cycle CPU architecture diagram.

class CPU extends Module {
  val io = IO(new CPUBundle)
  // CPUBundle is the channel for data exchange between the CPU and peripherals like memory.

  val regs = Module(new RegisterFile)
  val inst_fetch = Module(new InstructionFetch)
  val id = Module(new InstructionDecode)
  val ex = Module(new Execute)
  val mem = Module(new MemoryAccess)
  val wb = Module(new WriteBack)

  ..
  // Here, we instantiate modules for different execution stages.
  inst_fetch.io.jump_address_id := ex.io.if_jump_address
  inst_fetch.io.jump_flag_id := ex.io.if_jump_flag
  // Taking the two lines above as an example, you can see the corresponding connections in the CPU schematic.
}

In the code above, we instantiate modules for various execution stages and then establish connections between them to create the CPU.

Please observe the input port code of the Execute module and the CPU architecture diagram, and fill in the connections between the inputs of the Execute module and the outputs of other modules.

:information_source: Please insert the code at the // lab3(CPU) comment section in src/main/scala/riscv/core/CPU.scala to make it pass the corresponding unit tests.

Functional Test

The process by which sbt test activates the test cases for validating the CPU implementation relies on Chiseltest, an extensive testing and formal verification library designed for Chisel-based RTL (Register-Transfer Level) designs. Chiseltest places a strong emphasis on creating tests that are lightweight, promoting minimal boilerplate code, easy to read and write for enhanced understandability, and conducive to test code reuse through composability.

Provided a C program that computes the Fibonacci sequence, its source code is presented below.

static int fib(int a) {
    if (a == 1 || a == 2) return 1;
    return fib(a - 1) + fib(a - 2);
}
int main() {
    *((volatile int *) (4)) = fib(10);
    return 0;
}

File: csrc/fibonacci.c

Within the main function, the line *((volatile int *) (4)) = fib(10) stores the Fibonacci(10) result in the memory address 4, which can be later verified using a Chiseltest-based test case.

class FibonacciTest extends AnyFlatSpec with ChiselScalatestTester {
  behavior.of("Single Cycle CPU")
  it should "calculate recursively fibonacci(10)" in {
    test(new TestTopModule("fibonacci.asmbin")).withAnnotations(TestAnnotations.annos) { c =>
      for (i <- 1 to 50) {
        c.clock.step(1000)
        c.io.mem_debug_read_address.poke((i * 4).U) // Avoid timeout
      }

      c.io.mem_debug_read_address.poke(4.U)
      c.clock.step()
      c.io.mem_debug_read_data.expect(55.U)
    }
  }                                
}

File: src/test/scala/riscv/singlecycle/CPUTest.scala

Given that Fibonacci(10) is known to be 55, this test case straightforwardly verifies the content of the designated memory region after our CPU executes the instructions.

Waveform

Before burning the board for verification, you can perform another round of testing using waveform simulation.

Generating Waveform Files During Testing:
While running tests, if you set the environment variable WRITE_VCD to 1, waveform files will be generated.

$ WRITE_VCD=1 sbt test

Afterward, you can find .vcd files in various subdirectories under the test_run_dir directory. You can open them using GTKWave.

On the left side of the interface, there is a tree-like structure organized by modules. To add a signal to the window, right-click and select Insert from the menu.

Verilator

Verilator is a tool that compiles Verilog and SystemVerilog sources into highly optimized C++ or SystemC code, which can be used for verification and modeling in C++ or SystemC testbenches.

For more details, please refer to the official Verilator website and its manual.

Why do we choose Verilator? It is a high-performance, open-source Verilog/SystemVerilog simulator. While it is powerful and fast, it is not a direct replacement for event-based simulators such as Modelsim and Vivado Xsim. Verilator operates on a cycle-based simulation model, which means it does not simulate exact circuit timing within a single clock cycle and may not capture intra-period glitches. While this approach has its advantages, it also has limitations compared to other simulators.

If you want to quickly test your own written programs, you can use Verilator for simulation. The main simulation function is already written and located in verilog/verilator/sim_main.cpp. After the first run and every time you modify the Chisel code, you need to execute the following command in the project's root directory to generate Verilog files:

$ make verilator

:warning: If you don't modify the Scala code as mentioned earlier, the Verilog generation will fail.

After compilation, an executable file named verilog/verilator/obj_dir/VTop will be generated. This executable file can take parameters to run different code files. Here are the parameters and their usage:

Parameter	Usage
-memory	Specify the size of the simulation memory in words (4 bytes each). Example: -memory 4096
-instruction	Specify the RISC-V program used to initialize the simulation memory. Example: `-instruction src/main/resources/hello
.asmbin`
-signature	Specify the memory range and destination file to output after simulation. Example: -signature 0x100 0x200 mem.txt
-halt	Specify the halt identifier address; writing 0xBABECAFE to this memory address stops the simulation. Example: -halt 0x8000
-vcd	Specify the filename for saving the simulation waveform during the process; not specifying this parameter will not generate a waveform file. Example: -vcd dump.vcd
-time	Specify the maximum simulation time; note that time is twice the number of cycles. Example: -time 1000

For example, to load the hello.asmbin file, simulate for 1000 cycles, and save the simulation waveform to the dump.vcd file, you can run:

$ ./run-verilator.sh -instruction src/main/resources/hello.asmbin
-time 2000 -vcd dump.vcd

:walking: Keep in mind that a time value of 2000 corresponds to simulating 1000 cycles.

Then, run gtkwave dump.vcd to check its waveform.

You can observe that the signal io_instruction begins with 000000000 and 00001137. In the meantime, let's verify the hexadecimal representation of hello.asmbin:

$ hexdump src/main/resources/hello.asmbin | head -1

Its output:

0000000 1137 0000 1097 0000 80e7 8b00 006f 0000

It aligns with the expected waveform.

:walking: You may wonder: why are not the modules/IO ports/registers defined in Chisel visible in the generated Verilog code (or waveform)?

This occurs because Chisel initially generates FIRRTL code and subsequently applies optimization steps, including logical simplification, constant propagation, and dead code elimination, to the FIRRTL code. The final Verilog code is then generated based on the optimized FIRRTL representation. If the modules/IO ports/registers you created in Chisel do not appear in the generated Verilog code, it is recommended to check for proper module connections and potential logic issues that could lead to constant values in certain registers, among other possible reasons.

Prepare Programs to Run on MyCPU

If no specific argument is provided to the GNU toolchain, the default linker script is utilized for the linking process. However, for more granular control over the linking process, it is possible to create a custom linker script. You can designate a linker script using the -T option, as demonstrated below:

$ riscv-none-elf-gcc -T link.lds hello.o -o hello

The content of the linker script would look something like this:

OUTPUT_ARCH( "riscv" )
ENTRY(_start)

SECTIONS
{
  . = 0x00001000;
  .text : { *(.text.init) *(.text.startup) *(.text) }
  .data ALIGN(0x1000) : { *(.data*) *(.rodata*) *(.sdata*) }
  . = 0x00100000;
  .bss : { *(.bss) }
  _end = .;
}

File: csrc/link.lds

The first line of the linker script specifies the output instruction format, which is RISC-V in this case. The second line specifies the program's entry address, which is the _start function. Starting from the third line, it defines the positions of various segments in the program. For example, the .text segment starts at address 0x00001000, the .data segment starts after .text and is aligned to address 0x1000, and the .bss segment starts at address 0x00100000. The last line specifies the program's end address, denoted as _end.

To regenerate the RISC-V programs utilized for unit tests, change to the csrc directory and run the make update command. Ensure that the $PATH environment variable is correctly configured to include the GNU toolchain for RISC-V.

$ cd csrc
$ make update

See Lab2: RISC-V RV32I[MACF] emulator with ELF support.

ELF (Executable and Linkable Format) is an executable file format commonly used in Linux systems. While a detailed understanding of the ELF format is not necessary, having a general idea of its structure can be helpful for this experiment.

An ELF file stores metadata about a program, including the entry address, segment information, symbol information, and more. Among these, segment information is crucial as it contains the program's code and data. Typically, the code segment is named .text, and the data segment is named .data. These segments are loaded into memory by the operating system for program execution and data access.

In our experiment, since we do not have an operating system, we use Chisel code to specify the CPU's entry address and load the code and data segments into memory for direct program execution. These code and data segments are flashed into the FPGA logic as initialization data during the synthesis phase. The InstructionROM module is responsible for generating this initialization data, and the ROMLoader module handles the loading of data into memory. After this data copying process is complete, the CPU can start executing the program.

The process of generating an executable file for the CPU involves the following steps:

1. Only the code and data segments from the ELF file are required, while other segments can be disregarded. In the linker script, these two segments are allocated to contiguous addresses to streamline the implementation.
2. The code segment commences from address 0x1000, with the space before it reserved for the program's stack.
3. The objcopy tool is employed to duplicate the code and data segments into a distinct file, resulting in a file containing solely binary code and data.

Reference

• (System)Verilog to Chisel Translation for Faster Hardware Design
• Digital Design with Chisel
• Davis In-Order (DINO) CPU models
• Online RISC-V instruction interpreter