Logic synthesis with Yosys

Synthesis turned this lesson’s 13-line counter into 22 gates and flip-flops, and the design passed through 101 cells on the way there. Logic synthesislogic synthesis: The step that turns RTL into a netlist of a target's cells: standard cells for a chip, or look-up tables and flip-flops for an FPGA. More in “How chips are designed and verified” with Yosys is a script of passes, each one a command whose result you can count, so you can watch what every pass does to your design and notice when one does something you did not mean.

Here you run the main passes one at a time on an 8-bit counter, read the cell statistics after each, and check the result against Yosys’s whole default script. Then the same counter goes to three targets, with the area each costs, and two short designs show the synthesis messages that point to bugs in the RTL.

Synthesis builds cells from always blocks, one pass at a time

counter.sv is an 8-bit counter with a synchronous reset and an enable, written as one always_ff block. Yosys reads it into RTLILRTLIL: Yosys's internal form of a design: modules made of cells, wires and processes. Every Yosys pass reads RTLIL and writes it back, so a script is a chain of rewrites of one design., its own form of a design, and every pass after that reads RTLIL and rewrites it. Step through the passes of a typical script, with the number of cells the counter has after each:

Two of those passes do the work that a person would call synthesis. proc turns processes, the always blocks, into coarse cells: a $dff for the eight flip-flops, a $mux for the enable and one for the reset, an $add for the increment. techmap later replaces each coarse cell with gates from Yosys’s own gate library, the step called technology mappingtechnology mapping: The step of synthesis that replaces generic cells with the cells of a target: gates of a library, look-up tables and flip-flops of an FPGA, or the standard cells of a chip process.. Between and after them, opt merges and removes cells, and abc rewrites the gates into fewer ones.

Yosys’s built-in reader takes Verilog-2005 and a part of SystemVerilog with read_verilog -sv; the build used here also has read_slang, a front end built on the slang compiler, which reads far more of SystemVerilog, as the lesson on structs and interfaces showed on an interface design.

Cell statistics show what each pass did

stat counts the cells of a design by type, and tee -q -o writes its report to a file. passes.ys runs the four passes by hand and keeps a report after each; the last command runs synth, Yosys’s default script, on the same RTL:

// A W-bit counter with a synchronous reset and an enable: the design that every target synthesises below.
module counter #(
  parameter int W = 8
) (
  input  logic         clk,
  input  logic         rst,      // synchronous, active high
  input  logic         en,
  output logic [W-1:0] q
);
  always_ff @(posedge clk)
    if (rst)     q <= '0;
    else if (en) q <= q + 1'b1;
endmodule

# The main passes of a synthesis script, one at a time, with the cell statistics after each.
read_verilog -sv counter.sv
hierarchy -check -top counter
proc
tee -q -o proc.txt stat
opt
tee -q -o opt.txt stat
techmap
tee -q -o techmap.txt stat
opt
abc
opt_clean
tee -q -o abc.txt stat

from session import run

# passes.ys runs proc, opt, techmap and abc by hand on the 8-bit counter and keeps the statistics after each; the
# grep shows the cell counts. Then synth, the whole default script, on the same counter.
run("""
yosys -q passes.ys
grep -E "cells|[$]" proc.txt opt.txt techmap.txt abc.txt
yosys -q -p "read_verilog -sv counter.sv; synth -top counter; tee -q -o synth.txt stat"
grep -E "cells|[$]" synth.txt
""")

# Yosys 0.69
$ yosys -q passes.ys
$ grep -E "cells|[$]" proc.txt opt.txt techmap.txt abc.txt
proc.txt:        4 cells
proc.txt:        1   $add
proc.txt:        1   $dff
proc.txt:        2   $mux
opt.txt:        2 cells
opt.txt:        1   $add
opt.txt:        1   $sdffe
techmap.txt:      101 cells
techmap.txt:       32   $_AND_
techmap.txt:        8   $_MUX_
techmap.txt:        8   $_NOT_
techmap.txt:       20   $_OR_
techmap.txt:        8   $_SDFFE_PP0P_
techmap.txt:       25   $_XOR_
abc.txt:       22 cells
abc.txt:        5   $_AND_
abc.txt:        1   $_NAND_
abc.txt:        1   $_NOT_
abc.txt:        8   $_SDFFE_PP0P_
abc.txt:        1   $_XNOR_
abc.txt:        6   $_XOR_
$ yosys -q -p "read_verilog -sv counter.sv; synth -top counter; tee -q -o synth.txt stat"
$ grep -E "cells|[$]" synth.txt
       22 cells
        5   $_AND_
        1   $_NAND_
        1   $_NOT_
        8   $_SDFFE_PP0P_
        1   $_XNOR_
        6   $_XOR_

