Verilog Design Flow

Design, implement, and verify Verilog/SystemVerilog modules with spec-driven development, self-checking testbenches, and automated simulation workflows. Supp...

Security Scan

The skill's files, instructions, and runtime actions are coherent with a Verilog/SystemVerilog simulation and verification workflow and do not request unrelated credentials or hidden endpoints.

Purpose & Capability

Name/description (Verilog design, testbench, simulation, VCD analysis) align with what is included: SKILL.md guidance, a simulation wrapper (simulate.sh), and a VCD-checker (check_vcd.py). No unrelated environment variables, config paths, or obscure binaries are requested.

Instruction Scope

Runtime instructions stay within the stated domain: coding style, static check with slang, running a simulator (VCS/Xrun/iverilog), generating VCDs, and analyzing VCDs with the included Python script. The only external execution steps are expected (running simulators and python3). The SKILL.md references calling the bundled check_vcd.py from a post-simulation $system call — this is consistent with automated verification but means the testbench can invoke host commands, so run only trusted testbenches.

Install Mechanism

This is instruction-only with no install spec. That's low-risk, but the reference docs and script require the Python package 'vcdvcd' (pip) and external EDA simulators (VCS/Xrun/iverilog). Those dependencies are not installed automatically by the skill; the user must provide them. No downloads from external URLs or archive extraction are present.

Credentials

No required env vars, no credentials, and no config paths are requested. Scripts use locally available commands (vcs/xrun/iverilog/python3) and local files only. This is proportionate to a simulation workflow.

Persistence & Privilege

The skill does not request persistent or platform-wide privileges; always:false and no self-enablement steps are present. It does not modify other skills or system-wide agent settings.

Assessment

This skill appears coherent for Verilog simulation and VCD analysis, but take these precautions before running it: (1) Inspect testbench and RTL files you run — simulators and Verilog $system calls can execute host commands. The references show an example using $system("python3 check_vcd.py ...") which will run whatever Python is on the host. (2) Install runtime dependencies yourself (e.g., pip install vcdvcd in a virtualenv) and verify you have a trusted simulator. (3) Run simulations in a restricted/sandboxed environment if you’re running untrusted code. (4) The skill doesn’t auto-install packages or fetch remote code; if you see any attempt to download/execute from unknown URLs, treat that as suspicious.

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

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

`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:

# 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

Tool	Command	Purpose
Synopsys VCS	vcs -full64 -debug_acc+all -l sim.log -R file.v	Compile & Simulate Verilog
Synopsys VCS (SV)	vcs -full64 -debug_acc+all -sverilog -l sim.log -R file.sv	Compile & Simulate SystemVerilog
Cadence Xrun	xrun -64bit -access rwc -l sim.log file.v	Compile & Simulate Verilog
Cadence Xrun (SV)	xrun -64bit -access rwc -sv -l sim.log -R file.sv	Compile & Simulate SystemVerilog
Icarus Verilog	iverilog -o out.vvp file.v	Compile Verilog (fallback)
VVP	vvp out.vvp	Run simulation
GTKWave	gtkwave dump.vcd	View waveforms (optional)

Common Pitfalls

Issue	Fix
Multiple drivers	Ensure one-always-one-signal: each signal assigned in exactly one always block
Latch inference	Ensure all if/case branches assign in combinational always
Missing reset	Include explicit reset in sequential always blocks
Race conditions	Use non-blocking <= in sequential logic only
Simulation mismatch	Check timescale and delays
VCD not generated	Ensure $dumpfile() called before $dumpvars()

Debugging Guide

Simulation Hangs / Freezes

Symptom	Cause	Solution
No output, simulation stuck	Combinational loop	Check for circular logic in combinational always blocks
Infinite loop warning	Zero-delay feedback	Add delay elements or check async feedback paths
Division by zero	Runtime calculation error	Check divisor is never zero
Array out of bounds	Invalid index	Verify index range before array access

Output Shows 'X' (Unknown)

Symptom	Cause	Solution
Specific signal is X	Uninitialized register	Add explicit reset value
Wide bus partially X	Mixed width assignment	Check vector width consistency
After reset release	Reset deassertion timing	Ensure reset held long enough
Random X propagation	X propagation from input	Trace back to source of X

Timing Issues

Symptom	Cause	Solution
Output one cycle late	Blocking vs non-blocking	Use <= in sequential always blocks
Glitches on output	Combinational logic hazard	Add register stage or use synchronous output
Setup/hold violations (ASIC)	Clock/data skew	Check synthesis timing reports

Synthesis Errors

Error	Cause	Solution
"Not synthesizable"	Unsupported Verilog construct	Replace with synthesizable equivalent
"Multiple drivers"	Signal assigned in multiple always	Merge logic or use intermediate signals
"Latch inferred"	Incomplete if/case in combinational	Add default assignment or use else
"Undriven signal"	Output declared but not assigned	Connect to logic or tie to constant

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