Verilog Design Flow

Core Rules

Phase 1: Understand Requirements

1. Ask clarifying questions if the design spec is incomplete
2. Identify: clock/reset strategy, interface signals, functionality, timing constraints
3. Confirm the target: synthesis (FPGA/ASIC) or simulation only

Phase 2: Write Design Spec

1. Create a markdown spec document with:
• Module name and purpose
• Port list (direction, width, description)
• Functional description
• Timing diagram (if applicable)
• Test scenarios checklist
2. Store spec in memory or as a file for reference

Phase 3: Implement Verilog

1. One-always-one-signal coding style: Each signal should be assigned in exactly one always block
• Separate sequential (posedge clk) and combinational (@*) logic
• Declare intermediate signals for complex logic
• Avoid mixing blocking (=) and non-blocking (<=) assignments in the same always block
2. Follow synthesizable coding guidelines:
• Use always @(posedge clk) for sequential logic
• Use assign or always @(*) for combinational logic
• Avoid latches (ensure all branches assign in combinational blocks)
• Explicit reset strategy (sync/async)
3. Include header comments with author, date, and revision (see Version Tracking below)
4. Use descriptive signal names, avoid single-letter variables

Phase 3b: Static Syntax Check with Slang

Before simulation, run static syntax checking using slang:

# Check Verilog/SystemVerilog syntax
slang <module_name>.v

# Or for SystemVerilog files
slang <module_name>.sv

What slang checks:

• Syntax errors and parsing issues
• Type mismatches
• Undefined references
• Port connection errors
• SystemVerilog compliance

If slang reports errors:

1. Fix all syntax errors before proceeding to simulation
2. Pay attention to warnings about potential issues
3. Re-run slang until "Build succeeded: 0 errors"

Phase 3c: Design Review Checklist

Before simulation, verify:

• [ ] Slang syntax check passes (0 errors)
• [ ] All sequential signals have explicit reset values
• [ ] No combinational logic loops (synthesis will error)
• [ ] No unintentional latches (all if/case branches assign in combinational blocks)
• [ ] State machines have default case branch
• [ ] Clock domain crossing signals are properly synchronized
• [ ] Vector widths match between assignment source and destination
• [ ] Array indices are within declared bounds
• [ ] No blocking assignments (=) in sequential always blocks
• [ ] No non-blocking assignments (<=) in combinational always blocks
• [ ] timescale directive present in all source files

Phase 4: Write Testbench

