Skip to content

Site Guide

How the course site and repository are organized

The site is organized into five top-level tabs accessible from the header:

Tab What's there
Home Course overview, syllabus, setup guide, project info, module library, curriculum map
Week 1 Days 1–4: Verilog foundations, combinational logic, procedural logic, sequential logic
Week 2 Days 5–8: Counters/debouncing, testbenches & AI verification, FSMs, hierarchy & generate
Week 3 Days 9–12: Memory, numerical architectures & PPA, UART TX, UART RX & SPI
Week 4 Days 13–16: SystemVerilog, verification & PPA analysis, project build day, demo day

What's on Each Day's Page

Every day (except Days 15–16) has four sub-pages:

Day Landing Page — links to all resources for that day: pre-class video segments with slide links, lecture code examples, and navigation cards to the plan, quiz, and lab.

Daily Plan — the session timeline with instructor notes: pre-class topics, mini-lecture outline, lab breakdown, and deliverables. Useful as a review tool after class.

Pre-Class Quiz — self-check questions with collapsible answers. Work through these after watching the pre-class video and before class. They're ungraded — the goal is to catch gaps before the hands-on lab.

Lab Guide — step-by-step exercises with embedded starter code downloads, solution zips, and links to source files on GitHub. Each exercise section has its own download buttons. Notebook versions are available for JupyterLab users.

Repository Structure

The Git repository mirrors the site structure:

hdl-for-dsd/
├── docs/                 ← Daily plans + course-level docs (markdown)
├── lectures/             ← Slide decks (Reveal.js HTML) + quiz source files
│   ├── week1_day01/
│   │   ├── d01_s1_*.html       ← Slide segments
│   │   ├── day01_quiz.md       ← Quiz source (symlinked into site)
│   │   └── code/               ← Lecture code examples
│   └── ...
├── labs/                 ← Lab exercises with starter + solution code
│   ├── week1_day01/
│   │   ├── README.md           ← Lab guide source
│   │   ├── ex1_led_on/
│   │   │   ├── starter/        ← What you start with
│   │   │   └── solution/       ← Reference solution
│   │   └── ...
│   └── ...
├── notebooks/            ← Auto-generated Jupyter notebook versions
├── shared/
│   ├── lib/              ← Reusable module library (uart_tx, debounce, etc.)
│   └── pcf/              ← Pin constraint file for the Go Board
├── projects/             ← Final project specs and rubrics
├── scripts/              ← Build scripts (prep_mkdocs.py, build_all.sh, etc.)
├── docs_src/             ← Generated MkDocs source (don't edit directly)
├── mkdocs.yml            ← Site configuration
└── flake.nix             ← Nix development environment

Which files to edit

  • Lab content → edit labs/weekX_dayYY/README.md
  • Daily plans → edit docs/dayNN.md
  • Quiz questions → edit lectures/weekX_dayYY/dayNN_quiz.md
  • Lecture slides → generated by Python scripts in scripts/; edit the generators, not the HTML
  • Site pages → docs_src/ is auto-generated by prep_mkdocs.py; edit the source files above instead

The Toolchain at a Glance

                    ┌──────────┐
  Verilog (.v) ───→ │  Yosys   │ ──→ JSON netlist
                    └──────────┘
                         │
                    ┌──────────┐
                    │ nextpnr  │ ──→ ASC placement
                    └──────────┘
                         │
                    ┌──────────┐
                    │ icepack  │ ──→ BIN bitstream
                    └──────────┘
                         │
                    ┌──────────┐
                    │ iceprog  │ ──→ Go Board
                    └──────────┘

For simulation, a parallel path:

  Verilog (.v) + Testbench (.v) ──→ iverilog ──→ VVP ──→ vvp ──→ VCD ──→ GTKWave

Every lab's Makefile wraps both flows: make sim for simulation, make prog for hardware.

Pre-Class Workflow

Before each class session:

  1. Watch the assigned video segments (linked on the day's landing page)
  2. Work through the pre-class quiz to check understanding
  3. Download the starter code from the lab guide (or clone/pull the latest repo)
  4. Enter the development environment: cd hdl-for-dsd && nix develop

Building the Site Locally

# Enter the full dev environment (includes MkDocs)
nix develop .#full

# Build and preview
./scripts/build_all.sh --serve
# Open http://127.0.0.1:8000

The build pipeline: prep_mkdocs.py generates docs_src/ → MkDocs builds _site/ → slides and notebooks are copied in.