Assignment 3: Single-cycle RISC-V CPU

contributed by AgainTW

Environment setup

• My environment
  • OS: windows 11
  • CPU: 11th Gen Intel® Core™ i5-11400H @ 2.70GHz

Install cygwin

• Install apt-cyg.
• Install dependency library (equal to build-essential) in Cygwin.

$ apt-cyg install make gcc-core gcc-g++ patch bzip2 perl tar xz
$ apt-cyg install git automake cmake python3-devel
$ apt-cyg install flex bison glade-python

Install verilator gtkwave

• Go to github to download the compressed file.
• Unzip then install.

$ cd "address about .gz file"
$ tar vxfz verilator-5.018.tar.gz
$ cd verilator-5.018

• Compile

$ autoconf
$ ./configure
$ make -j

• Solve the "python3 bug" and execute ./configure again.
  • Go to the python installation address, copy "python.exe" to the same address and rename it to "python3.exe".

Annotation: Installing some libraries using apt-cyg will cause incorrect environment variable settings (such as "bison" library), so it is recommended to re-install using the cygwin installation file.

Install gtkwave

• Go to Official website download "gtkwave-gtk3-3.3.114".
• Unzip then install.

$ cd "address about .gz file"
$ tar vxfz gtkwave-gtk3-3.3.114.tar.gz
$ cd gtkwave-gtk3-3.3.114

• Compile

$ autoconf
$ ./configure

• Then you will find that you don’t know why it failed, but don’t worry !

Annotation: I additionally installed tcl, tk, gperf, libz, libbz2, xz-devel, LZMA, libgtk2

• Download and unzip "gtkwave-3.3.100-bin-win64" then it works !

Install sdkman

• It was originally used to install the Java environment, but using sdkman will not find a JDK compatible with win11.

$ curl -s "https://get.sdkman.io" | bash

• As a result, I ended up downloading JDK11 from here.

Annotation: I additionally installed unzip、zip

Install sbt & JDK

• Download the msi file of sbt and install it.
  • You can use CTRL+C to close sbt in cygwin.
• You can successfully run chisel using JDK11.

$ cd "address_of_your_file\chisel\chisel-tutorial"

• Reference output about running "sbt test".

again@DESKTOP-7MC8UTU ..\chisel\chisel-tutorial
$ sbt run
[info] Loading project definition from ..\chisel\chisel-tutorial\project
[info] Loading settings for project chisel-tutorial from build.sbt ...
[info] Set current project to chisel-tutorial (in build file:/../chisel/chisel-tutorial/)
[info] running hello.Hello
[info] [0.000] Elaborating design...
[info] [0.047] Done elaborating.
Computed transform order in: 125.6 ms
Total FIRRTL Compile Time: 269.7 ms
End of dependency graph
Circuit state created
[info] [0.000] SEED 1701862250275
test Hello Success: 1 tests passed in 6 cycles taking 0.008166 seconds
[info] [0.000] RAN 1 CYCLES PASSED
[success] Total time: 3 s, completed 2023年12月6日 下午7:30:52

• Reference output about running "FullAdder".

again@DESKTOP-7MC8UTU ../chisel/chisel-tutorial
$ ./run-examples.sh FullAdder
[sbt_options] declare -a sbt_options=()
[process_args] java_version = '11'
[copyRt] java9_rt = 'C:\Users\again\.sbt\1.0\java9-rt-ext-microsoft_11_0_21/rt.jar'
# Executing command line:
java
-Dfile.encoding=UTF-8
-Xms1024m
-Xmx1024m
-Xss4M
-XX:ReservedCodeCacheSize=128m
-Dsbt.script=/cygdrive/c/Program%20Files%20(x86)/sbt/bin/sbt
-Dscala.ext.dirs=C:\Users\again\.sbt\1.0\java9-rt-ext-microsoft_11_0_21
-Djline.terminal=jline.UnixTerminal
-Dsbt.cygwin=true
-jar
"C:\Program Files (x86)\sbt\bin\sbt-launch.jar"
"test:runMain examples.Launcher FullAdder"