1. Create self-checking testbench using:
• Clock generator (typical: always #5 clk = ~clk; for 10ns period)
• Reset stimulus
• Input stimulus generation
• Expected output generation/comparison
• $display() or $monitor() for pass/fail reporting
• $finish() after all tests complete
2. Save as _tb.v

Phase 5: Simulate with EDA Tools

The skill automatically detects and uses available simulators in priority order:

1. Synopsys VCS (if vcs command available)
2. Cadence Xrun (if xrun command available)
3. Icarus Verilog (fallback)

Simulator Detection Logic

# Priority order: VCS → Xrun → Icarus
which vcs && use_vcs
which xrun && use_xrun
fallback to iverilog

Synopsys VCS (Verilog)

vcs -full64 -debug_acc+all -l sim.log -R <module_name>.v <module_name>_tb.v

Synopsys VCS (SystemVerilog)

vcs -full64 -debug_acc+all -sverilog -l sim.log -R <module_name>.sv <module_name>_tb.sv

Cadence Xrun (Verilog)

xrun -64bit -access rwc -l sim.log <module_name>.v <module_name>_tb.v

Cadence Xrun (SystemVerilog)

xrun -64bit -access rwc -sv -l sim.log -R <module_name>.sv <module_name>_tb.sv

Icarus Verilog (Fallback)

iverilog -o <module_name>.vvp <module_name>.v <module_name>_tb.v
vvp <module_name>.vvp

VCD Waveform Output

⚠️ Important: Always use VCD format for waveform dumping to ensure compatibility:

initial begin
    $dumpfile("<module_name>.vcd");
    $dumpvars(0, <module_name>_tb);
end

• VCS and Xrun support VCD via $dumpfile()/$dumpvars()
• FSDB format (for Verdi) is NOT supported by the VCD analysis scripts
• Keep testbench VCD-compatible for cross-simulator portability

Phase 6: Debug & Iterate

1. If assertions fail or outputs incorrect:
• Review waveforms with gtkwave OR
• Use Python VCD analysis script: python3 /scripts/check_vcd.py .vcd
• See references/vcd-analysis.md for detailed API
2. Fix RTL bugs, update testbench if needed
3. Re-simulate until all tests pass
4. Update spec with any design changes

Testbench Template

`timescale 1ns/1ps

module <module>_tb;
    // Parameters
    parameter CLK_PERIOD = 10;
    
    // Signals
    reg clk;
    reg rst_n;
    // ... add inputs/outputs
    
    // Instantiate DUT
    <module> dut (
        .clk(clk),
        .rst_n(rst_n),
        // ... ports
    );
    
    // Clock generation
    initial begin
        clk = 0;
        forever #(CLK_PERIOD/2) clk = ~clk;
    end
    
    // VCD dump
    initial begin
        $dumpfile("<module>.vcd");
        $dumpvars(0, <module>_tb);
    end
    
    // Test stimulus
    initial begin
        // Initialize
        rst_n = 0;
        // ... init inputs
        
        // Release reset
        #(CLK_PERIOD * 2);
        rst_n = 1;
        
        // Apply test vectors
        // ... stimulus code
        
        // Check results
        // ... self-checking assertions
        
        #(CLK_PERIOD * 10);
        $finish();
    end
    
    // Monitor
    initial begin
        $monitor("Time=%0t: signals=...", $time);
    end
endmodule

VCD Analysis

For automated waveform checking, use Python VCD parsing.

Reference: references/vcd-analysis.md

Data Storage

• Design specs: Store in memory/verilog_specs/_spec.md
• Verilog files: Create in workspace as .v
• Testbenches: Create as _tb.v
• Simulation outputs: Generate .vvp (Icarus), sim.log, and .vcd files

Simulator Auto-Detection Script

Use the provided helper script to automatically select and run the best available simulator:

# The script checks for VCS → Xrun → Icarus in order
bash <skill_dir>/scripts/simulate.sh <module_name>

Example workflow:

# 1. Detect simulator and run
bash scripts/simulate.sh counter

# 2. Check simulation log
cat sim.log

# 3. Analyze VCD waveforms
python3 scripts/check_vcd.py counter.vcd

External Tools

Common Pitfalls

Debugging Guide

Simulation Hangs / Freezes

Output Shows 'X' (Unknown)

Timing Issues

Synthesis Errors

Version Tracking

File Header Template

Every Verilog file should include:

/**
 * Module: <module_name>
 * Description: <brief description>
 * Author: <name>
 * Date: <YYYY-MM-DD>
 * Version: <major>.<minor>.<patch>
 * 
 * Changelog:
 *   v1.0.0 - <date> - Initial release
 *   v1.1.0 - <date> - <description of changes>
 *   v2.0.0 - <date> - <breaking changes>
 * 
 * Parameters:
 *   - PARAM1: <description> (default: <value>)
 *   - PARAM2: <description> (default: <value>)
 * 
 * Ports:
 *   - clk: <description>
 *   - rst_n: <description>
 *   ...
 */

Version Numbering

• Major: Breaking changes (interface change, removed features)
• Minor: New features, backward compatible
• Patch: Bug fixes, no functional change

Git Workflow (Recommended)

# Before starting new feature
git checkout -b feature/new-functionality

# After completing and testing
git add <files>
git commit -m "feat: add <feature> to <module>"
git checkout main
git merge feature/new-functionality