Quick Start Guide

Begin by cloning the OpenTitan repository directly from GitHub.

git clone https://github.com/lowRISC/opentitan.git
cd opentitan
export REPO_TOP=$(pwd)

This development path is optimized for Linux (Ubuntu 22.04 LTS). A Docker alternative is linked below.

A number of software packages from the distribution’s package manager are required. On Ubuntu 20.04, the required packages can be installed with the following command.

sed '/^#/d' ./apt-requirements.txt | xargs sudo apt install -y

Python libraries require a virtual environment to be set up.

sudo apt install python3-venv
cd $REPO_TOP
python3 -m venv .venv
source .venv/bin/activate

And then the Python libraries are installed through pip.

pip3 install "setuptools<66.0.0"
pip3 install -r python-requirements.txt --require-hashes

In order to run software without physical targets (silicon or FPGA), we need to emulate an OpenTitan chip. OpenTitan supports Verilator, which constructs high-performance execution binaries from SystemVerilog files.

Although Verilator is packaged with Linux, we use a newer version, which means a few steps to compile from source. This is straightforward, although it will take a few minutes to run.

First fetch the Verilator source.

sudo apt install gcc-11 g++-11
export VERILATOR_VERSION=4.210
git clone https://github.com/verilator/verilator.git
cd verilator
git checkout v$VERILATOR_VERSION

Now compile the source code.

autoconf
sudo apt-get install flex
sudo apt-get install bison
CC=gcc-11 CXX=g++-11 ./configure --prefix=/tools/verilator/$VERILATOR_VERSION
CC=gcc-11 CXX=g++-11 make
sudo CC=gcc-11 CXX=g++-11 make install

Finally add to your PATH and check that Verilator is installed correctly.

export PATH=/tools/verilator/$VERILATOR_VERSION/bin:$PATH
verilator --version

OpenTitan software artifacts, testing regressions, and device binary files are compiled using the Bazel build ecosystem.

Run the bundled shell script wrapper to build the baseline SoC simulation binary image, compile the low-level firmware code, and run a safe UART smoke test.

cd $REPO_TOP
./bazelisk.sh test --test_output=streamed \
//sw/device/tests:uart_smoketest_sim_verilator

The initial compilation pass compiles the entire digital hardware architecture so it's a chance for a coffee break while this builds. Subsequent execution loops reuse cached files and complete rapidly.

Simulation of OpenTitan Earl Grey
=================================

//sw/device/tests:uart_smoketest_sim_verilator  PASSED in 65.1s

Executed 1 out of 1 test: 1 test passes.

Want to write custom embedded C binaries, trace memory map layout rules, or implement complex testing scenarios?

Below are some suggested next areas to explore.