Introduction

Welcome to the troubleshooting guide for open-source EDA (Electronic Design Automation) tools. If you've been working with Yosys, Icarus Verilog, Verilator, or OpenSTA, you've probably encountered cryptic error messages or unexpected behavior. Don't worry—you're not alone! This guide will help you understand common problems, develop systematic debugging approaches, and avoid the pitfalls that catch even experienced designers.

Think of this guide as your debugging companion. We'll explore real error messages you're likely to encounter, explain what they actually mean (not just what they say), and provide practical solutions. By the end, you'll have a toolkit of strategies to tackle problems methodically rather than through trial and error.

Understanding Your Toolchain

Before diving into specific errors, let's clarify what each tool does:

  • Icarus Verilog (iverilog): A simulator that executes your RTL code to verify functional correctness
  • Verilator: A fast simulator that converts Verilog to C++ for high-performance verification
  • Yosys: A synthesis tool that transforms RTL into gate-level netlists
  • OpenSTA: A static timing analyzer that verifies your design meets timing requirements

Each tool has different strengths, limitations, and quirks. Knowing which tool is generating an error immediately narrows down the problem space.

Common Icarus Verilog Issues

Undeclared Signals and Implicit Nets

Error Message:

error: Unable to bind wire/reg/memory 'signal_name' in 'module_name'

What It Means: You're using a signal that hasn't been declared. Unlike some commercial simulators, Icarus Verilog won't automatically create implicit nets in all contexts.

Solution: Declare all signals explicitly at the beginning of your module:

