Install Build Requirements

{{% toc 3 }}

System preparation

Note for all Windows users: many tools we‘re using can in theory work on Windows. However, we didn’t test on Windows and things will be broken there. Unless you are experienced in debugging various tool problems on Windows using Linux will improve your developer experience significantly.

By convention tools which are not provided through a package manager will be installed into /tools. This directory can be replaced by any sufficiently large directory without spaces in the directory name. It is assumed that the user executing the build instructions has full write permissions to this directory; the following commands ensure that.

$ sudo mkdir /tools
$ sudo chown $(id -un) /tools

Install required software

A number of software packages from the distribution's package manager is required. All installation instructions below are for Ubuntu 16.04. Adjust as necessary for other Linux distributions.

$ sudo apt-get install python3 python3-pip python3-setuptools build-essential ninja-build pkgconf srecord zlib1g-dev

Some tools in this repository are written in Python 3 and require Python dependencies to be installed through pip. (Note that the diff_generated_util_output.py tool works better with Python3.6 or later where the order is preserved in dict types, earlier versions of Python will show spurious differences caused by things being reordered.)

$ cd $REPO_TOP
$ pip3 install --user -r python-requirements.txt

The pip installation instructions use the --user flag to install without root permissions. Binaries are installed to ~/.local/bin; check that this directory is listed in your PATH by running fusesoc --version. If the fusesoc binary is not found, add ~/.local/bin to your PATH, e.g. by modifying your ~/.bashrc file.

Software development

Compiler toolchain

To build software you need a baremetal rv32imc compiler toolchain. You can either build your own or use a prebuilt one. We recommend installing the toolchain to /tools/riscv.

Option 1 (recommended): Use the lowRISC-provided prebuilt GCC toolchain

lowRISC provides a prebuilt GCC toolchain for the OpenTitan project. Download the file starting with lowrisc-toolchain-gcc-rv32imc- from GitHub releases and unpack it to /tools/riscv.

Or alternatively, use a in-tree helper script.

$ cd $REPO_TOP
$ ./util/get-toolchain.py

Option 2: Compile your own GCC toolchain

  1. Install all build prerequisites listed in the documentation.

  2. Build the toolchain

    $ git clone --recursive https://github.com/riscv/riscv-gnu-toolchain
$ cd riscv-gnu-toolchain
$ ./configure --prefix=/tools/riscv --with-abi=ilp32 --with-arch=rv32imc --with-cmodel=medany
$ make

The make command installs the toolchain to /tools/riscv, no additional make install step is needed.

OpenOCD

OpenOCD is a tool to connect with the target chip over JTAG and similar transports. It also provides a GDB server which is an “intermediate” when debugging software on the chip with GDB.

Unfortunately the upstream sources of OpenOCD do not contain all necessary patches to support RISC-V, and hence typical distribution packages don't work. We therefore need to build OpenOCD from source from a forked repository.

For FTDI support the libraries libftdi > 1.0 and libusb > 1.0 are needed. Install those packages prior to building OpenOCD.

$ sudo apt-get install libftdi1-dev libusb-1.0-0-dev
$ git clone https://github.com/riscv/riscv-openocd.git
$ cd riscv-openocd
$ ./bootstrap
$ mkdir build
$ cd build
$ ../configure --enable-ftdi --enable-verbose-jtag-io --disable-vsllink --enable-remote-bitbang --prefix=/tools/openocd
$ make -j4
$ sudo make install

Verilator

Even though Verilator is packaged for most Linux distributions these versions tend to be too old to be usable. We recommend compiling Verilator from source, as outlined here.

First some build prerequisites need to be installed. For Ubuntu the following packages are needed.

$ sudo apt-get install git make autoconf g++ flex bison

Install Verilator

Then you can fetch, build and install Verilator itself.

$ export VERILATOR_VERSION=4.010

$ git clone http://git.veripool.org/git/verilator
$ cd verilator
$ git checkout v$VERILATOR_VERSION

$ autoconf
$ ./configure --prefix=/tools/verilator/$VERILATOR_VERSION
$ make
$ make install

After installation you need to add /tools/verilator/$VERILATOR_VERSION/bin to your PATH environment variable.

Xilinx Vivado

System requirements

This guide makes assumes the following system setup.

  • A reasonably powerful PC running Linux. Using a virtual machine can work, but will slow down builds considerably. 8 GB of RAM or more are highly recommended.
  • Physical access to that machine, root permissions and a graphical environment.
  • Python 3.5 or newer. Python 3.6+ is recommended.
  • 60 GB or more of disk space. EDA tools like Xilinx Vivado can easily take up 40 GB each.
  • We develop and test on the following Linux distributions:
    • Ubuntu 16.04 LTS
    • Debian testing
    • openSUSE Tumbleweed
    • TODO: Check RHEL/CentOS and SLES (used in many commercial environments)

