iic-jku / IIC-OSIC-TOOLS

IIC-OSIC-TOOLS is an all-in-one Docker image for SKY130/GF180/IHP130-based analog and digital chip design. AMD64 and ARM64 are natively supported.
Apache License 2.0
327 stars 53 forks source link
analog-design circuits digital-design ic microelectronics mixed-signal-chips

IIC-OSIC-TOOLS

This environment is based on the efabless.com FOSS-ASIC-TOOLS.

IIC-OSIC-TOOLS is an all-in-one Docker container for open-source-based integrated circuit designs for analog and digital circuit flows. The CPU architectures x86_64/amd64 and aarch64/arm64 are natively supported based on Ubuntu 22.04LTS (since release 2022.12). This collection of tools is curated by the Institute for Integrated Circuits (IIC), Johannes Kepler University (JKU).

Table of Contents

1. How to Use These Open-Source (and Free) IC Design Tools

For great step-to-step instructions of installation and operation of our tool collection, please checkout Kwantae Kim's Setting Up Open Source Tools with Docker!

It supports two modes of operation:

  1. Using a complete desktop environment (XFCE) in Xvnc (a VNC server), either directly accessing it with a VNC client of your choice or the integrated noVNC server that runs in your browser.
  2. Using a local X11 server and directly showing the application windows on your desktop.
  3. Using it as a development container in Visual Studio Code (or other IDEs)

1.1 Step 1: Clone/download this GitHub repository onto your computer

Use the green Code button, and either download the zip file or do a git clone --depth=1 https://github.com/iic-jku/iic-osic-tools.git.

1.2 Step 2: Install Docker on your computer

See instructions on how to do this in the section Quick Launch for Designers further down in this README.

1.3 Step 3: Start and Use a Docker Container based on our IIC-OSIC-TOOLS Image

Enter the directory of this repository on your computer, and use one of the methods described in the section Quick Launch for Designers to start up and run a Docker container based on our image. The easiest way is probably to use the VNC mode.

If you do this the first time, or we have pushed an updated image to DockerHub, this can take a while since the image is pulled (loaded) automatically from DockerHub. Since this image is ca. 4GB, this takes time, depending on your internet speed. Please note that this compressed image will be extracted on your drive, so please provide at least 20GB of free drive space. If, after a while, the consumed space gets larger, this may be due to unused images piling up. In this case, delete old ones; please consult the internet for instructions on operating Docker.

If you know what you are doing and want full root access without a graphical interface, please use ./start_shell.sh.

2. Installed PDKs

As of the 2022.12 tag, the following open-source process-development kits (PDKs) are pre-installed, and the table shows how to switch by setting environment variables (you can do this per project by putting this into .designinit as explained below):

SkyWater Technologies sky130A
export PDK=sky130A
export PDKPATH=$PDK_ROOT/$PDK
export STD_CELL_LIBRARY=sky130_fd_sc_hd
Global Foundries gf180mcuC
export PDK=gf180mcuC
export PDKPATH=$PDK_ROOT/$PDK
export STD_CELL_LIBRARY=gf180mcu_fd_sc_mcu7t5v0
IHP Microelectronics sg13g2
Not yet ready to use

More options for selecting digital standard cell libraries are available; please check the PDK directories.

3. Installed Tools

Below is a list of the current tools already installed and ready to use (note there are some adaptions in our container vs. efabless.com):

The tool versions used for OpenLane2 (and other tools) are documented in tool_metadata.yml. In addition to the EDA tools above, further valuable tools (like git) and editors (like gvim) are installed. If something useful is missing, please let us know!

4. Quick Launch for Designers

Download and install Docker for your operating system:

Note for Linux: Do not run docker commands or the start scripts as root (sudo)! Follow the instructions in Post-installation steps for Linux

The following start scripts are intended as helper scripts for local or small-scale (single instance) deployment. Consider starting the containers with a custom start script if you need to run many instances.

4.1 Customizing Environment

All user data is persistently placed in the directory pointed to by the environment variable DESIGNS (the default is $HOME/eda/designs for Linux/macOS and %USERPROFILE%\eda\designs for Windows, respectively).

If a file .designinit is put in this directory, it is sourced last when starting the Docker environment. In this way, users can adapt settings to their needs.

4.2 Using VNC and noVNC

This mode is recommended for remote operation on a separate server or if you prefer the convenience of a full desktop environment. To start it up, you can use (in a Bash/Unix shell):

./start_vnc.sh

