Appendices
F
Setting Up the RISC-V Processor Design Project Repos-
itory
Version:
git changeset: 170:373da60b63aa0705868d6a651c2d72842dcea0bc,
Fri Apr 10 14:52:08 2020 +0100
Debugging is like alien abduction. Large blocks of time disappear, for
which you have no explanation.
— Unknown source.
One of the goals of the RISC-V processor design project is to provide you
with the experience setting up all the tools you will need in both simulating
and designing the processor if you were to choose to do so on your own at
a future time: All the tools we will use are open source
1
. The time required
1
You can in principle set
the tools up on your own
PC or mac but the instruc-
tor and demonstrators are
not under any obligation
to provide any additional
support if you choose to do
so.
to complete the installation is factored into the design of the project and you
are expected to perform these installation tasks as a team, on your group’s
workstation in the lab. The instructions below are for the workstations you
will have access to in the lab and work reliably for Ubuntu 18.04.2.
Hint: some of the tools take a while to build, so your team should be able
to have several compilation steps running at the same time (e.g., building the
Sunflower toolchain while also building YoSys.)
F.1 Intended Learning Outcomes
By the end of this chapter, you should be able to:
1. Find your way around the Unix shell, including navigating using
cd, pwd,
and so on, editing files using vi, reading man pages for Unix commands,
and composing Unix commands using pipes.
4 phillip stanley-marbell
2. Identify the software and hardware tools you need for setting up a new
hardware design in Verilog for the iCE40 FPGA.
3. Install the open-source tools for the iCE40 FPGA, from scratch, on your
own PC.
4. Identify which local file changes you need to make to get the open-source
tools setup, as well as to track those local changes using git.
F.1.1 Things to look out for
Concepts people sometimes get confused by in this chapter include:
1. The difference between the concept of synthesis (performed by Yosys) and
place-and-route (performed by ArachnePNR and NextPNR).
2. The difference between Sunflower (a whole-embedded-system emulator)
and Narvie (a command-line interface for RISC-V instruction emulation in
software as well as emulation on the iCE40 FPGA).
F.1.2 The muddiest point
As you go through the material in this chapter, think about the following two
questions and note your responses for yourself or using the annotation tools
of the online version of the chapter. You will have the opportunity to submit
your responses to these questions at the end of the chapter:
1. What is least clear to you in this chapter? (You can simply list the section
numbers or write a few words.)
2. What is most clear to you in this chapter? (You can simply list the section
numbers or write a few words.)
F.1.3 Learning outcomes pre-assessment
Complete the following
quiz to evaluate your prior knowledge of the material
for this chapter.
F.2 Getting access to the server
All the tools we will use for this project are accessible from the command
line. You will access them on a public server which you can connect to using
ssh. To log into the shared server, you will need to provide your ssh public
key so that you can log in. If you do not already have an
ssh key pair, you
can generate one using:
$ ssh-keygen -t rsa
foundations of embedded systems 5
When the process completes, you will see a message such as:
Your identification has been saved in /home/someuser/.ssh/id
_
rsa.
Your public key has been saved in /home/someuser/.ssh/id
_
rsa.pub.
Provide your public key
2
(id
_
rsa.pub from the .ssh directory in your home
2
The public key, not the
private key.
directory).
You will need to be familiar with the Unix command line to use the open-
source FPGA tools. The following
video in the online resources provides a
quick introduction to the bare essentials that you will need.
F.3 Setting up the repository
First, use the command
git clone -recursive to clone the RISC-V processor
design project repository:
$ git clone --recursive https://github.com/f-of-e/f-of-e-tools.git
Once you have the repository cloned, edit the file
f-of-e-tools/tools/sunflower/conf/setup.conf
to change the value of the SUNFLOWERROOT variable in the configuration file to
point to the location of the pre-compiled Sunflower tools on the server:
SUNFLOWERROOT = /data/f-of-e-tools/tools/sunflower
All the tools are already installed on the server and you do not need to go
through the installation process on the server. The instructions are only for
you to be able to install the tools on your own after the project is over.
Hint: When you begin the installation process below, at any point in time,
you can use
git status to see what files you have changed in the closest
enclosing repository and you can use git diff to see what changes you have
made to those files.
F.4 Compiling IceStorm
Change directory into the
tools/icestorm directory of the top-level of your
clone of the course repository and type sudo make install. You should see
something like:
$ sudo make install
make -C icebox all
python3 icebox
_
chipdb.py -3 > chipdb-384.new
mv chipdb-384.new chipdb-384.txt
python3 icebox
_
chipdb.py > chipdb-1k.new
mv chipdb-1k.new chipdb-1k.txt
python3 icebox
_
chipdb.py -8 > chipdb-8k.new
mv chipdb-8k.new chipdb-8k.txt
python3 icebox
_
chipdb.py -5 > chipdb-5k.new
mv chipdb-5k.new chipdb-5k.txt
python3 icebox
_
chipdb.py -4 > chipdb-lm4k.new
mv chipdb-lm4k.new chipdb-lm4k.txt
...
6 phillip stanley-marbell
The compilation process will take about four minutes.
F.5 Compiling NextPNR
The program
nextpnr is the tool that determines how to fit your design into
the FPGA (placing components and routing wires: place and route or pnr).
You need to complete installing IceStorm before attempting this step. If
you are the team member tasked with installing this step, you need to wait
until the previous step of installing icestorm is complete. Change directory
into the
tools/nextpnr directory of the top-level of your clone of the course
repository and run the following:
$ cmake -DARCH=ice40 .; make; sudo make install
-- The C compiler identification is AppleClang 10.0.1.10010046
-- The CXX compiler identification is AppleClang 10.0.1.10010046
-- Check for working C compiler: cc
-- Check for working C compiler: cc -- works
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
...
The compilation process will take about 15 minutes. On Amazon Linux, you
will instead need to run the following:
$ cmake3 -DARCH=ice40 -DBUILD
_
GUI=OFF -DBUILD
_
PYTHON=OFF -DBUILD
_
HEAP=OFF . ; make; sudo make install
...
F.6 Compiling Arachnepnr
The program
arachnepnr is the tool that determines how to fit your design
into the FPGA (placing components and routing wires: place and route or
pnr). ArachnePNR and NextPNR are different implementations of the same
concept and you will have the opportunity to use them both in different
situations to get acquainted with them.
You need to complete installing IceStorm before attempting this step. If
you are the team member tasked with installing this step, you need to wait
until the previous step of installing
icestorm is complete. Change directory
into the
tools/arachnepnr directory of the top-level of your clone of the
course repository and run the following:
$ sudo make install
c++ -Isrc -std=c++11 -MD -O2 -Wall -Wshadow -Wsign-compare -Werror -c -o src/arachne-pnr.o src/arachne-pnr.cc
c++ -Isrc -std=c++11 -MD -O2 -Wall -Wshadow -Wsign-compare -Werror -c -o src/netlist.o src/netlist.cc
c++ -Isrc -std=c++11 -MD -O2 -Wall -Wshadow -Wsign-compare -Werror -c -o src/blif.o src/blif.cc
c++ -Isrc -std=c++11 -MD -O2 -Wall -Wshadow -Wsign-compare -Werror -c -o src/pack.o src/pack.cc
c++ -Isrc -std=c++11 -MD -O2 -Wall -Wshadow -Wsign-compare -Werror -c -o src/place.o src/place.cc
...
The compilation process will take about 2 minutes.
foundations of embedded systems 7
F.7 Compiling srec2hex
The program
srec2hex converts executable RISC-V binaries into a form that
you can pre-load into the Verilog RV32I processor design. Change directory
into the tools/srec2hex directory of the top-level of your clone of the course
repository and type
make install.
F.8 Compiling yosys
The program
yosys is the tool that synthesizes your design. Change directory
into the tools/yosys directory of the top-level of your clone of the course
repository and type sudo make install. You should see something like:
$ sudo make install
[ 0%] Building kernel/version
_
70d0f389.cc
[ 0%] Building kernel/version
_
70d0f389.o
[ 0%] Building kernel/driver.o
[ 0%] Building techlibs/common/simlib
_
help.inc
[ 0%] Building techlibs/common/simcells
_
help.inc
[ 1%] Building kernel/register.o
...
The compilation process will take about 30 minutes. While this is compiling,
all three team members should start getting familiar with the Digilent tools.
F.9 Compiling narvie
The program narvie-cli is a read-eval-print-loop (REPL) that allows you to
run individual RISC-V instructions on the iCE40 FPGA (or in simulation) and
it builds on top of the same RISC-V processor implementation we will be us-
ing in this project. Narvie is therefore a valuable tool for you to interactively
debug the effect of your changes to the RISC-V implementation.
Change directory into the
tools/narvie directory of the top-level of your
clone of the course repository and run:
$ cargo install narvie-cli
Updating crates.io index
Fetch [=============> ] 25.99%
...
The compilation process will take about 5 minutes. You will be using Narvie
by invoking
narvie-cli -simulate.
F.10 Compiling Sunflower
Sunflower is a processor simulator that you will use in this project. To com-
pile Sunflower:
8 phillip stanley-marbell
$ cd tools/sunflower
Next, edit the file conf/setup.conf to set the $OSTYPE, $MACHTYPE, and $SUNFLOWERROOT
variable:
SUNFLOWERROOT = <insert full path to the Sunflower/ directory here, with no space at the end of the line>
...
OSTYPE = linux
MACHTYPE = i386
For example, if your username is thx1138 and you cloned the course reposi-
tory to your home directory, you will need SUNFLOWERROOT = /students/thx1138/f-of-e-tools/tools/sunflower.
Next, change directory to
tools/source (from within the Sunflower direc-
tory) and run the downloads.sh script:
$ ./downloads.sh
Once the download script has downloaded and uncompressed all the files it
needs to, change directory back to the top level of the Sunflower repository.
The next step you need to build is what is called a cross-compiler. A cross-
compiler is a compiler that runs on one processor architecture (e.g., the Intel
x86 architecture of the workstation) and generates binaries for a different
architecture (e.g., for the RISC-V architecture which we will be studying in
this course). From the top of the Sunflower directory, run:
$ make cross-riscv
$ make
This compilation process will take about 15 minutes and you might choose
to leave it running on the workstation and adjourn for the day. You should
now have several binaries in the folder
tools/bin relative to the root of the
Sunflower director y, and you should also have a binary named sf in the
folder
sim/ relative to the root of the Sunflower directory.
F.11 Exercise
Complete the following
exercise to evaluate your understanding of the mate-
rial for this chapter.
foundations of embedded systems 9
F.12 The Muddiest Point
Think about the following two questions and submit your responses through
this
link.
1. What was least clear to you in this chapter? (You can simply list the section
numbers or write a few words.)
2. What was most clear to you in this chapter? (You can simply list the
section numbers or write a few words.)
10 phillip stanley-marbell
F.13 Further Reading
The following resources will be useful in exploring the concepts of this chap-
ter further:
1. Digital Design: An Embedded Systems Approach Using Ver ilog, ISBN: 978-
0123695277. This book is a detailed reference on the Verilog hardware
description language and will be valuable as you investigate methods to
reduce resource usage.
foundations of embedded systems 11
