🖥️ PixelCore — Build a RISC-V CPU in Simulation · Part 1 · Beginner

Setting Up Your Toolchain: Installing WSL2

Part one of building PixelCore — a RISC-V CPU that runs real compiled C and draws graphics, all in simulation. Before any Verilog, we set up the one thing the whole toolchain sits on: WSL2, a real Linux environment inside Windows.

In this part

What WSL2 is and why it's the foundation for the whole PixelCore toolchain.
Installing WSL2 with Ubuntu on Windows 11, from a clean machine.
Verifying the install and setting up your first Linux environment correctly.

Part 1 Part 2 Part 3

Welcome to PixelCore — a build series where we design a real RISC-V CPU in SystemVerilog, run actual compiled C programs on it, and watch it render graphics to a screen. The catch, and the fun part: it all happens in simulation. No FPGA, no dev board, no wiring. Just code, a simulator, and output you can see.

Before we write a single line of Verilog, we need a place to build. The professional open-source tools we’ll use — Verilator, the RISC-V GCC compiler, GTKWave — all live in the Linux world. On Windows, the cleanest way to get a real Linux environment without dual-booting or a heavy virtual machine is WSL2. That’s what this first part sets up.

What WSL2 actually is

WSL stands for Windows Subsystem for Linux. Version 2 (WSL2) runs a real Linux kernel inside a lightweight, tightly-integrated virtual machine. In practice that means:

You get a full Ubuntu command line that behaves exactly like Linux, because it is Linux.
It starts in seconds and uses far fewer resources than a traditional VM like VirtualBox.
Your Windows files and your Linux files can see each other, so you can edit code in a Windows editor (VS Code) while it builds and runs on the Linux side.
Later in this series, WSL2’s built-in graphics support (WSLg) will let a real window pop up on your Windows desktop showing the graphics our CPU renders.

Before you start

You’ll need:

Windows 11 (or Windows 10 version 2004 / build 19041 or later). Windows 11 is ideal — it ships with WSLg for GUI apps out of the box, which we’ll want later.
Administrator access on your machine (to run one elevated command).
Virtualization enabled in your BIOS/UEFI. On most modern PCs it’s on by default. If the install later complains about virtualization, that’s the setting to check.
A working internet connection — the install downloads the Linux kernel and Ubuntu.

Step 1 — Open PowerShell as Administrator

Click the Start menu, type PowerShell, then right-click Windows PowerShell and choose Run as administrator. Click Yes on the prompt.

You should see a blue terminal window. Everything in the next step happens here.

Step 2 — Run the install command

Microsoft has boiled the entire setup down to a single command. In the admin PowerShell window, type:

🪟 Run in Windows PowerShell (as Administrator):

wsl --install

Press Enter. This one command does all of the heavy lifting:

Enables the required Windows features (the Virtual Machine Platform and WSL).
Downloads and installs the latest Linux kernel.
Sets WSL2 as the default version.
Downloads and installs Ubuntu (the default distribution).

💡If PowerShell says 'wsl' isn't recognized, add .exe

On some Windows setups the bare wsl command doesn’t resolve in PowerShell, but the full wsl.exe always does. So if wsl --install isn’t recognized, run:

wsl.exe --install

The same applies to every wsl command later in this guide — if one isn’t found, just add the .exe (e.g. wsl.exe --list --verbose).

You’ll see progress messages as each piece downloads. Give it a few minutes.

Step 3 — First launch of Ubuntu

After rebooting, Ubuntu often launches on its own to finish setup. If it doesn’t, open the Start menu and click Ubuntu (or type ubuntu and hit Enter).

The first launch takes a minute while it unpacks. Then it asks you to create your Linux user account:

Enter a username — lowercase, no spaces (e.g. pulasthi). This is separate from your Windows account.
Enter a password — you won’t see any characters as you type; that’s normal Linux behaviour, not a frozen terminal. You’ll use this password for admin (sudo) commands.

When you’re done you’ll land at a green prompt that looks something like this:

pulasthi@DESKTOP-XXXX:~$

That’s a real Linux shell. You’re in.

Step 4 — Verify your install

Before building anything on top of WSL2, let’s confirm all of it is actually correct. There are a few quick checks, and they’re worth doing — a subtle problem here (like accidentally being on WSL1) will only surface much later as a confusing tool failure.

First, from a normal PowerShell window (no admin needed this time):

🪟 Run in Windows PowerShell:

wsl --list --verbose

You should see something like:

  NAME      STATE           VERSION
* Ubuntu    Running         2

The 2 in the VERSION column is the single most important thing — it confirms you’re on WSL2, not WSL1. Then check the WSL and kernel versions:

🪟 Run in Windows PowerShell:

wsl --version

This prints the WSL version and the Linux kernel version. If PowerShell doesn’t recognise the command, you’re on an older build — run wsl --update and try again.

Next, launch Ubuntu itself (Start menu → Ubuntu, or just type wsl) and confirm it’s a real, up-to-date Linux system. Check the distribution:

🐧 Run in Ubuntu:

lsb_release -a

Distributor ID: Ubuntu
Description:    Ubuntu 24.04 LTS
Release:        24.04
Codename:       noble

Confirm you’re on a genuine WSL2 kernel:

🐧 Run in Ubuntu:

uname -r

The output ends in -microsoft-standard-WSL2 (e.g. 5.15.167.4-microsoft-standard-WSL2). That WSL2 suffix is your proof the real Linux kernel is running. Finally, make sure Ubuntu can reach the internet — it’ll need to, to download the toolchain in Part 2:

🐧 Run in Ubuntu:

ping -c 3 google.com

Three replies means networking is good.

💡What 'good' looks like, at a glance

Check	Command	Good result
Distro installed + on WSL2	`wsl --list --verbose`	`Ubuntu` … `2`
WSL + kernel present	`wsl --version`	shows a kernel version
It’s really Ubuntu	`lsb_release -a`	`Ubuntu 24.04 LTS`
Genuine WSL2 kernel	`uname -r`	ends in `-microsoft-standard-WSL2`
Internet works	`ping -c 3 google.com`	3 replies

If everything above checks out, you’re done — skip ahead to updating Ubuntu. If the version column showed 1, fix it first:

🪟 Run in Windows PowerShell:

wsl --set-version Ubuntu 2

Step 5 — Update Ubuntu

A fresh Ubuntu ships with a slightly outdated package list. Back in your Ubuntu terminal, run:

🐧 Run in Ubuntu:

sudo apt update && sudo apt upgrade -y

Enter your Linux password when prompted. This refreshes the catalogue of available software and upgrades anything already installed. It’s good hygiene and it primes the system for the tools we install in Part 2.

One habit that will save you later: where your files live

WSL2 can see your Windows files under /mnt/c/..., and it’s tempting to keep your project on the Windows side. Don’t — at least not for the build files.

For now, just make a home for the project so it’s ready:

🐧 Run in Ubuntu:

mkdir -p ~/pixelcore && cd ~/pixelcore

You’re standing in the folder where, over the coming parts, an entire CPU will take shape.

Where we’re headed next

You now have a real, fast Linux environment living inside Windows — the foundation the whole PixelCore project is built on. Nothing about the rest of this series will feel like fighting your tools, and that’s exactly the point.

In Part 2, we install the actual toolchain: Verilator (the simulator that turns our SystemVerilog into a running program), GTKWave (for reading waveforms — our debugger), the RISC-V GCC compiler (so we can write C and run it on our CPU), and wire up VS Code to edit everything from Windows. By the end of that part you’ll compile and run your very first SystemVerilog module and watch it work.

Then, finally, we start designing hardware.