hdl-tools/digital-chip-design-agents/functional-verification

Skill: Functional Verification (UVM)

Invocation

When this skill is loaded and a user presents a verification task, do not execute stages directly. Immediately spawn the digital-chip-design-agents:verification-orchestrator agent and pass the full user request and any available context to it. The orchestrator enforces the stage sequence, loop-back rules, and sign-off criteria defined below.

Use the domain rules in this file only when the orchestrator reads this skill mid-flow for stage-specific guidance, or when the user asks a targeted reference question rather than requesting a full flow execution.

Pre-run Context

Before executing or advising on any stage, read the following files if they exist:

1. memory/verification/knowledge.md — known failure patterns, successful tool flags, PDK/tool quirks.

Incorporate its guidance into every stage decision. If absent, proceed without it.

1. memory/verification/run_state.md — current run identity (run_id, design_name, tool,

last_stage). Use this to resume correctly after interruption. If absent, a new run is starting; the orchestrator will create this file before the first stage.

This pre-run read applies whether this skill is loaded by a user or called by the orchestrator mid-flow. It ensures the fix database is consulted before any diagnosis step.

Purpose

Guide the complete UVM functional verification flow from testbench architecture through coverage-closed regression sign-off. Produces a verified RTL package with documented coverage and a clean regression. Also guides port mode: bringing an existing, passing testbench up on another simulator (simulator_portability), and reviewing coverage holes without closing them (coverage_analysis report-only mode).

Supported EDA Tools

Open-Source

• Verilator (verilator) — fast cycle-accurate simulator; UVM support via verilator+UVM
• Icarus Verilog (iverilog) — event-driven simulation for quick testbench checks
• cocotb — Python-based co-simulation framework (pip install cocotb)
• PyUVM — UVM implementation in Python for cocotb environments
• UVVM — VHDL verification methodology library

Proprietary

• Synopsys VCS (vcs, dialect synopsys) — industry-standard SV/UVM simulator
• Cadence Xcelium (xrun, dialect cadence) — multi-language simulator with coverage engine
• Siemens Questa (vsim / vlog / vcom, dialect siemens) — mixed-language simulation with UVM support
• Synopsys URG (urg, dialect synopsys) — merges and reports VCS .vdb coverage; wrapper wrap-urg.sh
• Cadence IMC (imc, dialect cadence) — merges and reports Xcelium cov_work coverage; wrapper wrap-imc.sh. Often off PATH, or not installed with Xcelium at all

cocotb runs on any of these through SIM= (see simulator_portability). Its makefile's exit code is not a verdict on any simulator; wrap-cocotb-results.sh reads results.xml.

Stage: simulator_portability

Entered only in port mode — an existing, passing testbench (cocotb or UVM) is brought up on a simulator it has not run on (for example a Verilator-only cocotb regression moved to VCS and Xcelium). The testbench and its checks are inputs, not artifacts this stage designs: the tb_architecture → constrained_random stages do not run. The simulator the regression already passes on is the reference simulator; its results are the baseline every new simulator is compared against.

Domain Rules — cocotb invocation

1. cocotb selects the simulator by SIM: verilator, icarus, vcs, xcelium, questa

(the value is the makefile name under cocotb's share/makefiles/simulators/, so check cocotb-config --makefiles for the installed version). Pass flags through cocotb's own variables, never by editing cocotb's makefiles:

cocotb 2.x renamed MODULE/TOPLEVEL to COCOTB_TEST_MODULES/COCOTB_TOPLEVEL; read the names from the installed version rather than assuming either

1. Read the COMPILE_ARGS/EXTRA_ARGS that cocotb's Makefile.<sim> already supplies

(make -n SIM=<sim>) before adding any: cocotb passes its own VPI-load and debug flags, and a duplicate is at best noise. Never set `EXTRA_ARGS` on the `make` command line for `SIM=xcelium`: a command-line variable overrides every makefile assignment, so it silently discards cocotb's own EXTRA_ARGS += in Makefile.xcelium, which carries -top, -xmlibdirpath and -licqueue (observed). Translate the reference value inside the shared include into a separate variable (or override undefine EXTRA_ARGS there, then append), and confirm with make -n that cocotb's own flags are still present

Domain Rules — Translating Verilator-only idioms

1. Translate every reference-simulator flag through this table. A flag with no row is

investigated and added to the table in the stage output, never passed through untranslated:

Quoting a string parameter goes through make and the shell; prove each override took effect by reading the parameter back in the smoke run (dut.<P>.value in cocotb, or a $display) and comparing it with the reference simulator's value — a mis-quoted string silently becomes the default. Any parameter-override warning (`PRM_ILLG`, `BDDSTR`, "parameter not found", "ignored") is a FAIL of the translation, not noise: the run that follows simulated the default value. Verilator's -I also resolves modules by file name, so a filelist can omit a module and still build on Verilator; map -I to the library search (-y/+libext+) as well as +incdir+, or — better — add the missing file to the filelist and record which modules were found only by search. Add a VPI access flag only when a test fails to find a signal (cocotb AttributeError on a handle) under cocotb's own default, and record which signal needed it

1. One shared make include, not per-target edits. Put the whole translation in one file

(e.g. sim_portability.mk) that every test makefile includes, with every rule guarded on SIM (ifeq ($(SIM),vcs) … else ifeq ($(SIM),xcelium) …). A per-target copy drifts: the tenth makefile edited is the one that misses a define

1. The reference simulator's command lines stay byte-identical. Before the include is added,

capture make -n SIM=<reference> <target> for every target into before/<target>.txt; after, capture the same into after/, and compare with cmp -s (exit 0 per file). Any difference is a FAIL of this stage until explained and accepted by the user — not diff output read by eye, and not a filtered diff, which can report changed files as identical. Where the reference simulator is not installed on the porting host, use make -n -i with a stub executable of the same name first on PATH (Verilator's build recipe runs make -C even under -n), and normalise make's own Makefile:NNN: line numbers in its warnings (sed -E 's/(Makefile[^:]*):[0-9]+:/\1:N:/') in both captures before cmp; say in the output that the proof used a stub. Parity of the command lines is not parity of the result: before handing a port back, run the reference simulator's lint and regression at the version CI executes (read it from the CI log or lockfile, not a comment). A testbench or model edit made for the new simulator can fail a lint rule that only a newer reference release has (PROCASSINIT in Verilator 5.048)

1. One `SIM_BUILD` per simulator (sim_build_vcs, sim_build_xcelium), set inside the

SIM-guarded branches so the reference simulator keeps its existing directory (rule 5). A shared directory lets one simulator's stale objects or results.xml be read as the other's

1. A `verilator --lint-only` prerequisite is skipped or replaced, never counted. Where a make

target runs Verilator lint before simulating, guard it on SIM=verilator, or replace it with the target simulator's compile as the gate. Report lint as NOT RUN for that simulator — a lint step that ran under another simulator's name is not evidence that the RTL compiles clean there. The same holds for every Verilator-only test: elaboration-guard checks (a parameter value that must fail to elaborate), *_neg targets and lint-based tests inside suites. List each one by name as NOT RUN for the commercial simulator, and account for them explicitly against any pass floor (expected = reference_passed − not_run_verilator_only). Never drop them silently, and never count them as passed

1. Resolve the simulator from a non-interactive shell. A user alias (alias vcs 'vcs -full64'

was observed) does not exist inside make; write -full64 into the VCS compile arguments explicitly, and record the binary path command -v vcs resolved to