Tutorial Preparation

What to Bring

Please bring a laptop with:

1 CPU core (4 recommended)
4 GB of RAM (16 recommended)
10 GB of free hard disk space (15 recommended)
Installation of the tutorial repository
Optional: your own Verilog RTL designs!

We strongly recommend setting up the tools before arriving to the tutorial so you don’t miss anything! We will provide USB 3.0 drives with virtual machine appliance files (.ova / .utm) at the tutorial. Internet connections may be unstable at the tutorial venue, so do not expect to connect to a remote server!

Toolchain Installation

We provide several methods to install the tool chain. Note that OpenROAD only natively supports Linux and MacOS, with best support for Ubuntu 20 and Centos 7.

Method 1: Install a Virtual Machine

If using this option, be sure you have at least 20 GB free disk space.

Virtual machine username: user password: openroad

x86_64 Hosts (Windows, Linux, MacOS)

Install Virtual Machine Software

If setting up prior to the tutorial:

Visit VirtualBox’s download page to download and run the installer for your OS.
Download the x86 virtual appliance openroad-tutorial-micro2022.ova (6.8 GB): [Mirror 1] [Mirror 2]

If setting up at the tutorial:

Pick up one of the supplied USB 3.0 flash drives. If needed, USB 3.0 to USB-C converters are available for use.
Navigate to x86_64/vm_installer on the flash drive and run the VirtualBox installer for your OS.

Some OSs may require you to enable hardware virtualization (if not already) and restart your computer.

Import Virtual Appliance

Start VirtualBox and navigate to File > Import Appliance…
If using a flash drive, navigate to the flash drive and select x86_64/vm_image/openroad-tutorial-micro2022.ova. Otherwise, select your downloaded .ova file. Then, select Next.
Alter any default parameters for your virtual machine. We recommend at least 4 GB RAM and 4 processors, but no more than 3/4 of your total system RAM or 3/4 of your processors. Please use at least 2 processors or the VM OS (Lubuntu) may not boot.
Select Import and wait for the process to finish (~5-10 minutes).

Launch the Virtual Machine

Select openroad-tutorial-micro2022 from your list of virtual machines and press Start.
Wait for the virtual machine to boot into Lubuntu (~1-3 minutes). Warnings during boot can be ignored.
If needed, the username is user and the password is openroad.

arm64 Hosts (MacOS)

Install Virtual Machine Software

If setting up prior to the tutorial:

Visit UTM’s download page and select Download. (The App Store version is non-free and supports open-source development).
Download the arm64 virtual appliance openroad-tutorial-micro2022.utm.bz2 (4.0 GB): [Mirror 1] [Mirror 2]

If setting up at the tutorial:

Pick up one of the supplied USB 3.0 flash drives. If needed, USB 3.0 to USB-C converters are available for use.
Navigate to arm64/vm_installer/osx/UTM.dmg on your flash drive and run the installer.

Import Virtual Appliance

If using a flash drive, copy arm64/vm_image/openroad-tutorial-micro2022.utm.bz2 to your local disk.
Extract the file (~3-8 minutes). In terminal, you can use tar -xf openroad-tutorial-micro2022.utm.bz2.
Start UTM, select File > Open…, and select the extracted file (openroad-tutorial-micro2022.utm).

Launch the Virtual Machine

Press the “play” icon on the openroad-tutorial-micro2022 virtual machine
Wait for the virtual machine to boot into Lubuntu (~1 minute). Warnings during boot can be ignored.
If needed, the username is user and the password is openroad.

Test the Toolchain

Inside the virtual machine:

Open QTerminal
cd ~/micro2022tutorial/OpenROAD-flow-scripts/flow
make

If the flow completes without error, congrats! You are ready to start the tutorial. You should run make clean_all to reset your flow build.

Method 2: Install from Docker

For advanced users only. Build times can take up to an hour.

See the OpenROAD docs on how to build from sources and test using Docker.

Note:

OpenROAD-flow-scripts is already included in the micro2022tutorial repo.
The tools will only be accessible inside the installed docker container.

Apply the Patchfile

There some temporary instability in Exercises 2 and 3 caused by upstream changes. Apply the patchfile to perform a workaround:

$ cd micro2022tutorial
$ patch OpenROAD-flow-scripts/flow/scripts/report_metrics.tcl patchfile.patch
patching file OpenROAD-flow-scripts/flow/scripts/report_metrics.tcl

Test the Toolchain

# Start an interactive shell inside the Docker container
# Must be run from the micro2022tutorial directory
$ docker run -it -u $(id -u ${USER}):$(id -g ${USER}) -v $(pwd)/OpenROAD-flow-scripts/flow/platforms:/OpenROAD-flow-scripts/flow/platforms:ro -v $(pwd):/micro2022tutorial openroad/flow-scripts

# The following lines will be executed inside the Docker container
$ cd /OpenROAD-flow-scripts/flow
$ make

If the flow completes without error, congrats! You are ready to start the tutorial. You should run make clean_all to reset your flow build.

Method 3: Install from Source

For advanced users only. Build times can take up to an hour.

This method will build OpenROAD-flow-scripts components (OpenROAD and Yosys) from source. Package managers are used to install (most) dependencies.

Download the Repository

$ git clone --recursive https://github.com/The-OpenROAD-Project/micro2022tutorial

Cloning recursively is important to download and initialize all git submodules.

Install Dependencies

OpenROAD cannot run on Windows natively. We recommend installing Windows Subsystem for Linux (WSL) and following the instructions for Linux. Be sure to install an Xserver such as Xming so that you can open GUIs.

OpenROAD has preliminary support for MacOS. You can use the OpenROAD dependency installer script (requires Homebrew):

micro2022tutorial/OpenROAD-flow-scripts/tools/OpenROAD/etc/DependencyInstaller.sh

Then, install additional dependencies for OpenROAD-flow-scripts:

brew install libffi pkg-config klayout

The OS may identify KLayout as an untrusted app - you will need to mark it as trusted in order to run it.

If you use Ubuntu or CentOS, you can use the OpenROAD dependency installer script:

sudo micro2022tutorial/OpenROAD-flow-scripts/tools/OpenROAD/etc/DependencyInstaller.sh

Using a different distribution is not recommended, however you may view the script and identify how to manually install the required packages for your distribution.

KLayout must be installed separately. See the KLayout download page to install it for your distribution.

Build

Run the install script. This step may take up to an hour, depending on your internet connection and CPU performance.

# This script uses all available cores to build. Use --threads N to use N threads
# Use --help to see all build options
$ micro2022tutorial/OpenROAD-flow-scripts/build_openroad.sh

Apply the Patchfile

There some temporary instability in Exercises 2 and 3 caused by upstream changes. Apply the patchfile to perform a workaround:

$ cd micro2022tutorial
$ patch OpenROAD-flow-scripts/flow/scripts/report_metrics.tcl patchfile.patch
patching file OpenROAD-flow-scripts/flow/scripts/report_metrics.tcl

Test the Toolchain

To quickly verify that your installation is correct, run

$ cd micro2022tutorial/OpenROAD-flow-scripts/flow
$ source ../setup_env.sh
# Make sure that KLayout is in your PATH before running make
$ make

If the flow completes without error, congrats! You are ready to start the tutorial. You should run make clean_all to reset your flow build.