Skip to content

bjwanneng/veriflow-cc / src/claude_skills/vf-rtl

vf-rtl

Verified

FileKindSize
SELF_IMPROVE.mdmarkdown3.8 KB
SKILL.mdskill md11.2 KB
SKILL_INDEX.mdmarkdown5.5 KB
analysis/bug_pattern_match.pyscript26.9 KB
analysis/corner_case_generator.pyscript4.9 KB
analysis/coverage_analyzer.pyscript5.3 KB
analysis/design_graph.pyscript8.9 KB
analysis/expected_trace_gen.pyscript12.5 KB
analysis/timing_contract_checker.pyscript25.4 KB
analysis/timing_diagnostic.pyscript21.1 KB
analysis/vcd2table.pyscript31.3 KB
bug_patterns.mdmarkdown23.2 KB
coding_style.mdmarkdown9.4 KB
core/init.pyscript13.8 KB
core/rtl_utils.pyscript7.5 KB
core/state.pyscript38.9 KB
design_rules.mdmarkdown2.9 KB
error_recovery.mdmarkdown7.0 KB
kb/knowledge_base.pyscript11.7 KB
kb/reference_kb.pyscript5.6 KB
kb/self_improve.pyscript24.4 KB
references/arbiter_round_robin.vother1.4 KB
references/counter.vother545 B
references/fifo.vother1.3 KB
references/fsm_moore.vother847 B
references/handshake_valid_ready.vother1.1 KB
references/pipeline_aligner.vother760 B
runners/benchmark_runner.pyscript23.6 KB
runners/cocotb_runner.pyscript26.3 KB
runners/iverilog_runner.pyscript26.3 KB
runners/yosys_equiv.pyscript14.2 KB
stage1_spec_golden.mdmarkdown6.1 KB
stage2_codegen.mdmarkdown5.9 KB
stage3_verify_fix.mdmarkdown17.0 KB
stage4_lint_synth.mdmarkdown6.3 KB
templates/cocotb_template.pyscript42.4 KB
templates/golden_model_template.pyscript8.7 KB
templates/spec_template.jsonconfig8.5 KB
templates/tb_integration_template.vother12.4 KB
verify/candidate_selector.pyscript7.0 KB
verify/formal_prove.pyscript12.1 KB
verify/synth_score.pyscript4.4 KB

templates/tb_integration_template.v

View on GitHub
// tb_<design_name>.v — integration test for <design_name>
module tb_<design_name>;
    // Declare wires/regs matching ALL ports of the top module DUT
    reg clk, rst;
    reg [31:0] data_in;
    wire [31:0] data_out;
    wire ready;

    // Cycle counter — used in ALL $display calls for waveform correlation
    integer cycle_count = 0;
    integer fail_count  = 0;

    // Instantiate DUT (top module — submodules are linked via RTL files)
    <design_name> uut (
        .clk(clk), .rst(rst),
        .data_in(data_in), .data_out(data_out), .ready(ready)
    );

    // Clock generation
    initial clk = 0;
    // codegen: replace #5 with HALF-period from spec timing.target_frequency_mhz.
    // half_period_ns = 1000 / (2 * target_frequency_mhz) = CLK_PERIOD_NS / 2.
    // For 100 MHz: full period = 10 ns, half period = 5 ns -> `always #5 clk = ~clk;`.
    always #5 clk = ~clk;

    // Cycle counter — increment every posedge
    always @(posedge clk) cycle_count = cycle_count + 1;

    // VCD capture — REQUIRED for waveform analysis. Suppress with `define NODUMP
    // (the runner passes -DNODUMP when invoked with --no-vcd).
