Skip to main content

Lab 03: Launch the workbench

You’ll clone the team’s workspace repo, start the IIC-OSIC-TOOLS container, open its desktop in your browser, and run the smoke test. Then you’ll restart the container and check which of your files survived. When the smoke test prints === All checks passed === after that restart, your setup is ready for every later course.

Other courses link here for their workbench setup, so if one of them sent you, do this whole lab and then go back to that course.

Before you start

  • You need git and Docker on your laptop. In a terminal there, run:

    git --version
    docker run --rm hello-world

    The first should print a version number, and the second a paragraph starting with Hello from Docker!. If git is missing, do Lab 01 first. If Docker isn’t installed, do Lab 02. If it’s installed but the command fails, Docker may still be starting: wait until Docker Desktop shows Engine running and try again. If it still fails, or you run Docker Engine on Linux without Docker Desktop, see Troubleshooting.

  • On a Mac, give Docker Desktop at least 4 GB of RAM under Settings → Resources (Lab 02, Part 1).

  • Read The workbench desktop and What the smoke test checks.

  • Have roughly 15 GB of free disk and a stable network connection, because the first launch downloads an image that is several GB in size.

Time: 30 minutes to 1 hour, most of it waiting for the first download.

Part 1: Clone the workspace

  1. Open a terminal on your laptop.

  2. Run:

    git clone https://github.com/uoftasic/workspace.git
    cd workspace

    The first command creates a folder named workspace inside the folder your terminal is in, and puts the team’s scripts and configuration in it. The second moves your terminal into workspace. Remember which folder you ran this in, because you’ll run the laptop commands in Parts 2 and 5 from inside workspace, and later courses start the workbench from it too.

You should see git print Cloning into 'workspace'... and finish without an error. If you get git: command not found, go back to Lab 01. If git says fatal: destination path 'workspace' already exists, you’ve already cloned it in this folder, so run cd workspace and use that clone.

Part 2: Start the container

  1. From inside workspace, start the container.

    On macOS or Linux:

    ./scripts/start_vnc.sh

    On Windows, run it from Windows Terminal or PowerShell:

    scripts\start_vnc.bat

    You can also double-click scripts/start_vnc.bat in File Explorer, but the window may close when the script ends, before you can read what it printed.

  2. Wait for the script to finish. The first run downloads hpretl/iic-osic-tools:2026.08 and can take several minutes.

You should see the script end with a block that starts === Open in your browser ===, followed by the desktop’s address and password.

If the script fails because port 80 is in use, start it on another port (on macOS or Linux, HOST_PORT=8080 ./scripts/start_vnc.sh) and use http://localhost:8080/ in Part 3. Other failures are in Troubleshooting.

Part 3: Open the desktop

  1. In your browser, go to http://localhost/, or http://localhost:<HOST_PORT>/ if you set a port in Part 2.

    The noVNC password prompt The address bar shows plain localhost, which means the default port, 80. With HOST_PORT=8080 it would show localhost:8080.

  2. Enter the password the script printed: abc123, unless you changed it with VNC_PW (Settings you can change).

You should see a Linux desktop with a column of icons down the left, including Terminal, XSchem and Magic.

The workbench desktop, loaded The desktop, running inside the browser tab. Connected to ... in the top bar means the VNC session is live. Every later course that uses the tools runs on this machine.

If the page is blank or won’t load, wait 30–60 s and reload. If it’s still blank, see Troubleshooting.

Part 4: Run the smoke test

