Quick Start Guide

The initial working directory of this document is labeled-RISC-V/fpga

Sub-directories Overview

.
├── board              # supported FPGA boards and files to build a Vivado project
├── boot               # PS boot flow of zynq and zynqmp
├── doc                # some development documents (but in Chinese...)
├── emu                # wrapper of the original rocketchip/emulator to support fast memory initializaion
├── lib                # HDL sources shared by different boards
├── Makefile
├── Makefile.check
├── Makefile.sw
├── pardcore           # wrapper of rocketchip in the Vivado project
└── README.md          # this file

Preparations

The following instructions mostly come from README-rocketchip.md under the root directory of this repo.

Get all submodules (right after this repo being cloned):

cd .. # go to labeled-RISC-V repo top directory
git submodule update --init --recursive
cd fpga/

Install essential packages:

sudo apt-get install autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev libusb-1.0-0-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev device-tree-compiler pkg-config libexpat-dev
sudo apt-get install openjdk-8-jdk

Prepare toolchains:

• Option 1: download our pre-built and currently-used riscv-toolchain
• Option 2: build riscv-tools from srcatch. Remember to checkout to the commit recorded in ../riscv-tools.hash

If you use the pre-built toolchain, it may require libmpfr.so.4, while it is highly possible that your system has libmpfr.so.6. You can just make a symbol link of libmpfr.so.4 pointing to libmpfr.so.6, which we have tested that it can work for most cases.

Set environment variables:

export RISCV=path/of/riscv-toolchain
export PATH=$PATH:$RISCV/bin

Build RISC-V image

• Build riscv-pk (which contains the bootloader), riscv-linux and riscv-rootfs with the following commands

mkdir build
make -j sw  # change 16 to the number of cores according to your host

If it is the first time you run this command, note that you will be asked to pull these repos under ../../sw.

After that, linux.bin will be generated under build/. This is a minimal rootfs only containing a hello program.

Run with emulator

cd ../bootrom && make
cd ../fpga/emu
make -j run-emu

The following files will be generated

1. build/generated-src/ is the directory containing files generated by origin rocketchip project
2. build/emu.log is the output of emulator, including printf() and assert() in scala code
3. build/serial@6000?000 is the output of the ?th UART. Use tail -f serial@60000000 to observe the output.

It may cost about one hour (it depends on the performance of your host) to boot linux in emulator.

Run with FPGA

Build a Vivado project

• note: if you are using new version of zcu102 (Please refer to the description of this link), you need to apply the patch from board/zcu102/patch/0001-patch-for-new-version-of-zcu102.patch
• Install Vivado 2019.1, and source the setting of Vivado and SDK
• Run the following command to build a Vivado project

make project PRJ=myproject BOARD=zcu102

Change zcu102 to the target board you want. Supported boards are listed under board/. The project will be created under board/zcu102/build/myproject-zedzcu102.

• Open the project with Vivado and generate bitstream.

Prepare SD card

Refer to the instructions of boot/README.md.

NOTE: Remember to put the bitstream into BOOT.BIN, since the guide is going to boot everything from SD card.

Set your board to SD boot mode

Please refer to the user guide of your board.

• zedboard
• zcu102
• sidewinder
• ultraZ (currently not avaliable to the public)

Boot linux in PRM

NOTE: PRM is short for Platform Resource Manager, which is acted by PS part of the board.

To boot linux in PRM, just insert the SD card into the board, open a serial terminal and powerup the board.

Boot RISC-V subsystem

Due to different resources in different FPGA devices, the configures of RISC-V subsystem are different among boards.

For details, please read LvNAConfigs.scala.

To boot the RISC-V subsystem

• Clone the prm-sw repo. prm-sw contains tools to boot and control the RISC-V subsystem. For details, please refer to the README.md under the prm-sw directory.
• Send the prm-sw directory to PRM. This can be achieved by either copying the file to SD card, or by sending the file with scp if you have your board connected to your host by network.
• Compile the tools on PRM.

cd path-to-prm-sw/apps/axi-loader && make PLATFORM=fpga [BOARD=zynq]
cd path-to-prm-sw/apps/pardctl && make PLATFORM=fpga [BOARD=zynq]
cd path-to-prm-sw/apps/stab && make PLATFORM=fpga [BOARD=zynq]

If the target board is zynq, add the BOARD=zynq argument specified above.

Build RISC-V image for FPGA

cd path-to-labeled-RISC-V/../sw/riscv-linux
make ARCH=riscv CROSS_COMPILE=riscv64-unknown-linux-gnu- fpga_defconfig
cd path-to-labeled-RISC-V/fpga
make -j16 sw

This will generator linux.bin under build/. This is a rootfs containing busybox to use in FPGA. Then put linux.bin under path-to-prm-sw/apps/axi-loader/ on PRM.

SMP Boot

SMP boot allows running one OS on multiple cores. This is the traditional way to use a multi-core system.

• Open minicom on PRM to connect to the UART of RISC-V subsystem. Note that you can connect to PRM via ssh and use tmux to get multiple terminals.

minicom -D /dev/ttyUL1

• Run the script to boot RISC-V subsystem in SMP mode.

cd path-to-prm-sw/apps/axi-loader
bash runme-smp.sh [board]
bash hard-reset.sh  # this is a temporary fix to the reset system

It may cost about 50s for zedboard to boot the RISC-V subsystem. Most of the time is spent in unpacking ramdisk image.

NOTE: Currently the process-level label machenism in the SMP OS does not work well. To use label, please use NoHype mode below.

NoHype Boot

Currently we are working on this part.

TODO

add dummy eth for PS