[info] Loading project definition from ..\chisel\chisel-tutorial\project
[info] Loading settings for project chisel-tutorial from build.sbt ...
[info] Set current project to chisel-tutorial (in build file:/../chisel/chisel-tutorial/)
[warn] Multiple main classes detected.  Run 'show discoveredMainClasses' to see the list
[info] running examples.Launcher FullAdder
Starting tutorial FullAdder
[info] [0.000] Elaborating design...
[info] [0.912] Done elaborating.
Computed transform order in: 265.5 ms
Total FIRRTL Compile Time: 405.6 ms
file loaded in 0.0360903 seconds, 13 symbols, 8 statements
[info] [0.000] SEED 1701862629796
test FullAdder Success: 8 tests passed in 9 cycles in 0.011595 seconds 776.17 Hz
[info] [0.000] RAN 4 CYCLES PASSED
Tutorials passing: 1
[success] Total time: 3 s, completed 2023年12月6日 下午7:37:11

Java version switching

• Use Configure Java to change version

Chisel

How to use

• Path to move to chisel folder.
• Use sbt command to use chisel.

Directory structure

• In sbt’s terminology, the “base directory” is the directory containing the project.
• sbt uses the same directory structure as Maven for source files by default (all paths are relative to the base directory):
  • Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.

src/
├── main/
│   ├── resources/
│   │   └── <files to include in main jar here>
│   ├── scala/
│   │   └── <main Scala sources>
│   ├── scala-2.12/
│   │   └── <main Scala 2.12 specific sources>
│   └── java/
│       └── <main Java sources>
└── test/
    ├── resources/
    │   └── <files to include in test jar here>
    ├── scala/
    │   └── <test Scala sources>
    ├── scala-2.12/
    │   └── <test Scala 2.12 specific sources>
    └── java/
        └── <test Java sources>

Create the scala project environment

• If you want to create a scala project, usesbt new to add a new template.

Create the Chisel project environment

• If you want to create a chisel project, usegit to add a new template.

git clone https://github.com/freechipsproject/chisel-template

• But I have not yet solved the integrated use of "verilator" and "gtkwave" under the windows OS.

Use jupyter as the project environment

• Reference information
• Steps:
  • You need to execute it under cygwin for the first time, but after installation, you can use CMD or cygwin directly.
  • These steps can be made into a "shell script" and executed in cygwin.
    • Note the difference between linux newline and windows newline.
    • Note the difference between source a.sh and sh a.sh.

1. Create jupyter chisel project.

$ cd "target folder"
$ git clone https://github.com/sysprog21/chisel-bootcamp

$ cd chisel-bootcamp
$ export SCALA_VERSION=2.12.10
$ export ALMOND_VERSION=0.9.1
$ export COURSIER_CACHE=coursier_cache
$ export JUPYTER_CONFIG_DIR=jupyter/config
$ export JUPITER_DATA_DIR=jupyter/data
$ mkdir -p $JUPYTER_CONFIG_DIR/custom
$ cp source/custom.js $JUPYTER_CONFIG_DIR/custom/

2. Add required packages (here I only list the ones I have not installed).

$ apt-cyg install graphviz

3. Add scala kernel to jupyter

$ mkdir coursier_cache
$ curl -Lo coursier https://git.io/coursier-cli && chmod +x coursier
$ ./coursier bootstrap \
    -r jitpack \
    -i user -I user:sh.almond:scala-kernel-api_2.12.11:0.10.0 \
    sh.almond:scala-kernel_2.12.11:0.10.0 \
    -o almond
$ ./almond --install --id scala_2_12_8  --display-name "Scala 2.12.8"

4. Run

$ jupyter notebook

visualize()

• An error will be reported when using thevisualize()function, but the image is still generated and saved in the diagrams subfolder.
  • But under cygwin, not only will errors occur, but the circuit diagram cannot even be generated.
• When using this function,.jsonand.firfiles will be generated under the .ipynb.
• Because I installed graphviz in cmd, I need to use cmd to execute jupyter to generate the structure diagram.

Chisel bootcamp

Set and download bootcamp resource by docker

• Reference document.
• Remember to open docker desktop first before using the docker command in CMD.
• Using the original bootcamp will cause error, but using the image provided by sysprog21 will not cause errors.

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

docker and bluestack(32 bits) conflicting bugs