TODO: Be more specific about the system requirements, especially the Linux distribution.

About Xilinx Vivado

To generate a bitstream for Xilinx devices a software called Vivado is required. Vivado is provided by Xilinx, it is freeware for certain (smaller) FPGA devices but requires a commercial license for larger FPGAs. The free version is called “WebPACK”, the commercial version “Design Edition”. The installation instructions below are valid for both installation methods.

Most lowRISC designs support at least one FPGA board which works with a free WebPACK license.

Install Xilinx Vivado

Vivado can be installed in two ways: either through an “All OS installer Single-File Download”, or via the “Linux Self Extracting Web Installer”. Neither option is great: the “All OS installer” is a huge download of around 20 GB (and the Xilinx download servers seem to be overloaded regularly), but it supports an unattended installation. The web installer downloads only necessary subsets of the software, which significantly reduces the download size. But unfortunately it doesn't support the batch mode for unattended installations, requiring users to click through the GUI and select the right options.

To get started faster we use the web installer in the following.

  1. Go to the Xilinx download page and download two files for the current version of Vivado. (We used Vivado 2018.3 to prepare this guide.)

    1. The file “Vivado HLx : WebPACK and Editions - Linux Self Extracting Web Installer”.
    2. The “Digests” file below the download.

    Vivado download site

    You need to register for a free Xilinx account to download the software, and you‘ll need it again later to install the software. Create a new account if you don’t have one yet.

  2. Before you proceed ensure that the download didn't get corrupted by verifying the checksum.

    $ sha512sum --check Xilinx_Vivado_SDK_Web_2018.3_1207_2324_Lin64.bin.digests
Xilinx_Vivado_SDK_Web_2018.3_1207_2324_Lin64.bin: OK
sha512sum: WARNING: 22 lines are improperly formatted

    If you see an “OK” after the downloaded file proceed to the next step. Otherwise delete the download and start over. (You can ignore the warning produced by sha512sum.)

  3. Run the graphical installer.

    $ sh Xilinx_Vivado_SDK_Web_2018.3_1207_2324_Lin64.bin

  4. Now you need to click through the installer. Click “Next” on the first screen.

    Vivado installation step 1

  5. Type in your Xilinx User ID (your email address) and the associated password. Choose the “Download and Install Now” option. Click “Next” to continue.

    Vivado installation step 2

  6. Click all “I Agree” checkboxes, and click on “Next” to continue.

    Vivado installation step 3

  7. Choose “Vivado HL WebPACK” if you do not have a commercial Vivado license, or “Vivado HL Design Edition” if you have a valid license. In this walk through we'll install the WebPACK edition.

    Vivado installation step 4

  8. Choose the features to install. You can restrict the features to the ones shown in the screenshot below. Click “Next” to continue.

    Vivado installation step 5

  9. Choose an installation location. Any location which doesn't have a whitespace in its path and enough free space is fine. We use /tools in our example, but a path in /opt or within the home directory works equally well. Click “Next” to continue.

    Vivado installation step 6

  10. Double-check the installation summary and click on “Next” to start the installation process.

Vivado installation step 7

  1. Now Vivado is downloaded and installed, a process which can easily take multiple hours.

Vivado installation step 8

  1. As soon as the installation has completed close the installer and you're now ready to use Vivado!

Device permissions: udev rules

To program FPGAs user using Vivado typically needs to have permission to USB devices connected to the PC. Depending on your security policy you can take different steps to enable this access. One way of doing so is given in the udev rule outlined below.

To do so, create a file named /etc/udev/rules.d/90-lowrisc.rules and add the following content to it:

# Grant access to board peripherals connected over USB:
# - The USB devices itself (used e.g. by Vivado to program the FPGA)
# - Virtual UART at /dev/tty/XXX

# Future Technology Devices International, Ltd FT2232C/D/H Dual UART/FIFO IC
# used on Digilent boards
ACTION=="add|change", SUBSYSTEM=="usb|tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", ATTRS{manufacturer}=="Digilent", MODE="0666"

# Future Technology Devices International, Ltd FT232 Serial (UART) IC
ACTION=="add|change", SUBSYSTEM=="usb|tty", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE="0666"

You then need to reload the udev rules:

# udevadm control --reload