Installation & Configuration¶
Installing an OpTiMSoC release should not take more than 10 minutes (if you have a decent internet connection), so let’s get started!
Please first check the system requirements.
- Supported Linux distribution: Ubuntu 16.04 LTS on x86_64
- 20 GB disk space (mostly for Xilinx Vivado and other tools)
- 4 GB or more of RAM helps greatly (especially during FPGA synthesis)
- We recommend not using a VM, but running directly on the hardware. Using a VM is possible, but will result in significantly slower compilation and synthesis runs.
- (optional, only if you want to do FPGA synthesis) Xilinx Vivado 2016.4. The free WebPack edition is sufficient for most use cases.
Some external tools, especially EDA tools for synthesis and simulators, 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.
In OpTiMSoC, we try to use only external dependencies which are known to be stable and readily available. Some can be installed as distribution packages, and others can be downloaded as binaries from us.
First, install all required packages from Ubuntu.
# This command should get all required build dependencies ./tools/install-build-deps.sh # If you do not plan to build the documentation you can save yourself # a bit of download time by using INSTALL_DOC_DEPS=no ./tools/install-build-deps.sh # optional, but highly recommended: a waveform viewer sudo apt-get -y install gtkwave
We build our systems with FuseSoC, a package manager for RTL designs. It automatically arranges the sources and writes project files for our systems. At least FuseSoC version 1.7 is required, you can install it from the Python package index:
sudo pip3 install --upgrade fusesoc
To run the tests shipped with OpTiMSoC pytest is required. Install it through pip (the distribution packages are too old):
sudo pip3 install --upgrade pytest
Additionally, we need two things which are not available as Ubuntu packages right now:
a recent version of Verilator (>= 3.902), and the
or1k-elf-multicore toolchain (compiler, C library, debugger, etc.).
Install them with our binary installation script:
# if it does not exist yet: prepare the /opt/optimsoc directory sudo mkdir /opt/optimsoc sudo chown $USER /opt/optimsoc # download and install the prebuilt tools curl -O https://raw.githubusercontent.com/optimsoc/prebuilts/master/optimsoc-prebuilt-deploy.py python optimsoc-prebuilt-deploy.py -d /opt/optimsoc verilator or1kelf
To use the prebuilt tools some environment variables need to be adjusted. This is done by running the following command in every terminal session that you want to use OpTiMSoC in:
Automatically load the prebuilts in every new terminal session by adding it to your
echo 'source /opt/optimsoc/setup_prebuilt.sh' >> ~/.bashrc
Now that all preparations are done, you are now ready to install the OpTiMSoC framework itself. There are two options: either, you can install a prebuilt release package, or you can build OpTiMSoC yourself from the sources. We recommend starting with a binary release installation, and move to a custom-built version only after you verified that everything works.
Recommended: OpTiMSoC binary releases¶
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 packages that can be extracted into any directory and used directly from there.
The recommended default is to install OpTiMSoC into
There are two packages: the
base package contains the programs, libraries and tools to get started.
examples package contains prebuilt example systems (both in simulation and FPGA bitstreams) for the real quick start.
This documentation was generated for a development version and you cannot download prebuild packages for it. Some parts of this documentation will vary from the release documentation and examples not work anymore. Please refer to the documentation matching the last release that you can find here: https://optimsoc.org/docs.
To install the 2016.1 release into
/opt/optimsoc, run the following commands:
wget https://github.com/optimsoc/sources/releases/download/v2016.1/optimsoc-2016.1-base.tar.gz wget https://github.com/optimsoc/sources/releases/download/v2016.1/optimsoc-2016.1-examples.tar.gz tar -xf optimsoc-2016.1-base.tar.gz -C /opt/optimsoc tar -xf optimsoc-2016.1-examples.tar.gz -C /opt/optimsoc
To use OpTiMSoC multiple environment variables need to be set. This is done by running the following command in every terminal session that you want to use OpTiMSoC in:
cd /opt/optimsoc/2016.1 source optimsoc-environment.sh
Automatically load the OpTiMSoC environment in every new
terminal session by adding it to your
echo 'cd /opt/optimsoc/2016.1; source optimsoc-environment.sh' >> ~/.bashrc
You are now ready to go to the Tutorials.
Alternative: 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.
First, you need some additional tools (the “build dependencies”):
sudo apt-get -y install doxygen texlive texlive-latex-extra texlive-fonts-extra
Then get the sources from git:
git clone https://github.com/optimsoc/sources.git optimsoc-sources cd optimsoc-sources # optional: checkout a release version git checkout 2016.1
Now you’re ready to build OpTiMSoC.
OpTiMSoC contains a Makefile which controls the whole build process. Building is as simple as calling (inside the top-level source directory that you just got from git)
By default this also builds the documentation, the Verilator examples and the FPGA bitstreams (which requires Xilinx Vivado to be working).
You can disable some features by passing variables to the
# only build Verilator examples, but no bitstreams and no docs make BUILD_EXAMPLES=yes BUILD_EXAMPLES_FPGA=no BUILD_DOCS=no
If you need even more fine-grained control over the build process, call the build script
tools/build.py --help will give you a list of all available options.
After the build process, all build artifacts are located in
You can either use OpTiMSoC directly from there (good during development), or copy it to a more suitable installation location in
/opt/optimsoc/VERSION by running
You can also modify the target directory using environment variables passed to
This is especially useful if you don’t have enough permissions to write to
INSTALL_PREFIXto change the installation prefix from
/opt/optimsocto something else. The installation will then go into
INSTALL_TARGETto fully override the installation path. The installation will then go exactly into this directory.
# use INSTALL_PREFIX to install into ~/optimsoc/VERSION make install INSTALL_PREFIX=~/optimsoc # full control for special cases: use INSTALL_TARGET # to install into ~/optimsoc-testversion make install INSTALL_TARGET=~/optimsoc-testversion
Independent of which directory you chose, to use OpTiMSoC multiple environment variables need to be set. This is done by running the following command in every terminal session that you want to use OpTiMSoC in:
cd YOUR_INSTALLATION_DIR source optimsoc-environment.sh
See the binary installation description above for information on how to make this change permanent.
OpTiMSoC is now ready to be used and you can continue with the Tutorials.