Chapter 2 Installation & Configuration

Before you get started with OpTiMSoC you should notice that external tools and libraries might be required that are in some cases proprietary and cost some money. Although OpTiMSoC is developed at an university with access to many EDA tools, we aim to always provide tool flows and support for open and free tools, but especially when it comes to synthesis such alternatives are even not available.

2.1 Prerequisites

Throughout this document some packages are required in your Linux distribution. OpTiMSoC should principally work on all common Linux distributions. In case you encounter problems in your system we highly encourage you to contact the OpTiMSoC maintainers to fix these problems. Nevertheless, we recommend Ubuntu 14.04 LTS as development system and can ensure OpTiMSoC will work on it as we also work on it. In the following we will refer to Ubuntu/Debian commands to install packages, that will run under Ubuntu 14.04 LTS.

Independent of the OpTiMSoC components you plan to use, you will need some packages to be installed:

⬇

sudo apt-get -y install git build-essential tcl libusb-1.0-0-dev \

libboost-dev libelf-dev swig python3 python3-yaml

# optional, but highly recommended: a waveform viewer

sudo apt-get -y install gtkwave

2.2 Option 1: Install the OpTiMSoC binary distribution (recommended)

The most simple way to get started is with the release packages. You can find the OpTiMSoC releases here: https://github.com/optimsoc/sources/releases. With the release you can find the distribution packets that can be extracted into any directory and used directly from there. The recommended default is to install OpTiMSoC into /opt/optimsoc. There are two packages: the base package contains the programs, libraries and tools to get started. The examples package contains prebuilt verilator simulations for the real quick start.

For example take the 2016.1 release and download both base and examples. Then create the base folder and extract the package:

⬇

sudo mkdir /opt/optimsoc

sudo chown $USER /opt/optimsoc

tar -xzf optimsoc-2016.1-base.tgz -C /opt/optimsoc

tar -xzf optimsoc-2016.1-examples.tgz -C /opt/optimsoc

You can now use the installation after setting the environment with the pre-installed environment source script:

⬇

cd /opt/optimsoc/2016.1

source optimsoc-environment.sh

We encourage you to put this code into your ~/.bashrc.

Now you are near to get started, but you need some programs to build software to run in OpTiMSoC and execute the verilator-based simulations. Those are: the or1k-elf-multicore toolchain and Verilator. All those tools are free, but are (except for an outdated Verilator version) not part of the Linux package systems. Hence you need to built those tools as described in the Reference Manual, or you can simply download some prebuilt-versions.

To do so simply run a script for your version:

⬇

wget https://raw.githubusercontent.com/optimsoc/prebuilts/master/optimsoc-prebuilt-deploy.py

chmod a+x optimsoc-prebuilt-deploy.py

./optimsoc-prebuilt-deploy.py -d /opt/optimsoc verilator or1kelf

You may of course leave out any of the tools if you already have it installed. Finally, you will get another source script to set up the environment for the prebuilt tools:

⬇

source /opt/optimsoc/setup_prebuilt.sh

We recommend to put this line into your ~/.bashrc file as well.

You are now ready to go to the tutorials in Chapter 3.

2.3 Option 2: Build OpTiMSoC from sources

You can also build OpTiMSoC from the sources. This options usually becomes standard if you start developing for or around OpTiMSoC. The build is done from one git repository: https://github.com/optimsoc/sources.

It is generally a good idea to understand git, especially when you plan to contribute to OpTiMSoC. Nevertheless, we will give a more detailed explanation of how to get your personal copies of OpTiMSoC and (potentially) update them.

The start of a successful built is to install the tools Verilator and the or1k-elf-multicore toolchain. The most simple way is to start with the prebuilt tools as described above, then set the environment for the tools.

Note

During the installation, you’ll frequently encounter three types of directories.

The source directory. This is the place where the uncompiled source code files are stored. Usually, that is the folder that you cloned from the git repository.

The $OPTIMSOC_SOURCE environment variable should point to the root of the source directories.
The build or object directory. For different components such a directory is used to build the component. The installer performs the build process in these directories and you perform individual builds there if you develop for OpTiMSoC (for example: if you develop the libraries).

Sometimes, this directory is equal to the source directory, but most of the time, we create a new directory called build inside the source directory. Doing so has a great benefit: if something in the build process went wrong, you can simply delete the build directory and start all over again.
The installation directory. This is the target directory where results of the build process are stored for further use. It is used by the installer or you when running make install to store the files generated by the build process. The environment variable $OPTIMSOC points to the root of the installation directory.

2.3.1 Prerequisites

You will need some programs to build OpTiMSoC, e.g., on Ubuntu 14.04:

⬇

sudo apt-get install autoconf automake libtool tcl texlive texlive-latex-extra texlive-fonts-extra

2.3.2 Get the sources

Start with checking out the repository:

⬇

git clone https://github.com/optimsoc/sources.git optimsoc-sources

cd optimsoc-sources

2.3.3 Build the code

OpTiMSoC contains a Makefile which controls the whole build process. Building is as simple as calling (inside the top-level source directory)

⬇

make

2.3.4 Install the code

To install OpTiMSoC to the default location in /opt/optimsoc/VERSION it’s sufficient to run

⬇

sudo make install

You can also modify the target directory using environment variables passed to make. This is especially useful if you don’t have enough permissions to write to /opt/optimsoc.

Use INSTALL_PREFIX to change the installation prefix from /opt/optimsoc to something else. The installation will then go into INSTALL_PREFIX/VERSION.
Use INSTALL_TARGET to fully override the installation path. The installation will then go exactly into this directory.

⬇

# recommended option: use INSTALL_PREFIX

make install INSTALL_PREFIX=~/optimsoc

# full control for special cases: use INSTALL_TARGET

make install INSTALL_TARGET=~/optimsoc-testversion

User Guide