`ifndef NODUMP
    initial begin
        $dumpfile("tb_<design_name>.vcd");
        $dumpvars(0, tb_<design_name>);
    end
`endif

    // ===========================================================================
    // TESTBENCH TIMING METHODOLOGY — Read Before Modifying This Testbench
    // ===========================================================================
    //
    // Rule 1: NBA FOR DUT INPUTS (MANDATORY)
    //   All DUT input assignments in initial blocks MUST use non-blocking
    //   assignment (<=). This prevents race conditions between the testbench
    //   and the DUT's sequential always blocks at the same posedge.
    //
    //   CORRECT:
    //     msg_block <= 512'h...;
    //     msg_valid <= 1'b1;
    //     @(posedge clk);
    //
    //   WRONG (blocking assignment to DUT input — race condition):
    //     msg_block = 512'h...;
    //     msg_valid = 1'b1;
    //     @(posedge clk);
    //
    //   Exception: Reset signal (rst/rst_n) MAY use blocking (=) in the
    //   dedicated reset sequence only. All other DUT inputs: use <= .
    //
    // Rule 2: RESET SEQUENCE TIMING
    //   Standard pattern:
    //     rst = 1;                          // blocking OK for reset only
    //     <zero all data inputs with <=>
    //     @(posedge clk); @(posedge clk);   // hold reset 2 cycles
    //     rst = 0;                          // blocking OK for reset only
    //     @(negedge clk);                   // wait for NBA region to settle
    //     // Now all DUT registers have their reset values
    //
    // Rule 3: MULTI-BLOCK/MESSAGE SENDING PATTERN
    //   When sending multiple blocks to a processing core:
    //     // Block 1 (NOT the last):
    //     msg_block <= BLOCK1_DATA;
    //     msg_valid <= 1'b1;
    //     is_last   <= 1'b0;       // MUST be 0 for all non-final blocks
    //     @(posedge clk);          // DUT samples inputs (msg_valid + is_last together)
    //     msg_valid <= 1'b0;
    //     is_last   <= 1'b0;       // hold 0 — never let it float into the gap
    //     // ... wait for block to complete ...
    //     @(posedge clk);          // inter-block gap — DUT FSM returns to IDLE
    //
    //     // Block 2 (the LAST block):
    //     msg_block <= BLOCK2_DATA;
    //     msg_valid <= 1'b1;
    //     is_last   <= 1'b1;       // MUST be 1 at the SAME posedge as msg_valid
    //     @(posedge clk);          // DUT samples both signals here
    //     msg_valid <= 1'b0;
    //     // is_last hold rule: see is_last sub-rule below.
    //
    //   CRITICAL: After a valid pulse, add at least one @(posedge clk) gap
    //   before driving the next block. The DUT FSM needs time to transition
    //   back to IDLE and re-assert ready.
    //
    // Rule 3a: is_last SEMANTICS (CRITICAL — was wrong in SM3 run)
    //   `is_last` is a *per-block* flag co-sampled with `msg_valid`. Strict rules:
    //   - All non-final blocks: `is_last <= 1'b0` at the same posedge as `msg_valid <= 1'b1`.
    //     Never leave is_last at its prior value — always re-drive 0 explicitly.
    //   - The final block: `is_last <= 1'b1` at the same posedge as `msg_valid <= 1'b1`.
    //   - Hold lifetime:
    //       * If the port's `handshake` is `single_cycle` / `pulse`:
    //           Deassert `is_last` together with `msg_valid` at the next posedge.
    //       * If the port's `handshake` is `hold_until_ack`:
    //           Hold `is_last` stable along with `msg_valid` until DUT asserts the
    //           ack/ready confirming the last block was consumed; then deassert
    //           BOTH together at the next posedge.
    //   - `is_last` MUST be driven with `<=` (non-blocking) like all other DUT inputs.
    //   - When the testbench has only ONE block, `is_last <= 1'b1` at the sole
    //     msg_valid posedge. Do not split it into a separate posedge.
    //
    // Rule 4: OUTPUT SAMPLING — posedge vs negedge (CRITICAL — caused SM3 Bug 3)
    //
    //   Two categories of output signals with DIFFERENT sampling rules:
    //
    //   A) PULSE signals (valid_out, ready, done, valid_out):
    //      These are single-cycle pulses. Detect AND sample at the SAME @(posedge clk).
    //      Do NOT insert @(negedge clk) between detection and sampling — the pulse
    //      may be cleared on the next posedge.
    //
    //   B) REGISTERED DATA outputs (result_out, result, data_out):
    //      These are NBA-driven register values. They MUST be sampled at @(negedge clk)
    //      AFTER the posedge where the valid pulse was detected. Reason: at the posedge
    //      where valid_out first appears, the DUT's NBA has just scheduled the new
    //      result_out value but it hasn't propagated through the event queue yet.
    //      Reading result_out at the SAME posedge as valid_out returns the PREVIOUS value.
    //
    //   CORRECT pattern (pulse detection + data sampling):
    //     // Wait for valid pulse at posedge
    //     while (valid_out !== 1'b1) @(posedge clk);
    //     // valid_out is 1 here — detected at posedge ✓
    //     // result_out is STALE here — NBA hasn't settled yet ✗
    //     @(negedge clk);  // wait for NBA to settle on result_out
    //     // result_out now has the correct new value ✓
    //     check_result(expected, "test_name");
    //
    //   WRONG pattern (reads stale result_out):
    //     while (valid_out !== 1'b1) @(posedge clk);
    //     check_result(expected, "test_name");  // result_out = OLD value!
    //
    //   Note: If the data output is purely combinational (assign data_out = data_reg),
    //   a simple #1 delay after posedge also works. But @(negedge clk) is the
    //   universal pattern that works for both registered and combinational outputs.
    //
    // Rule 5: TIMING CONTRACT QUICK REFERENCE
    //   When spec.json timing_contract shows:
    //     same_cycle_visible=false, pipeline_delay_cycles=1
    //     → Consumer sees NEW value one posedge AFTER producer writes it.
    //       Insert one @(posedge clk) between driving and checking.
    //     same_cycle_visible=true, pipeline_delay_cycles=0
    //     → Consumer sees value immediately. Check on the same posedge.
    //
    // Rule 6: DATA INPUT HOLD TIME (CRITICAL — prevents hash mismatches)
    //   Data inputs must remain stable until the DUT has sampled them.
    //   If the control signal that triggers sampling has pipeline_delay_cycles=N
    //   in the timing_contract, keep data inputs stable for N+1 cycles AFTER
    //   deasserting valid. Do NOT clear msg_block immediately with msg_valid.
    //
    //   CORRECT (N=1, e.g. registered FSM → combinational datapath):
    //     msg_block <= BLOCK_DATA;
    //     msg_valid <= 1'b1;
    //     @(posedge clk);          // handshake posedge
    //     msg_valid <= 1'b0;
    //     @(posedge clk);          // wait for load_en to propagate
    //     msg_block <= 512'd0;     // NOW safe to clear
    //
    //   WRONG (data cleared before consumer sees load_en):
    //     msg_block <= BLOCK_DATA;
    //     msg_valid <= 1'b1;
    //     @(posedge clk);
    //     msg_valid <= 1'b0;
    //     msg_block <= 512'd0;     // BUG: cleared one cycle too early!
    //
    // ===========================================================================

    // ===========================================================================
    // MACROS: Race-free sampling helpers
    // ===========================================================================
    // Use these macros instead of raw @(negedge clk) to avoid race conditions.
    //
    // Failure log format (parsed by timing_diagnostic.py):
    //   [FAIL] test=<name> cycle=<n> signal=<s> kind=<registered|pulse>
    //          width=<w>b expected=0x<hex> actual=0x<hex> xor=0x<hex> phase=<edge>
    // Keep this format stable — the diagnostic tool relies on it.
    `define SAMPLE_REGISTERED_OUTPUT(sig, expected, test_name) \
        @(negedge clk); \
        if (sig !== expected) begin \
            $display("[FAIL] test=%s cycle=%0d signal=%s kind=registered width=%0db expected=0x%0h actual=0x%0h xor=0x%0h phase=negedge", \
                     test_name, cycle_count, `"sig`", $bits(sig), expected, sig, (expected ^ sig)); \
            fail_count = fail_count + 1; \
        end else \
            $display("[PASS] test=%s cycle=%0d signal=%s kind=registered width=%0db actual=0x%0h phase=negedge", \
                     test_name, cycle_count, `"sig`", $bits(sig), sig);

    `define SAMPLE_PULSE_OUTPUT(sig, expected, test_name) \
        if (sig !== expected) begin \
            $display("[FAIL] test=%s cycle=%0d signal=%s kind=pulse width=%0db expected=0x%0h actual=0x%0h xor=0x%0h phase=posedge", \
                     test_name, cycle_count, `"sig`", $bits(sig), expected, sig, (expected ^ sig)); \
            fail_count = fail_count + 1; \
        end else \
            $display("[PASS] test=%s cycle=%0d signal=%s kind=pulse width=%0db actual=0x%0h phase=posedge", \
                     test_name, cycle_count, `"sig`", $bits(sig), sig);

    // ===========================================================================
    // RESET TASK: Must be called at start of EVERY independent test
    // ===========================================================================
    task automatic apply_reset;
        begin
            rst = 1;
            data_in <= 0;  // zero all data inputs with NBA
            @(posedge clk); @(posedge clk); @(posedge clk);
            rst = 0;
            @(negedge clk);  // wait for NBA to settle after rst deassert
            $display("[TRACE] cycle=%0d rst released", cycle_count);
        end
    endtask

    // ===========================================================================
    // Test cases
    // ===========================================================================
    initial begin
        // --- Test case 1: <description> ---
        apply_reset();
        data_in <= 32'h0000_1234;
        @(posedge clk);   // DUT samples data_in
        `SAMPLE_REGISTERED_OUTPUT(data_out, 32'hEXPECTED, "test1")

        // --- Test case 2: multi-cycle operation with valid/ready handshake ---
        // CRITICAL: Call apply_reset() before EVERY independent test to prevent
        // state accumulation (e.g., hash chaining variables retaining stale values).
        apply_reset();

        // IMPORTANT: When polling for single-cycle pulse signals (valid_out, ready):
        //   - PULSE detection: Detect the signal at posedge in a wait loop
        //   - DATA sampling: Read the guarded data output at @(negedge clk) AFTER
        //     detecting the pulse — this gives NBA time to settle on registered outputs
        //   - Do NOT read data outputs at the same posedge as pulse detection
        //
        // Correct pattern (pulse at posedge, data at negedge):
        //   wait_valid(cycles);   // polls @(posedge clk) until valid_out==1
        //   @(negedge clk);            // wait for NBA to settle on result_out
        //   check_result(expected, ...); // NOW result_out has the correct value
        //
        // Wrong pattern (reads stale data — SM3 Bug 3):
        //   wait_valid(cycles);
        //   check_result(expected, ...); // result_out still has PREVIOUS value!

        // --- Summary ---
        if (fail_count == 0) $display("ALL TESTS PASSED");
        else $display("FAILED: %0d assertion(s) failed", fail_count);
        $finish;
    end
endmodule
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall