Synthesizing SystemVerilog with Yosys on WSL
FPGA · Digital Logic · Open-Source Toolchain
From Code to Gates: Synthesizing SystemVerilog with Yosys on WSL
A Yosys-generated hardware schematic, rendered from SystemVerilog on WSL
Welcome back to AppliedKaos! In our previous guide, we dipped our toes into low-latency FPGA design by writing and simulating a SystemVerilog glitch filter using Icarus Verilog and GTKWave.
Simulation proves your logic works in a perfect, virtual environment. But an FPGA isn't a virtual machine — it's physical silicon.
Today we take the crucial next step: synthesis. We'll transform human-readable SystemVerilog into a netlist of real digital hardware components (logic gates, multiplexers, flip-flops) using Yosys, the workhorse of the open-source FPGA toolchain.
This is Part 2 of the AppliedKaos FPGA flow series. Ready for the next stage after this? Jump to Place and Route with NextPNR.
What Is Logic Synthesis?
If Icarus Verilog is a "debugger," Yosys is the "compiler."
In software, a compiler translates C++ or Python into machine code that a CPU executes sequentially. In hardware, a synthesizer translates Hardware Description Language (HDL) into a netlist.
A netlist is exactly what it sounds like: a list of electronic components (nets) and the wires connecting them. Yosys analyzes your always_ff blocks and if/else statements and figures out exactly how to wire up registers and logic gates to execute your behavior with deterministic latency.
The Two Stages of Synthesis
Generic Synthesis
Converts SystemVerilog into generic logic gates (AND, OR, NOT) and D-type flip-flops, independent of any specific chip.
Technology Mapping
Converts those generic gates into the specific physical resources (Look-Up Tables) available on your target FPGA, like a Lattice iCE40 or Xilinx Artix-7.
Today we'll focus on generic synthesis to visualize the hardware we've created, then add a bonus section on real technology mapping.
Step 1: Install Graphviz for Visualization
We're continuing in the same WSL Ubuntu 22.04 environment from Part 1. Make sure your OSS CAD Suite is still on your system PATH.
To see the hardware schematic Yosys generates, install Graphviz:
sudo apt update
sudo apt install -y graphvizVerify it installed correctly:
dot -V
# Expected output: dot - graphviz version 2.43.0 (or similar)Step 2: Create the Yosys Script
Navigate back to your project directory:
cd ~/kaos_fpga_filterWhile you can run Yosys interactively, scripting it is best practice. Create synth.ys:
# synth.ys - AppliedKaos Yosys Synthesis Script
# 1. Read the SystemVerilog design file
read_verilog -sv glitch_filter.sv
# 2. Check the design hierarchy and set the top module
hierarchy -check -top glitch_filter
# 3. Perform generic synthesis
# (We use 'prep' instead of 'synth' here to keep the schematic readable and
# generic, rather than mapping it to a highly optimized, hard-to-read
# FPGA-specific architecture just yet)
prep -top glitch_filter
# 4. Clean up unused signals and optimize
clean
# 5. Output a visual schematic of our hardware (generates an SVG file)
show -format svg -prefix glitch_filter_schematic
# 6. Write the generic netlist to a JSON file (useful for later stages)
write_json glitch_filter_netlist.jsonStep 3: Run the Synthesis
yosys synth.ysYou'll see a wall of text fly by — that's Yosys analyzing the logic, optimizing away dead code, identifying your THRESHOLD parameter, and constructing the circuit graph.
Look for a line near the end:
Output filename: glitch_filter_schematic.svgIf you see that, synthesis succeeded.
stat right before write_json in your script to print a resource summary (cell counts, wire counts) straight to the terminal — handy for catching an accidentally-huge design before you even open the schematic.
statStep 4: View Your Hardware Schematic
On WSL, viewing an SVG straight from the terminal is tricky without an X-server. The easiest path is opening the file in your Windows browser:
explorer.exe glitch_filter_schematic.svg(Alternatively, copy the .svg to /mnt/c/Users/YourName/Desktop and open it normally.)
The generic gate-level schematic of the glitch filter, rendered by Graphviz
Bonus: Mapping to a Real FPGA Target
Generic synthesis is great for learning, but eventually you want gates mapped to actual LUTs on your target chip. If you're following along toward a Lattice iCE40 board (see recommendations below), swap prep for a real target-specific synth command:
# synth_ice40.ys - technology-mapped synthesis for Lattice iCE40
read_verilog -sv glitch_filter.sv
hierarchy -check -top glitch_filter
# Full iCE40-targeted synthesis: maps generic gates to real iCE40 LUTs/DFFs
synth_ice40 -top glitch_filter -json glitch_filter_ice40.json
statRun it the same way:
yosys synth_ice40.ysCompare the stat output between the generic run and this one — you'll see actual SB_LUT4 and SB_DFF cell counts instead of abstract $dff/$mux cells. That JSON file is exactly what NextPNR consumes in the next part of this series.
Bonus: Automating the Flow with Make
Once you're running this more than twice, script it. Drop this Makefile in your project root:
# Makefile - AppliedKaos FPGA synthesis automation
TOP = glitch_filter
SRC = glitch_filter.sv
.PHONY: all synth ice40 view clean
all: synth
synth:
yosys synth.ys
ice40:
yosys synth_ice40.ys
view: synth
explorer.exe $(TOP)_schematic.svg
clean:
rm -f *.svg *.jsonNow the whole flow is one command:
make viewUnderstanding the Yosys Output
When you open the SVG, you're looking at the actual hardware architecture of your glitch filter:
D-Type Flip-Flops
$dff cells represent your counter, clean_out, and sampling registers, synchronized to the clk signal.
Multiplexers
$mux cells are the hardware form of your if/else statements, choosing which data path feeds each register.
Adders
$add blocks represent counter <= counter + 1'b1;.
Comparators
$eq/$ge cells check whether the counter has reached THRESHOLD.
By keeping logic shallow — minimizing gates between flip-flops — signals can propagate through the entire schematic within a single clock cycle, preserving that ultra-low latency.
Recommended Gear for This Series
Affiliate disclosure: AppliedKaos is a participant in the Amazon Associates program. If you buy through these links, I may earn a small commission at no extra cost to you — it helps keep this blog running. I only recommend gear I've actually used or would use myself.
| Item | Why It's Worth It | Link |
|---|---|---|
| Lattice iCE40 dev board (e.g. iCEBreaker) | Fully supported by the open-source toolchain (Yosys + NextPNR + IceStorm), no vendor tools required. | Check price → |
| ULX3S (Lattice ECP5) | More logic cells if you outgrow the iCE40, still fully open-source. | Check price → |
| USB-C logic analyzer | Invaluable once you move past simulation and want to probe real signal timing. | Check price → |
| Digital Design and Computer Architecture — Harris & Harris | The book that made this material click for me. | Check price → |
| FPGA Prototyping by SystemVerilog Examples — Pong P. Chu | Excellent hands-on companion once you're past the basics. | Check price → |
FAQ
Is Yosys free and open-source?
Yes — Yosys is released under an ISC license and is the synthesis backbone of the entire open-source FPGA toolchain (alongside NextPNR and IceStorm/Trellis).
What's the difference between simulation and synthesis?
Simulation (Icarus Verilog + GTKWave, from Part 1) proves your logic behaves correctly in software. Synthesis (this post) proves that logic can actually be built as real hardware gates.
Can Yosys target Xilinx or Intel/Altera FPGAs?
Yosys has growing support for Xilinx (via synth_xilinx) and some Intel families, though the open-source place-and-route ecosystem is most mature for Lattice iCE40 and ECP5 devices.
Do I need Windows/WSL specifically, or does this work on native Linux?
Everything here runs identically on native Linux or macOS — WSL is only relevant for the explorer.exe viewing step; substitute your OS's default SVG viewer instead.
Why use prep instead of synth in the first script?
prep performs generic synthesis and stops before technology mapping, which keeps the schematic human-readable. synth/synth_ice40 goes further and maps directly to target-specific LUTs, which is harder to read but necessary before place-and-route.
Conclusion
You've successfully transitioned from writing abstract code to generating a concrete hardware schematic using entirely open-source tools. You can now visually prove that your SystemVerilog translates into a clean, predictable circuit.
Simulation proves your logic is correct. Synthesis proves your logic is buildable. The next step in the FPGA design flow is place and route on the board!
Enjoyed this? Subscribe to the newsletter for the rest of the FPGA-from-scratch series, or follow along on GitHub.
Disclosure: This post contains affiliate links. If you make a purchase through them, AppliedKaos may earn a small commission at no extra cost to you. All recommendations are based on genuine use and opinion.
Comments
Post a Comment