Lab 1: Development Environment, Git, GitHub, and Design Notebook

- Made by Hans :)

Overview

Due date: 11:59 PM 09/21/26 via design notebook.

Welcome to the Processor Design VIP! The objective of this lab is to make sure you know how to submit your design notebook and complete your first RTL exercise.

You will:

1. Set up your development environment with Git and Verilator.
2. Set up GitHub and your Design Notebook (DN).
3. Create your onboarding repository.
4. Write a small SystemVerilog module and testbench.
5. Verify the design with Verilator.
6. Submit your work through a pull request.
7. Document the work in your DN.

All onboarding labs should be stored in the same repository.

Before starting, make sure you can access the official Processor Design VIP GitHub repositories. If you cannot access them, ask a lead before continuing.

1. Set Up Your Development Environment

You need a Unix-like environment for development in this VIP.

If you use Windows, I recommend using VS Code with WSL (Windows Subsystem for Linux).

Linux users may use their native environment. macOS users may use the native terminal with Homebrew.

You are responsible for setting up your development environment before continuing.

Once you set up your environment, install Git and Verilator.

For Ubuntu/Linux or WSL, install Git and Verilator with:

sudo apt update
sudo apt install -y git verilator

For macOS:

brew update
brew install git verilator

Verify both installations:

git --version
verilator --version

Git is used for version control and collaboration through GitHub.

Verilator is used to compile and simulate SystemVerilog designs. We will use it throughout onboarding and project development.

2. Complete the Git and Design Notebook Setup

Before continuing, complete the existing:

Design Notebooks and Git Guide

Make sure you have:

• a GitHub account,
• Git configured,
• GitHub authentication working,
• access to the official VIP documentation repository,
• forked and cloned the VIP documentation repository,
• configured origin and upstream.

As part of this setup, create your Fall 2026 design notebook under:

src/design_notebooks/2026fall/

Use the naming (netID.md) and structure described in the existing guide.

You will submit your first design notebook PR after completing this lab using the instructions in Section 8.

You should also be comfortable with:

branch → commit → push → pull request → merge

and with updating your fork from the official repository.

If any of this is unclear, please review the Git guide or ask a lead or experienced member before continuing.

3. Create Your Onboarding Repository

Create a new public GitHub repository named:

processor-design-onboarding

Initialize it with a README.md.

This repository will contain all of your onboarding labs.

Clone it:

git clone git@github.com:<your-username>/processor-design-onboarding.git
cd processor-design-onboarding

Before making any Lab 1 changes, create a branch:

git switch -c lab_1

All work for this lab should be done on this branch.

4. Create the RTL and Testbench

Create the following structure:

processor-design-onboarding/
├── README.md
├── .gitignore
└── lab_1/
    ├── rtl/
    │   └── simple_and.sv
    └── tb/
        └── simple_and_tb.sv

To create the directories, you can run:

mkdir -p lab_1/rtl lab_1/tb

.gitignore

Verilator, which we use to compile and simulate SystemVerilog designs, will generate obj_dir/ during compilation. These generated files should not be committed.

.gitignore tells Git which files or folders should normally be ignored when staging changes, including when using git add ..

Add this to .gitignore:

obj_dir/

RTL

RTL stands for Register-Transfer Level. It is a hardware design abstraction that describes digital circuits in terms of registers, the data transferred between them, and the combinational logic that operates on that data.

In practice, when we refer to the RTL for our projects, we generally mean the synthesizable Verilog/SystemVerilog code that describes the hardware. If this is unfamiliar, don’t worry; later labs will cover RTL design in more detail.

Now it’s time to create your first SystemVerilog module.

Create:

lab_1/rtl/simple_and.sv

with:

module simple_and (
    input  logic a,
    input  logic b,
    output logic y
);

    assign y = a & b;

endmodule

This implements a two-input AND gate.

If this module confuses you, stop and review the code or ask a lead or experienced member before continuing.

If you have previously used Verilog, this should look very familiar. One visible SystemVerilog difference is the use of:

logic

instead of many uses of wire and reg.

SystemVerilog will be covered in more detail in later labs.

Testbench

Create:

lab_1/tb/simple_and_tb.sv

with:

module simple_and_tb;

    logic a;
    logic b;
    logic y;

    simple_and dut (
        .a(a),
        .b(b),
        .y(y)
    );

    initial begin
        a = 0; b = 0; #1;
        if (y !== 0) $fatal(1, "00 failed");

        a = 0; b = 1; #1;
        if (y !== 0) $fatal(1, "01 failed");

        a = 1; b = 0; #1;
        if (y !== 0) $fatal(1, "10 failed");

        a = 1; b = 1; #1;
        if (y !== 1) $fatal(1, "11 failed");

        $display("All tests passed!");
        $finish;
    end

endmodule

You do not need to understand every detail of the testbench yet. Later labs will cover SystemVerilog and verification more thoroughly.

5. Run the Design with Verilator

From the repository root, compile:

verilator --binary --timing \
    lab_1/rtl/simple_and.sv \
    lab_1/tb/simple_and_tb.sv \
    --top-module simple_and_tb

Run the generated simulation:

./obj_dir/Vsimple_and_tb

You should see:

All tests passed!

Do not continue until the simulation passes.

6. Commit and Push Your Work

Check what changed:

git status

You can stage specific files:

git add lab_1
git add .gitignore

or stage all non-ignored changes:

git add .

Run git status again before committing to confirm that only the files you expect are staged.

Commit:

git commit -m "Complete Lab 1"

Push your branch:

git push -u origin lab_1

7. Submit Your Work Through a Pull Request

On GitHub, open a pull request from:

lab_1

into:

main

Before merging, inspect the Files changed tab and verify that the PR contains only the intended files.

Since this is your own onboarding repository, you may merge your own PR.

Use:

Squash and merge

After the PR is merged, delete the remote branch when GitHub offers the option.

Update your local repository:

git switch main
git pull

Then delete the local branch:

git branch -d lab_1

For future labs, create a new branch from the updated main branch and add a new folder such as lab_2/, lab_3/, etc.

8. Document the Lab in Your Design Notebook

Follow the Design Notebooks and Git Guide to update your Fall 2026 notebook under:

src/design_notebooks/2026fall/

For Lab 1, briefly describe:

• what you completed,
• what you learned,
• any problem or difficulty you encountered,
• and include a link to your onboarding repository.

Example:

## Week 1

This week I completed the first onboarding lab. I set up Verilator,
created a small SystemVerilog module and testbench, and practiced the
branch and pull request workflow.

One issue I encountered was [...]. I resolved it by [...].

### Work

- [Processor Design Onboarding](https://github.com/<your-username>/processor-design-onboarding)

Write about your own work rather than copying the example.

For this and future weekly notebook submissions, use the PR title format:

docs(dn): First Last mm/dd/yy

Example:

docs(dn): Jane Smith 09/15/26

Submit the design notebook PR according to the guide, and a VIP lead will review and merge it.

Completion Checklist

• Git/design notebook setup completed
• Verilator installed and working
• processor-design-onboarding repository created
• lab_1/ completed and simulation passes
• Lab 1 PR squash-merged into main
• Week 1 design notebook entry submitted

Reminder: Lab 1 is due via your design notebook by 11:59 PM on 09/21/26.

After you complete this lab, you may work ahead on later labs in order. However, remember a design notebook entry is required every week regardless of lab completion.