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/abarajithan11/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

Run on real hardware (Tang Nano 20K FPGA)

Implement a design onto a Sipeed Tang Nano 20K.

1. Build the bitstream in the container:

First you need to "compile" or implement your SystemVerilog code into a bitstream, which is a stream of bits that configures the FPGA to implement the digital logic you wanted.

make enter
make bitstream DESIGN=up_counter
exit

2. Program it via the web programmer

Windows: install the WebUSB driver through Zadig first

1. Download and run Zadig. It is portable and does not need to be installed.
2. Connect the Tang Nano 20K to Windows. Do not attach it to WSL yet.
3. In Zadig, select Options → List All Devices.
4. Select the Tang Nano JTAG interface, usually Dual RS232-HS (Interface 0) or Interface A.
5. Select WinUSB and click Replace Driver.
6. Close Zadig when the replacement finishes.

Only replace Interface 0/A. Do not replace Interface 1/B: it is the USB-UART interface used by uart_echo.py and fir_audio.py.

Next you need to send the bitstream to your FPGA (called programming the FPGA). Connect your FPGA to your machine, then visit openFPGALoader Web via Google Chrome. Note, Firefox does not support the required WebUSB access.

1. Visit the site, then choose

   • Automatic Operations
   • Tang Nano 20K
   • SRAM or Flash (SRAM is volatile, Flash persists after power-off)

2. and select the file:

   material/fpga/tang_nano_20k/build/up_counter/up_counter.fs
   

3. Then click Program FPGA. You will see this and the lights lighting up as a counter.

   Done
   DONE
   Execution completed in ---ms
   

3. UART Serial Examples - Sending data between your computer and FPGA

For UART examples, you need to switch the ownership of the USB port between Chrome, and your OS.

Ubuntu

Chrome cannot claim the board while the Linux FTDI serial driver owns it. Before programming, close programs using /dev/ttyUSB* and run:

sudo modprobe -r ftdi_sio

After programming, restore the serial ports for UART examples:

sudo modprobe ftdi_sio

Windows (WSL)

First connect the board to your computer. Now Windows owns it. Program from Chrome. For UART examples, switch the ownership to WSL after you program from Chrome.

To do this, open Powershell as Administrator. Then:

usbipd list
usbipd bind --busid <BUSID>
usbipd attach --wsl --busid <BUSID>

Run bind once from Administrator PowerShell. Run attach from a regular PowerShell each time the device is reconnected.

MacOS

Open the web programmer in Chrome, select the generated .fs file, and program the board. For UART examples, set the Python script's PORT to the board's /dev/tty.usbserial-* device.

More FPGA details are in material/fpga/tang_nano_20k/README.md.

4. Run the FIR audio example

The following commands build sys_fir_filter, load it into volatile FPGA SRAM, stream material/data/chill_sub.wav through the board, write material/data/fpga_out.wav, and compare it with the reference output.

1. From the digital-design repository root, build the bitstream inside the container:

   make enter
   make bitstream DESIGN=sys_fir_filter
   exit

2. Install the Python packages on the host once:

   python3 -m pip install --user numpy scipy pyserial

3. Program sys_fir_filter.fs into SRAM with openFPGALoader Web as described above. Restore or attach the serial device using the relevant OS section, then run the Python script. It resolves its WAV paths relative to itself, so it also works when invoked by absolute path from another directory.

   python3 material/py/fir_audio.py

Expected final output:

PASS: all 735000 samples match .../material/data/bass_only_8bit.wav.

5. Run the CPU

Build and program the CPU bitstream using the same container and web-programmer steps above:

make enter
make bitstream DESIGN=cpu_fpga
exit

Select material/fpga/tang_nano_20k/build/cpu_fpga/cpu_fpga.fs in the web programmer. Restore or attach the UART interface, then run:

python3 -m pip install --user pyserial  # one time
python3 material/py/program_cpu.py

The script loads a program that computes 1 + ... + 10. Press S1 when prompted to start the CPU. As it runs at one instruction per second, the LEDs show the opcode in binary. Hold S2 to show the low six bits of dmem[4] on the LEDs. When it is done, it streams the data RAM to the python script, and should print:

dmem[4] = 55  (sum(1..10) should be 55)

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 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/ucsd-cse140-s126/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.