Read the four reports in order. After proc the counter is 4 cells. After opt it is 2: the two multiplexers went into the flip-flop, now a $sdffe, a flip-flop with a synchronous reset and an enable. techmap turned those 2 cells into 101, and abc brought them down to 22, of which 8 are the flip-flops, as $_SDFFE_PP0P_. Yosys’s cell manual spells that name out: a rising clock edge, an active-high reset that loads 0, and an active-high enable. synth ended at the same 22 cells as the script by hand.

A report like this is a check on the RTL. Eight flip-flops for an 8-bit counter is right; a $_DLATCH_ cell, Yosys’s latch, in a design that should have none is a bug; and a module whose report lists no cells at all has lost its logic.

The same RTL can go to three kinds of target, and each is a line of the script:

• Generic gates: synth alone maps to Yosys’s own gates, a netlist for simulation and quick comparisons.
• FPGA cells: synth_ice40 maps to an iCE40’s look-up tables, carry cells and flip-flops.
• Standard cells: dfflibmap and abc read a Liberty fileLiberty file: A text file, in the Liberty format, that describes the cells of a standard-cell library: each cell's function, pins, area, timing and power, at one corner of voltage and temperature. and map to the standard cellsstandard cell: A gate, flip-flop or other small circuit drawn once by a library's makers to a fixed height, so that place and route can line cells up in rows. A chip's logic is built from thousands or millions of them. of a real chip library.

One counter on three targets, with the area each one costs Pro: opens with a Pro, Premium or Ultimate pass

Synthesis messages that point to RTL bugs, reproduced Pro: opens with a Pro, Premium or Ultimate pass

Practise: summarise a stat report

The exercise turns a stat report into the numbers this lesson reads from one: cells, flip-flops, latches and the rest. Its sample tests are the counter’s reports from the passes above:

def summary(report):
    """Cells, flip-flops, latches and other cells of one module's stat report."""
    return {"cells": 0, "flip_flops": 0, "latches": 0, "other": 0}

from stat_summary import summary

PROC = """=== counter ===

        6 wires
       28 wire bits
        4 cells
        1   $add
        1   $dff
        2   $mux
"""

ABC = """=== counter ===
        4 ports
       11 port bits
       22 cells
        5   $_AND_
        1   $_NAND_
        1   $_NOT_
        8   $_SDFFE_PP0P_
        1   $_XNOR_
        6   $_XOR_
"""


def test_after_proc():
    """counts the counter's report after proc: one flip-flop cell and three others"""
    assert summary(PROC) == {"cells": 4, "flip_flops": 1, "latches": 0, "other": 3}


def test_after_abc():
    """counts the eight $_SDFFE_PP0P_ cells as flip-flops"""
    assert summary(ABC) == {"cells": 22, "flip_flops": 8, "latches": 0, "other": 14}


def test_latches():
    """counts $_DLATCH_ cells as latches, not flip-flops"""
    report = "        5 cells\n        2   $_DLATCH_P_\n        3   $_AND_\n"
    assert summary(report) == {"cells": 5, "flip_flops": 0, "latches": 2, "other": 3}


def test_no_cells():
    """gives zeros for a module whose report has wires and ports but no cells"""
    report = "=== mac ===\n        6 wires\n        5 ports\n"
    assert summary(report) == {"cells": 0, "flip_flops": 0, "latches": 0, "other": 0}


def test_total_must_match():
    """refuses a report whose cell lines do not add up to its total"""
    try:
        summary("        3 cells\n        1   $add\n")
    except ValueError:
        return
    raise AssertionError("no ValueError for a total of 3 with 1 cell listed")

Then test yourself on the passes and the statistics. The questions start where your answers have been weakest so far:

Interview questions

What does Yosys’s proc pass do?

It turns processes, the always blocks of the RTL, into cells. Each clocked block becomes flip-flop cells such as $dff, with multiplexers for its if and case branches, and each combinational block becomes multiplexers and logic; a variable that some path leaves unassigned becomes a latch. In this lesson’s counter, proc made 4 cells: a $dff, two $mux and an $add. Later passes then merge and map those cells.

Three harder questions follow, on a design that synthesised to nothing, an area over budget and comparing FPGA and chip results:

Key takeaways

• Yosys synthesises with a script of passes over RTLIL: proc turns always blocks into cells, opt merges and removes cells, techmap maps them to gates and abc rewrites the gates.
• Reading stat after each pass shows what it did: the counter went from 4 cells to 2, then 101, then 22.
• The cell statistics are a check on the RTL: the flip-flops you expect, no latch cells you did not want, and no module with no cells at all.