• Because both programs require the use of virtualization technology, they cannot exist at the same time (in win11).
• Docker requires "Hyper-V" and "Memory integrity" option in win11.
• Bluestack(32 bits) does not require "Hyper-V" and "Memory integrity" option in win11.
• Therefore, "Hyper-V" and "Memory Integrity" options need to be enabled when using Docker, and the computer should be restarted. Conversely, when using Bluestacks (32 bits), "Hyper-V" and "Memory Integrity" options need to be disabled, and the computer should be restarted as well.
• How to turn off or turn on the "Hyper-V" and "Memory integrity" options, please refer to: website1, website2
• I searched DOCKER COMMUNITY FORUMS, but there is no discussion of this issue type. Therefore I created a new discussion and share it in DOCKER COMMUNITY FORUMS.

Chisel bootcamp note

• Using technology supported by Binder ,we can remotely access the Chisel environment and learning content customized by bootcamp authors.
  • However, it will be subject to connection quality and some technical limitations, such as being unable to stay on the Chisel bootcamp page for a long time.
• With the beginning of Chisel 3.5, the launch of Scala 2.12, and the modification and maintenance of some experimental content, the content on Chisel bootcamp has some problem and is not exhaustive, such as:
  • bug about .asTypeOf()
  • Syntax error in call module
  • Imperfect AsyncFIFO generator example
  • Experiment and analysis of Arbiter
• Therefore, based on Chisel bootcamp, I wrote a series of study notes. In addition to recording my learning experience, I also added about a quarter of the new content. These include:
  • Bug resolution for version differences
  • Analysis of verilog code
  • reasonable generator
  • Additional Chisel content and experiments
  • Hardware related supplements, etc.

• Currently, only Chinese content is supported. English version content will be added after proofreading in the future.
• Because FIRRTL is currently in the version maintenance, firrtl.Compiler cannot compile the modified FIRRTL normally. Therefore, the FIRRTL-related content in Chapters 7 and 8 is still being established and i still attempts to resolve related issues.

• My bootcamp notes
  • 【1】Scala and Chisel syntax in short
  • 【2】Combinational Circuits, Sequential Circuits, and Control Flow
  • 【3】Generators
  • 【4】Higher-order functions and design
  • 【5】object-oriented design
  • 【6】Generators: Types
  • 【7】Introduction to FIRRTL
  • 【8】FIRRTL Application

First CPU

Get the teaching repository

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

Complete CPU

• InstructionFetch
  • When the instruction of the previous cycle is a jump instruction, the ID decoding of the previous cycle jump_flag_id is true, and the jump_flag_id result is input to the IF in this cycle, therefore:
• InstructionDecode
  • Determine the signals of memory_read_enable and memory_write_enable according to the opcode type.
• Execute
  • Use chisel default Mux hardware to determine the ALU data input based on aluop1_source and aluop2_source from ID respectively.
  • The function control of ALU is determined by alu_ctrl
• CPU
  • Complete wiring of EXE

Test

Test using sbt

• sbt run

[info] welcome to sbt 1.9.7 (Microsoft Java 11.0.21)
[info] loading settings for project ca2023-lab3_sysprog21-build from plugins.sbt ...
[info] loading project definition from C:\AG\course notes\112_1\閮?璈?瑽HW3\RV32 bootcamp\ca2023-lab3_sysprog21\project
[info] loading settings for project root from build.sbt ...
[info] set current project to mycpu (in build file:/C:/AG/course%20notes/112_1/閮?璈?瑽?HW3/RV32%20bootcamp/ca2023-lab3_sysprog21/)
[info] running board.verilator.VerilogGenerator
[success] Total time: 4 s, completed 2024撟???5??銝?5:40:52

• sbt test

• Due to unresolved reasons, the project can complete the functional testing of each component, but cannot complete the execution of the program.

