Yosys

Verilog to a bitstream, with the open-source flow

Six tools, one command, and a strict subset of one language. Everything below is what actually passes through Icarus Verilog, Yosys, nextpnr and icepack — not what the standard permits.

The flow

"$YOSYS_FLOW" blink            # the whole thing, for top module `blink`

Each step's full output is at out/logs/<step>.log, with <step>.start, <step>.time and <step>.exit beside it and out/logs/run.json for the run as a whole — the pane reads those to show which step is running. The flow does not stop the world on a failure: synthesis still runs when simulation fails, so you see every problem at once.

Single steps, when you are iterating on one thing — through "$YOSYS_TOOLCHAIN/run", which finds the tools the way the flow does (they need not be on your PATH):

# just the simulation
"$YOSYS_TOOLCHAIN/run" iverilog -g2012 -o out/sim.vvp rtl/*.v tb/blink_tb.v && "$YOSYS_TOOLCHAIN/run" vvp out/sim.vvp
# just the cell count
"$YOSYS_TOOLCHAIN/run" yosys -p "read_verilog rtl/*.v; synth_ice40 -top blink; stat"

Then always finish with the full "$YOSYS_FLOW" <top> so the pane and the verdict are current.

The synthesisable subset

Yosys turns a description of hardware into gates. Anything that does not describe hardware is either rejected or, worse, quietly turned into something you did not mean.

Always

`default_nettype none        // first line of every file: an undeclared name is now an error,
                             // not a silent 1-bit wire. This catches every typo'd port.

module counter #(
    parameter integer WIDTH = 8          // parameters, not `define — they are per-instance
) (
    input  wire              clk,
    input  wire              rst,
    input  wire              en,
    output reg  [WIDTH-1:0]  count       // a port assigned in an always block is `reg`
);

    always @(posedge clk) begin          // ONE clock, ONE edge, no other signal in the list
        if (rst)      count <= {WIDTH{1'b0}};
        else if (en)  count <= count + 1'b1;
    end

endmodule

`default_nettype wire        // last line: put it back, so other files are not surprised

Rules that are not negotiable:

• <= in always @(posedge clk), = in always @(*). Non-blocking for flip-flops, blocking for combinational logic. Mixing them is the single most common source of "it simulates but does not synthesise the same".
• A signal is driven from exactly one always block (or one assign), never two. Two drivers is an error in synthesis and an x in simulation.
• Every always @(*) assigns every output on every path. An if without an else, or a case without a default, infers a latch — see the pitfalls below.
• Sized literals everywhere: 8'd0, 4'b1010, 16'hBEEF, {WIDTH{1'b0}}. A bare 0 is 32 bits and will silently widen an expression.
• $clog2(N) for a counter's width. It is Verilog-2005 and Yosys supports it.
• No initial blocks for logic (initial values on a reg are fine and do synthesise on iCE40 — the bitstream sets the flip-flops). No #delays. No fork/join. No while/forever. No real. for loops only with constant bounds — they unroll into copies of hardware.
• Multiplication by a constant power of two is a shift and is free; * by a variable costs a lot of LUTs (the UP5K has 8 DSP blocks, synth_ice40 -dsp maps to them). Division is not free and usually means you want a different algorithm.

State machines — two blocks, always:

localparam [1:0] IDLE = 2'd0, RUN = 2'd1, DONE = 2'd2;
reg [1:0] state, next;

always @(posedge clk)                    // the register
    if (rst) state <= IDLE; else state <= next;

always @(*) begin                        // the transition, fully assigned
    next = state;                        // <-- the default that prevents a latch
    case (state)
        IDLE: if (start) next = RUN;
        RUN:  if (done)  next = DONE;
        DONE:            next = IDLE;
        default:         next = IDLE;
    endcase
end

The testbench

One per top module, at tb/<top>_tb.v. The shape matters: the pane draws its waves from the VCD, and the verdict reads the word FAIL.

`timescale 1ns / 1ps
`default_nettype none

module counter_tb;
    reg clk = 1'b0, rst = 1'b1, en = 1'b0;
    wire [7:0] count;
    integer errors = 0;

    counter #(.WIDTH(8)) dut (.clk(clk), .rst(rst), .en(en), .count(count));

    always #5 clk = ~clk;                       // a 100 MHz clock: 10 ns period

    task check(input condition, input [8*40-1:0] what);   // NOT `expect` — reserved in -g2012
        begin
            if (condition) $display("  ok   %0s", what);
            else begin errors = errors + 1; $display("  FAIL %0s (at %0t)", what, $time); end
        end
    endtask

    initial begin
        $dumpfile("out/sim.vcd");               // exactly this path — the flow reads it
        $dumpvars(0, counter_tb);               // 0 = this scope and everything under it

        repeat (2) @(posedge clk); rst = 1'b0; en = 1'b1;
        repeat (5) @(posedge clk); #1;
        check(count == 8'd5, "counts five clocks");

        if (errors == 0) $display("PASS  counter: %0d checks", 3);
        else             $display("FAIL  counter: %0d check(s) failed", errors);
        $finish;                                 // ALWAYS: without it vvp runs forever
    end
endmodule

• #1 after @(posedge clk) before checking. At the edge itself the non-blocking update has not landed yet; one time unit later it has.
• Simulate in shrunken time. A 1 Hz blink off a 12 MHz clock is 12 million cycles. Parameterise the design (CLK_HZ) and override it in the testbench (.CLK_HZ(16)), so the same RTL runs in a hundred clocks. Never change the RTL to make the test fast.
• $dumpvars(0, tb) dumps everything including the DUT's internals — that is what you want: the pane's Waves tab browses every scope, shows parameters with their values, and opens on the DUT's ports and registers. A line named tx/rx is decoded as UART (baud measured off the line); an 8-bit bus named data/byte/char starts in ASCII. Keep a dump under a few tens of millions of changes — $dumpoff around a long quiet stretch, as hello_uart-style testbenches do.
• The word FAIL anywhere in the output fails the verdict. Do not print it in passing messages.

The board: iCEBreaker, iCE40UP5K-SG48

5280 logic cells, 30 × 4 kbit block RAMs, 4 × 16 kB single-port RAMs, 8 DSP blocks, 1 PLL. Pin numbers are the board's, from the iCEBreaker project's own constraints file.

set_io -nowarn clk   35     # 12 MHz oscillator
set_frequency clk 12        # nextpnr's extension: this is what Fmax is measured against
set_io -nowarn btn_n 10     # on-board button   — ACTIVE LOW (0 = pressed)
set_io -nowarn ledr_n 11    # red LED           — ACTIVE LOW (0 = lit)
set_io -nowarn ledg_n 37    # green LED         — ACTIVE LOW (0 = lit)
set_io -nowarn rx     6     # UART from the on-board FTDI (FPGA's point of view)
set_io -nowarn tx     9     # UART to the FTDI

The full board — RGB LED (39/40/41), SPI flash, PMOD 1A/1B/2, and the snap-off section's five active-high LEDs and three buttons — is commented out in constraints/blink.pcf; uncomment what you use. -nowarn lets one PCF carry pins the current design does not have.

Every port of the top module needs a set_io line, or nextpnr fails with "unconstrained IO". Nothing else in the design does; internal signals are routed automatically.

Another board: change constraints/<top>.pcf and set YOSYS_DEVICE / YOSYS_PACKAGE (e.g. YOSYS_DEVICE=--hx8k YOSYS_PACKAGE=ct256 for the HX8K breakout).