module counter(
    input wire clk,
    input wire reset,
    output reg [7:0] count
);
    wire rollover;  // Explicitly declare intermediate signals
    
    assign rollover = (count == 8'd255);
    // rest of code...
endmodule

Pro Tip: Use the -Wall flag when compiling to catch implicit wire declarations: iverilog -Wall -o sim design.v testbench.v

Syntax Errors with SystemVerilog Features

Error Message:

syntax error

What It Means: You're using SystemVerilog syntax, but Icarus is defaulting to Verilog-2001 mode, or you're using a construct that isn't yet supported.

Solution: Specify the language standard explicitly:

  • For SystemVerilog: iverilog -g2012 design.sv
  • For Verilog-2005: iverilog -g2005 design.v

Common Gotcha: Even with -g2012, Icarus Verilog doesn't support all SystemVerilog features. Always-comb and always-ff blocks work, but interfaces and classes have limited or no support. Check the documentation or test incrementally.

Time Scale Mismatches

Warning Message:

warning: Some designs have no timescale declared

What It Means: Different modules have different or missing timescale directives, which can cause simulation timing issues.

Solution: Add a consistent timescale directive at the top of each file:

`timescale 1ns/1ps  // time_unit / time_precision

module my_design(...);
    // design code
endmodule

Verilator: Speed with Constraints

Verilator is exceptionally fast but more restrictive than Icarus Verilog. Understanding its limitations will save you hours of frustration.

Unsupported Constructs

Error Message (example: an expect statement):

%Error-UNSUPPORTED: expect_stmt.sv:4:3: Unsupported: expect

What It Means: Verilator does not implement every SystemVerilog construct. It reports the ones it lacks with the UNSUPPORTED code and names the construct, so the message tells you exactly what to change.

What Verilator 5 Does Support: Since version 5.0, Verilator simulates delays (#10), fork/join, user-defined primitives and real variables. All of them ran in a test with Verilator 5.052, the version in ChipVerify Lab. Guides that list them as unsupported describe Verilator 4.

Solution: Rewrite the reported construct (an expect can become an assertion, or a wait followed by a check), or run that testbench in another simulator such as Icarus Verilog.

Delays in Clocked Logic

Verilator 5 accepts and simulates a delay inside a clocked block, but synthesis ignores it, so the simulated design and the hardware no longer match:

// Bad - simulates, but synthesis drops the #5
always @(posedge clk) begin
    #5 data <= new_data;
end

// Good - use proper clocking
always @(posedge clk) begin
    data <= new_data;  // Happens on clock edge
end

Solution: Keep delays out of design code and leave timing to the clock and to static timing analysis.

Unoptimizable Constructs Warning

Warning Message:

%Warning-UNOPTFLAT: design.v:1:37: Signal unoptimizable: Circular combinational logic: 'y'

What It Means: Verilator detected combinational logic with feedback, which it can't optimize efficiently. It names one signal on the loop: with the loop below driving an output (assign y = a;), it named y. Trace back from that signal to find the rest. A loop that drives nothing is removed as dead logic and gives no warning at all. This often indicates a real design problem.

Solution: Review your combinational logic for unintended latches or circular dependencies. Use sequential logic (registers) to break feedback loops intentionally:

// Problematic combinational loop
assign a = b & c;
assign b = a | d;  // Circular!

// Fixed with registered logic
always @(posedge clk) begin
    a <= b & c;
    b <= a | d;
end

Yosys Synthesis Challenges

Inferring Memory vs. Registers

Warning Message:

Mapping memory \mem in module \top:
  created 16 $dff cells and 0 static cells of width 8.

What It Means: Yosys found no RAM cell to map the array to, so its memory_map pass built it from flip-flops and multiplexers: 16 words of 8 bits became 128 flip-flops. This is what always happens in an ASIC flow with only a standard-cell library, because Yosys has no SRAM macros to use. It is fine for small register files and very costly for large memories.

Solution: For a large ASIC memory, instantiate an SRAM macro from a memory compiler (for SkyWater 130, OpenRAM generates them). On an FPGA target (synth_ice40, synth_xilinx and others) the same RTL can map to block RAM if it follows the pattern the target supports, such as a synchronous read:

// Synchronous read: the pattern FPGA block RAMs need
reg [7:0] memory [0:255];

always @(posedge clk) begin
    if (write_enable)
        memory[write_addr] <= write_data;
    read_data <= memory[read_addr];
end

Gotcha: Read and write in the same always block with separate ports. Mixed read-write on the same address may prevent memory inference depending on your target FPGA.

Latch Inference Problems

Warning Message:

Warning: Latch inferred for signal 'data_out'

What It Means: Your combinational always block doesn't assign a value to the output in all code paths, creating an unintended latch.

Solution: Always assign values to all outputs in all branches:

// Bad - creates a latch
always @(*) begin
    if (select)
        data_out = data_in;
    // What happens when select is 0? LATCH!
end

// Good - no latch
always @(*) begin
    if (select)
        data_out = data_in;
    else
        data_out = 8'd0;  // Default assignment
end

Pro Tip: Initialize signals at the beginning of always @(*) blocks to provide default values, then override them conditionally.

Synthesis Attribute Issues

Symptom: A signal you wanted to keep, for debug or for a later step, is missing from the netlist.

What It Means: Yosys removes logic that drives nothing. It does honour (* keep *): in a test with Yosys 0.63, a wire marked (* keep *) survived synth. Attributes Yosys does not know, such as (* ram_style = "block" *) from FPGA vendor tools, are stored but have no effect, and Yosys prints no warning about them.

Solution: Use attributes Yosys documents:

(* keep *) wire important_signal;
(* fsm_encoding = "one-hot" *) reg [2:0] state;

Check Yosys documentation for supported attributes. Some Xilinx or Intel-specific attributes won't work.

OpenSTA Timing Analysis Traps

Missing or Incorrect SDC Constraints

Output without a clock:

No paths found.
worst slack max INF

What It Means: OpenSTA prints no warning. Without a clock there is nothing to check, so report_checks finds no paths and the worst slack is infinite. A clean-looking report can therefore mean that nothing was analysed.

Solution: Create a proper SDC (Synopsys Design Constraints) file:

# Define clocks
create_clock -name clk -period 10.0 [get_ports clk]

# Define input/output delays
set_input_delay -clock clk 2.0 [all_inputs]
set_output_delay -clock clk 2.0 [all_outputs]

# Define clock uncertainty (jitter, skew)
set_clock_uncertainty 0.5 [get_clocks clk]

Path Grouping Confusion

Issue: Timing reports show unexpected critical paths or miss important violations.

What's Happening: Without proper path grouping, OpenSTA might not report the paths you care about.

Solution: Use path groups to organize timing analysis:

group_path -name input_to_reg -from [all_inputs] -to [all_registers]
group_path -name reg_to_reg -from [all_registers] -to [all_registers]
group_path -name reg_to_output -from [all_registers] -to [all_outputs]

False Paths and Multicycle Paths

Problem: OpenSTA reports timing violations on paths that don't need to meet single-cycle timing.

Solution: Use false_path and multicycle_path constraints:

# Asynchronous reset path - doesn't need timing analysis
set_false_path -from [get_ports reset]

# This path has two cycles to complete
set_multicycle_path 2 -from [get_pins reg_a/*] -to [get_pins reg_b/*]

General Debugging Strategies

The Incremental Approach

When facing complex errors, simplify aggressively:

  1. Create a minimal failing example: Strip your design down to the smallest piece that shows the problem
  2. Add complexity gradually: Once the simple version works, add features back one at a time
  3. Test at each step: Don't wait until everything is implemented to test

Systematic Error Interpretation

When you see an error message:

  1. Read the entire message: Don't just skim the first line
  2. Note the file and line number: Go directly to the problematic code
  3. Check the context: Look at surrounding code, not just the reported line
  4. Search for the exact error: Many errors have been solved by others—use search engines!

Comparing Tool Outputs

Run your design through multiple tools when possible:

  • If Icarus Verilog simulates correctly but Verilator fails, you might be using unsupported constructs
  • If Yosys synthesis succeeds but OpenSTA shows timing violations, your constraints might be too aggressive
  • If simulation works but synthesis creates unexpected logic, review your coding style for synthesis-unfriendly patterns

Using Waveform Viewers

Visual debugging is powerful. Generate VCD (Value Change Dump) files:

// In your testbench
initial begin
    $dumpfile("wave.vcd");
    $dumpvars(0, testbench);
end

View with GTKWave to see signal behavior over time. Often, watching signals transition makes bugs obvious.

Enabling Verbose Output

Most tools have verbose modes that provide additional debugging information:

  • Icarus Verilog: Use -v flag
  • Yosys: Use debug command or -v flag
  • Verilator: Use --debug flag

Tool-Specific Configuration Tips

Icarus Verilog Configuration

Create a .verilog file in your home directory to set default options:

-g2012
-Wall

Yosys Optimization Control

Sometimes Yosys optimizes too aggressively. Control optimization:

# In your synthesis script
read_verilog design.v
hierarchy -check
# Reduce optimization for debugging
opt -fast

Verilator Lint Mode

Use Verilator's lint mode to catch potential issues without full compilation:

verilator --lint-only design.v

This is faster than full compilation and catches many common problems.

Conclusion

Debugging open-source EDA tools requires patience and systematic thinking, but it's a learnable skill. Remember these key principles:

  • Understand each tool's purpose and limitations before blaming the tool for errors
  • Read error messages completely and search for solutions—you're rarely the first person to encounter a particular error
  • Simplify and isolate problems to their smallest reproducible form
  • Test incrementally rather than building everything before testing
  • Use multiple tools to cross-validate your design and identify tool-specific issues

With experience, you'll develop intuition for which tool is likely causing which problem, and debugging will become much faster. The open-source community is also incredibly helpful—don't hesitate to ask questions on forums or GitHub issues when you're truly stuck.

Happy debugging, and remember: every error message is an opportunity to learn something new about your tools and your design!

Did you find what you were looking for?

Quiz

Test Your Knowledge

1 of 5 Score: 0 / 5