[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 4 seconds, 145 milliseconds.
[info] Total number of tests run: 9
[info] Suites: completed 7, aborted 0
[info] Tests: succeeded 6, failed 3, canceled 0, ignored 0, pending 0
[info] *** 3 TESTS FAILED ***
[error] Failed tests:
[error]         riscv.singlecycle.ByteAccessTest
[error]         riscv.singlecycle.FibonacciTest
[error]         riscv.singlecycle.QuicksortTest
[error] (Test / test) sbt.TestsFailedException: Tests unsuccessful
[error] Total time: 5 s, completed 2024撟???5??銝?5:40:41

Test in jupyter environment

• Due to the error mentioned above, I switched to using jupyter to test functions of the hardware.
  • This test method requires the input of binary instructions, but an assembler can be written to realize the input of the assembly language.

test(new CPU) { c =>
    def printReg() = {
        for(i <- 0 until Parameters.PhysicalRegisters){
            c.io.debug_read_address.poke(i.U)
            print(s"${c.io.debug_read_data.peek()} ")
            if(i%8==7) println()
        }
        println()
    }

    // Init
    printReg()
    c.clock.step(1)

    // I1  addi x1, x1, 15
    c.io.instruction_valid.poke(true.B)
    c.io.instruction.poke("b00000000111100001000000010010011".U)
    c.clock.step(1)
    printReg()

    // I2  addi x2, x2, 5
    c.io.instruction_valid.poke(true.B)
    c.io.instruction.poke("b00000000010100010000000100010011".U)
    c.clock.step(1)
    printReg()

    // I2  add x3, x2, x1
    c.io.instruction_valid.poke(true.B)
    c.io.instruction.poke("b00000000000100010000000110110011".U)
    c.clock.step(1)
    printReg()
}

Elaborating design...
Done elaborating.
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 

UInt<32>(0) UInt<32>(15) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 

UInt<32>(0) UInt<32>(15) UInt<32>(5) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 

UInt<32>(0) UInt<32>(15) UInt<32>(5) UInt<32>(20) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 
UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) UInt<32>(0) 

test CPU Success: 0 tests passed in 6 cycles in 0.124751 seconds 48.10 Hz

Tips

Note when using jupyter as a working environment

1. Need to set the "path" to read the dependent database.

val path = System.getProperty("user.dir") + "/source/load-ivy.sc"
interp.load.module(ammonite.ops.Path(java.nio.file.FileSystems.getDefault().getPath(path)))

2. Jupyter kernel scala is partially different from general scala in objects, so pay attention to the "import of objects".
   • For example, scala’s ArraySeq is defined in immutable, but jupyter kernel scala’s ArraySeq is defined in mutable.

import scala.collection.immutable
import scala.collection.mutable.{ArraySeq => mutable_ArraySeq}

3. Some functions are used in different ways, such as the use of ceil.

// Original: Can be compiled in sbt, but cannot be compiled successfully in jupyter
val WordSize         = Math.ceil(DataBits / ByteBits).toInt
// After modification, it can be compiled in jupyter
val WordSize         = ((DataBits / ByteBits).ceil).toInt

Advantages/disadvantages of using jupyter as a working environment

• Advantages
  • You can use convenient functions such as getVerilog() and visualize().
  • You can test and get results in a timely manner without completing the complete hardware or dependent objects.
• Disadvantages
  • Unfriendly to import other packaged items.
  • Not friendly to calling external functions, such as gtkwave.
  • Unfriendly to chisel, FIRRTL, java and scala version control.
  • Not easy to perform system-level simulations.

Reference

main

1. Assignment3: single-cycle RISC-V CPU
2. Lab3: Construct a single-cycle RISC-V CPU with Chisel
3. kc71486:Assignment3

Install cygwin and debug

1. Install cygwin on Win10 and add apt-cyg
2. WGET command not working in Cygwin
3. Getting started with Cygwin
4. Setting sudo
5. How to install build-essential in Cygwin?

Install Verilator and debug

1. Install Verilator on windows
2. python3 bug

Install sdkman and debug

1. Install sdkman

Install sbt & JDK and debug

1. Install sbt on Windows
2. Install JDK on Windows
3. Install JDK 11
4. JDK environment settings in sublime text
5. Scala environment settings in sublime text
6. sbt bug
7. Java version switching bug
8. Configure Java
9. Use Configure Java to change version

Docker and bluestack (32 bits) conflicting bugs

1. Enable or disable Windows Hyper-V option
2. Enable or disable Windows Hyper-V option
3. Enable or disable Windows memory integrity option
4. Enable or disable Windows memory integrity option

Bootcamp resource

1. Jupyter Notebook Kernels: How to Add, Change, Remove

sbt

1. Directory structure of sbt
2. SCALA introductory tutorial
3. Build and test SCALA projects using SBT

Chisel

1. Chisel github
2. chisel-template
3. getVerilog() function