Course Website and Material (SystemVerilog) for CSE 140

Visit the site: abapages.com/digital-design

Quickstart on Examples

• Please do these three steps before the first lecture. If you need any support, we will help you during the office hours on Wednesday.
• You need a machine with either Ubuntu, Windows 11 or macOS and about 3–4 GB of space.

1. Install Docker on your system.

Ubuntu

• If you prefer detailed instructions, or if anything goes wrong, follow this instead..

1. Install Docker:

   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   sudo usermod -aG docker "$USER"

2. Test Docker:

   docker run --rm hello-world

macOS

• If you prefer detailed instructions, or if anything goes wrong, follow this instead.

1. Download Docker Desktop for Mac from here for your CPU architecture: Apple Silicon vs Intel.

2. Open the .dmg file.

3. Drag Docker into Applications.

4. Start Docker Desktop.

5. Test Docker:

   docker run --rm hello-world

Windows 11

• If you prefer detailed instructions, or if anything goes wrong, follow this instead.

1. Open PowerShell as Administrator.

2. Install WSL if you have not already:

   # Replace D:\WSL\Ubuntu with the desired location
   wsl --install -d Ubuntu --location D:\WSL\Ubuntu

3. Install Docker Desktop on Windows, not from WSL:

   1. Download and install Docker Desktop for Windows.
   2. Open Docker Desktop once and accept the license.
   3. Ensure Use the WSL 2 based engine is enabled; it is normally enabled automatically:
      1. Click the gear icon in the upper-right.
      2. Go to General.
      3. Under Choose how to Run Docker Containers, select WSL2
      4. Click Apply & restart.

4. Test whether Docker works correctly from PowerShell (use a regular terminal without administrator for everything now):

   wsl  # Enter WSL Ubuntu from a non-administrator powershell
   docker run --rm hello-world

2. Set up our Docker container:

Clone the repo, pull the docker image & start the container, and if you use macOS, do the extra step of setting up GUI.

git clone https://github.com/SkillSurf/digital-design
cd digital-design
make fresh         # This pulls the image and starts the container

For macOS, set up GUI forwarding

• If you prefer detailed instructions, or if anything goes wrong, follow this instead.

• After running make fresh:

  1. Visit vnc://localhost:5901 in a web browser.
  2. Allow the website to open Screen Sharing.
  3. You will see a black window. This is where any GUI from the Docker container will appear.
  4. Go back to the terminal to run other commands. The VNC window is for displaying GUI apps only.

3. Test one example with GUI:

make enter                            # Enter the container from the terminal while Docker is running
make sim gds show_layout DESIGN=alu   # This should run for a minute or two and show the KLayout GUI
# Ctrl+C                              # To exit KLayout
exit                                  # Exit the container; you can run make enter again later

Run Examples

From inside the Docker container (to be run from material directory, which is default when doing make enter):

make sim                 DESIGN=alu
make gds                 DESIGN=alu

make gds                 DESIGN=auto_light USE_BASIC_GATES=1
make show_syn_netlist    DESIGN=auto_light
make show_final_nestlist DESIGN=auto_light

make sim_all
make gds_all
make show_layout         DESIGN=alu
make show_3d             DESIGN=alu
make show_3d_cell        CELL=NAND2x1 
make show_3d_cell        # show all available cells
make show_layout_cells   

exit                     # to leave the container

• The root Makefile handles Docker, artifact collection, and site generation.
• The material/Makefile handles the in-container design flows.
• Reports and layout images are stored in material/openroad/work/reports/asap7/alu/base

For Staff

To locally serve the site

pip install sphinx furo myst-parser
make 3d_assets
make site
make serve

Then open http://localhost:8000 in your browser.

To publish the docker image without rebuilding it (for instructors)

The image only holds the toolchain (Verilator, Yosys, OpenROAD, FPGA tools); the course files are mounted from this repo at run time. So an existing, tested image can be copied to ghcr.io/skillsurf as-is.

On GitHub: Actions → publish-docker → Run workflow. It copies digital-design-amd64 and -arm64 into ghcr.io/skillsurf, links them to this repo, and runs a simulation in each to check them.

Or from your machine (copies registry-to-registry, without downloading the ~6.5 GB image):

echo <github-token> | docker login ghcr.io -u <github-username> --password-stdin
for ARCH in amd64 arm64; do
  docker buildx imagetools create \
    -t ghcr.io/skillsurf/digital-design-$ARCH:latest \
       ghcr.io/ucsd-cse140-s126/digital-design-$ARCH:latest
done

Then on GitHub, open SkillSurf → Packages → digital-design-amd64 (and -arm64) → Package settings: set visibility to Public so students can pull without logging in, and connect it to this repository. Rebuild from the Dockerfile (below) only when the Dockerfile changes.

To build and publish the docker container (for instructors)

To build that same image locally from the Dockerfile (slow, might take 3 hours on ARM), start and use it:

make scratch   # build from Dockerfile for your $ARCH & start
make enter     # Enter the container
# -------------- do the testing
exit           # Leave the container

# Publish the image your build & tested to ghcr.io/skillsurf/digital-design-$(ARCH):latest
GHCR_TOKEN=<github-token> GHCR_USER=<github-username> make publish   

The Makefile auto-detects ARCH from your machine (amd64 or arm64). You can still override it explicitly if needed, for example ARCH=arm64.

Get your GHCR token as:

• Log into GitHub, click your profile picture in the top right corner, and select Settings.
• Scroll all the way down the left sidebar and click on Developer settings.
• In the left menu, expand Personal access tokens, then select Tokens (classic).
• Click the Generate new token button, and choose Generate new token (classic).
• Give your token a descriptive name in the "Note" field (like "ghcr-login").
• Set an expiration date.
• Under Select scopes, check the boxes based on what you need to do:
  • read:packages: Required to download/pull container images.
  • write:packages: Required to upload/push container images. (Note: Checking this usually auto-selects the full repo scope. If you want to strictly limit the token to just packages for security, you can bypass the auto-select by clicking this specific link to create your token).
  • delete:packages: Required if you need the ability to delete images.
• Scroll to the bottom and click Generate token.