On Windows, you can use the equivalent batch script (if the defaults are acceptable, it can also be started by double-clicking in Explorer):

.\start_vnc.bat

You can now access the Desktop Environment through your browser (http://localhost). The default password is abc123.

4.2.1 Variables for VNC

Both scripts will use default settings, which you can tweak by settings shell variables (VARIABLE=default is shown):

To overwrite the default settings, see Overwriting Shell Variables

4.3 Using a Local X-Server

This mode is recommended if the container is run on the local machine. It is significantly faster than VNC (as it renders the graphics locally), is more lightweight (no complete desktop environment is running), and integrates with the desktop (copy-paste, etc.). To start the container, run the following:

./start_x.sh

or

.\start_x.bat

Attention Windows and macOS users: The X-server connection is automatically killed if there is a too-long idle period in the terminal (when this happens, it looks like a crash of the system). A workaround is to start a second terminal from the initial terminal that pops up when executing the start scripts ./start_x.sh or .\start_x.bat and then start htop in the initial terminal. In this way, there is an ongoing display activity in the initial terminal, and as a positive side-effect, the usage of the machine can be monitored. We are looking for a better long-term solution.

Attention macOS users: Please disable the Enable VirtioFS accelerated directory sharing setting available as "Beta Setting," as this will cause issues accessing the mounted drives! However, enabling the VirtioFS general setting works in Docker >v4.15.0!

4.3.1 Variables for X11

The following environment variables are used for configuration:

4.3.2 macOS and Windows-specific Variables

For Mac and Windows, the X11 server is accessed through TCP (:0, aka port 6000). To control the server's address, you can set the following variable:

If the executable xauth is in PATH, the startup script automatically disables access control for localhost, so the X11 server is open for connections from the container. A warning will be shown if not, and you must disable access control.

4.3.3 Linux-specific Variables

For Linux, the local X11 server is accessed through a Unix socket. There are multiple variables to control:

The defaults for these variables are tested on native X11 servers, X2Go sessions, and Wayland. The script copies and modifies the cookie from the.Xauthority file into a separate, temporary file. This file is then mounted into the container.

4.3.4 Installing X11-Server

Everything should be ready on Linux with a desktop environment / UI (this setup has been tested on X11 and XWayland). For Windows and macOS, the installation of an X11 server is typically required. Due to the common protocol, every X11-server should work, although the following are tested:

For both X-Servers, it is strongly recommended to enable OpenGL:

4.4 Overwriting Shell Variables

4.4.1 For the Linux/macOS Bash Scripts

There are multiple ways to configure the start scripts using Bash. Two of them are shown here. First, the variables can be set directly for each run of the script; they are not saved in the active session:

DESIGNS=/my/design/directory DOCKER_USERNAME=another_user ./start_x.sh

The second variant is to set the variables in the current shell session (not persistent between shell restarts or shared between sessions):

export DESIGNS=/my/design/directory
export DOCKER_USERNAME=another_user
./start_x.sh

As those variables are stored in your current shell session, you only have to set them once. After setting, you can directly run the scripts.

4.4.2 For the Windows Batch Scripts

In CMD you can't set the variables directly when running the script. So for the .bat scripts, it is like the second variant for Bash scripts:

SET DESIGNS=\my\design\directory
SET DOCKER_USERNAME=another_user
.\start_x.bat

4.5 Using as devcontainer

This is a new usage mode, that might not fit your needs. Devcontainers are a great way to provide a working build environment along your own project. It is supported by the devcontainer extension in Visual Studio Code.

4.5.1 Add it to project

Option 1: In Visual Studio, click the remote window icon on the left and then "Reopen in Container", "Add configuration to workspace". Enter "ghcr.io/iic-jku/iic-osic-tools/devcontainer" as template, choose the version of the container and add more features (probably not needed). It will then restart the IDE, download the image and start a terminal and mount the work folder into the image.

Option 2: Alternatively you can directly just create the configuration file .devcontainer/devcontainer.json:

{
    "name": "IIC-OSIC-TOOLS",
    "image": "ghcr.io/iic-jku/iic-osic-tools-devcontainer:2024.09"
}

Either way, the great thing is that you can now commit the file to repository and all developers will be asked if they want to reopen their development in this container, all they need is Docker and VSCode.

5. Support with Issues/Problems/Bugs

We are open to your questions about this container and are very thankful for your input! If you run into a problem and you are sure it is a bug, please let us know by following this routine: