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:

bash

# 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 <module_name>_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

bash

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

Synopsys VCS (Verilog)

bash

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

Synopsys VCS (SystemVerilog)

bash

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

Cadence Xrun (Verilog)

bash

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

Cadence Xrun (SystemVerilog)

bash

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

Icarus Verilog (Fallback)

bash

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:

verilog

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 <skill_dir>/scripts/check_vcd.py <module>.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#

verilog

`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/<module_name>_spec.md
• Verilog files: Create in workspace as <module_name>.v
• Testbenches: Create as <module_name>_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:

bash

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

Example workflow:

bash

# 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#

ToolCommandPurposeSynopsys VCSvcs -full64 -debug_acc+all -l sim.log -R file.vCompile & Simulate VerilogSynopsys VCS (SV)vcs -full64 -debug_acc+all -sverilog -l sim.log -R file.svCompile & Simulate SystemVerilogCadence Xrunxrun -64bit -access rwc -l sim.log file.vCompile & Simulate VerilogCadence Xrun (SV)xrun -64bit -access rwc -sv -l sim.log -R file.svCompile & Simulate SystemVerilogIcarus Verilogiverilog -o out.vvp file.vCompile Verilog (fallback)VVPvvp out.vvpRun simulationGTKWavegtkwave dump.vcdView waveforms (optional)

Common Pitfalls#

IssueFixMultiple driversEnsure one-always-one-signal: each signal assigned in exactly one always blockLatch inferenceEnsure all if/ case branches assign in combinational alwaysMissing resetInclude explicit reset in sequential always blocksRace conditionsUse non-blocking <= in sequential logic onlySimulation mismatchCheck timescale and delaysVCD not generatedEnsure $dumpfile() called before $dumpvars()

Debugging Guide#

Simulation Hangs / Freezes#

SymptomCauseSolutionNo output, simulation stuckCombinational loopCheck for circular logic in combinational always blocksInfinite loop warningZero-delay feedbackAdd delay elements or check async feedback pathsDivision by zeroRuntime calculation errorCheck divisor is never zeroArray out of boundsInvalid indexVerify index range before array access

Output Shows 'X' (Unknown)#

SymptomCauseSolutionSpecific signal is XUninitialized registerAdd explicit reset valueWide bus partially XMixed width assignmentCheck vector width consistencyAfter reset releaseReset deassertion timingEnsure reset held long enoughRandom X propagationX propagation from inputTrace back to source of X

Timing Issues#

SymptomCauseSolutionOutput one cycle lateBlocking vs non-blockingUse <= in sequential always blocksGlitches on outputCombinational logic hazardAdd register stage or use synchronous outputSetup/hold violations (ASIC)Clock/data skewCheck synthesis timing reports

Synthesis Errors#

ErrorCauseSolution"Not synthesizable"Unsupported Verilog constructReplace with synthesizable equivalent"Multiple drivers"Signal assigned in multiple alwaysMerge logic or use intermediate signals"Latch inferred"Incomplete if/case in combinationalAdd default assignment or use else"Undriven signal"Output declared but not assignedConnect to logic or tie to constant

Version Tracking#

File Header Template#

Every Verilog file should include:

verilog

/**
 * 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)#

bash

# 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