Every command in this part runs in a terminal inside the noVNC desktop, not on your laptop. Inside the container, your workspace folder is /foss/designs.

  1. Open Terminal from the icons on the left of the desktop. To paste a command from this page into it, press Ctrl+Shift+V, or use the clipboard icon in the noVNC sidebar. Plain Ctrl+V doesn’t paste into the desktop.

  2. Load the workspace environment:

    . /foss/designs/common/.designinit

    .designinit points the tools at the SKY130 PDK and defines the mod command you’ll use in steps 4 and 5. The . and the space after it are part of the command, because the . is what loads the file into this terminal.

    You should see:

    ASIC-EDU: PDK=sky130A  PDK_ROOT=/foss/pdks  designs=/foss/designs
              run 'mod' to list course modules, or 'mod <name>' to enter one.

    A new terminal on the desktop loads this file by itself, so you may already have seen these two lines when the terminal opened. Running it again does no harm, and it’s also the fix if a terminal ever says bash: mod: command not found.

  3. Run the smoke test:

    /foss/designs/scripts/smoke_test.sh

    You should see the same two ASIC-EDU lines, then:

    === ASIC-EDU workspace smoke test ===
    OK  ngspice
    OK  xschem
    OK  magic
    OK  netgen
    OK  yosys
    OK  PDK sky130A at /foss/pdks/sky130A
        ngspice-47
    --- module helpers ---
    OK  mod function loaded
    OK  add_module.sh present
    OK  mod lists ic101_setup
    OK  mod ic101_setup
    === All checks passed ===

    The indented ngspice-47 line is the ngspice version. If any line says FAIL or WARN, see Smoke test: tool or helper not found or Smoke test: PDK is not sky130A.

  4. List the course modules:

    mod

    You should see Available modules: and, under it, ic101_setup.

  5. Go to IC101’s scratch folder:

    mod ic101_setup

    You should see cwd: /foss/designs/modules/ic101_setup.

Part 5: Restart the container

Step 3 below is how you stop the workbench, and steps 4 and 5 are how you start it again at the beginning of every later session. Before you restart it, you’ll save two test files and predict which of them the restart keeps.

  1. In the desktop terminal, save one file in your workspace and one in the container’s /tmp folder:

    echo "saved in the workspace" > /foss/designs/modules/ic101_setup/restart-test.txt
    echo "saved in the container" > /tmp/restart-test.txt
  2. Write down which of the two files you expect to find after you remove the container and start a new one.

  3. In a terminal on your laptop (not the desktop), stop and remove the container. The launch script named it asic-edu-osic:

    docker rm -f asic-edu-osic

    It prints the name, asic-edu-osic, when the container is gone.

  4. From inside your workspace folder, start the container again as in Part 2: ./scripts/start_vnc.sh on macOS or Linux, scripts\start_vnc.bat on Windows. This time the image is already on your computer, so there’s nothing to download.

  5. Reload http://localhost/ (or your HOST_PORT address), enter the password, and open Terminal from the icons on the left. If the page is blank, wait 30–60 s and reload, as in Part 3.

  6. Look for both files:

    cat /foss/designs/modules/ic101_setup/restart-test.txt
    cat /tmp/restart-test.txt
  7. Run the smoke test again:

    /foss/designs/scripts/smoke_test.sh

In step 6 you should see the workspace file’s text, then an error for the /tmp file:

saved in the workspace
cat: /tmp/restart-test.txt: No such file or directory

In step 7, the smoke test should end with === All checks passed ===, as in Part 4. Compare the cat output with what you wrote down in step 2.

/foss/designs is your workspace folder on your laptop, mounted into the container, so the first file is on your own disk and survives. /tmp exists only inside the container, and docker rm -f deleted the container with everything in it.

Keep your course work under /foss/designs. Even if you skip step 3, start_vnc removes any old asic-edu-osic container before it starts a new one, so every launch gives you a fresh container and anything you saved outside /foss/designs is lost. You can leave restart-test.txt where it is, since ic101_setup is IC101’s scratch folder.

Finishing

You’re done when, after the restart in Part 5, the smoke test ends with === All checks passed === in a desktop terminal and restart-test.txt is still in ic101_setup.

Submit

Nothing to submit. Keep the workspace clone, though, because every later course that uses the tools runs in it.

Next on the Course path: read Where each tool sits in the tapeout flow. If another course sent you here, go back to the page that sent you. Courses that use the tools add their own files to your workspace with mod add <course>, which What the smoke test checks describes.