- Home
- Skills
- Testing & Debugging
- FPGA UVM on Verilator — Bring-Up & False-Pass Check
FPGA UVM on Verilator — Bring-Up & False-Pass Check
Get a UVM testbench running on an open-source simulator — and find out whether your green run verified anything at all.
$30
Works with the AI Agents you already use
FPGA UVM on Verilator — Bring-Up & False-Pass Check
Example session with this skill installed
Our nightly UVM regression on Verilator has been green for three weeks, but a colleague says the waveform looks empty and he doesn't trust it. We're also about to port two more VIP blocks over from Questa. Can you check whether the green runs mean anything, and tell me what the port is going to cost me? Log is at ci/nightly.log, sources under rtl/ and tb/.
- Read your context and instructions
- Compiled the fpga uvm on
Summary
Your colleague is right. Three weeks of green nightlies verified nothing — your simulator is below the release boundary where UVM phases actually run. The port itself is small: six mechanical fixes and one real decision.
1. Preflight — the release is the problem
$ python3 scripts/preflight.py --uvm-root vendor/uvm
# Preflight — UVM on Verilator
## Simulator version
BLOCKER 5.038 < 5.045
A green run is not trustworthy here: simulation time can
advance and UVM_INFO lines can appear while the phases
stand still. Upgrade first, then measure.
Pin a specific version, never 'latest'.
## UVM library in the source tree
FOUND IEEE 1800.2-2017
vendor/uvm/src/uvm_pkg.sv
This is the edition that runs without extra work.
It omits the deprecated-API macros — see signature S02.
## Machine against the two cost centres
WARNING 4 core(s): compiling the ~10,000 generated C++ files
then dominates. Set -j, and get more cores if you can.
OK 32.0 GB.
## Verdict
RED — 1 blocker, 1 warning(s).
2. Log triage — the green run was empty
$ python3 scripts/triage_log.py ci/nightly.log --exit-code 0
## False-pass check
UVM messages: 1184 | Report Summary: NO | Run-phase trace: yes |
Objection: NO | Phase names: 2 | Time advances: yes
FALSE_PASS_SUSPECTED — this run is not trustworthy:
- No UVM Report Summary: the run never reached the report,
although UVM messages are present.
- No objection message: without an objection raised and
dropped, the run phase did no work.
- No driver/monitor/scoreboard activity in the log.
- Simulation time advances while the report is missing —
exactly the picture of the objection trip.
The run ended with exit 0 — so CI reports green.
Golden logs that were updated onto this state cement the
false pass. Review the golden logs as well.
1184 UVM_INFO lines and not one of them is evidence. Time advanced, so the dashboard looked healthy. The phases stood still.
3. Source scan — what the port actually costs
$ python3 scripts/scan_sources.py tb/
# Port scan — 47 file(s) under tb/
## Findings (6 site(s))
### S01 — starting_phase used as a variable [reported]
Cause: Replaced by get_starting_phase()/set_starting_phase()
in UVM 1.2. The 1800.2 library has no such member.
Fix: Move the accesses to the accessors.
Sites (2):
apb/apb_seq.sv:34 starting_phase.raise_objection(this);
ahb/ahb_seq.sv:51 starting_phase.raise_objection(this);
### S02 — Deprecated-API macros [derived]
Fix: Shim back (~50-100 lines) or rewrite onto
start_item/finish_item. The rewrite is durable.
Sites (1): apb/apb_seq.sv:38 `uvm_do(req)
### S04 — Integer literal assigned to an enum [reported]
Cause: Commercial simulators only warn; this is an error here.
Sites (1): apb/apb_pkg.sv:77 state = 1;
### S07 — SVA sequence with a temporal range [reported]
Fix: Do not port as a sequence. Rebuild as a property using
$past plus modelling logic.
Sites (1): ahb/ahb_props.sv:88 ready ##[1:5] !ready;
## Hints (1 site(s)) — not a failure, just check
- S10 protected/local members: 1 site, e.g. apb/apb_seq.sv:12
What to do, in order
| # | Action | Effort |
|---|---|---|
| 1 | Upgrade past the boundary, then pin the version | 30 min |
| 2 | Regenerate the golden logs — the current ones encode the broken behaviour | 1 h |
| 3 | S01, S04: mechanical rewrites, no design decision | 30 min |
| 4 | S02: shim vs. rewrite — see the decision table in references/signatures.md | your call |
| 5 | S07: rebuild one assertion with $past; do not try to make the sequence work | 2 h |
| 6 | Set -j4, watch the link stage for RAM | ongoing |
Two things worth knowing before you start
Don't chase the sequence. S07 is the one place to stop rather than engineer. Developers who maintain the scheduler assess SVA sequence support as genuinely hard given the architecture, and the explicit advice is not to attempt it — including with AI assistance. The $past rebuild is the route by which real AXI and APB assertion IP was ported.
Budget the compile, not the runtime. Runtime here is fast — up to 10x a commercial simulator, because it's two-state with no event scheduling. The cost is the compile: ~10,000 generated C++ classes, measured at 4,000 s serial and up to 12,000 s worst case on a 4-core box. Your 32 GB is comfortable for the link stage; your 4 cores are the bottleneck. That is why step 3 above ran a scan instead of six compiles.
Next steps
- Upgrade and pin — nothing else is meaningful until then.
- Re-run
triage_log.pyon the first post-upgrade nightly. ExpectPLAUSIBLY_REAL. - Keep that log as your known-good reference, so the next regression of this class is a diff rather than an archaeology project.
- Before porting the two new VIP blocks, scan them first:
scan_sources.py vip/.
Connects securely to your tools. The creator never sees your data.
About this skill
The bug that makes a green CI worthless
Running UVM without a commercial licence became realistic only recently — and for a stretch of releases it came with a trap. The simulator produced runs that looked green: simulation time advanced, UVM_INFO lines printed in volume, the process exited clean. And the UVM phases never ran. A scheduler-inserted objection trip stalled them.
Then it got worse. The CI golden logs were updated onto that broken state. Once the expected output is the broken output, CI reports green forever and nobody downstream can see it.
That is why the advice you find online contradicts itself. "UVM runs on Verilator" and "UVM does not run on Verilator" were both true, in different months, and almost nobody writes down the release number. This skill starts by settling that question — before you debug a single line.
What it does
1. Establishes that a pass can be real. preflight.py checks your simulator release against the boundary below which phase behaviour cannot be trusted, identifies which UVM library edition is in your tree, and sizes your machine against the two compile cost centres. Below the boundary it says BLOCKER and tells you to stop: the release is the cause, not your code.
2. Triages any run you already have. triage_log.py inverts the usual logic — it looks for the traces a real UVM run leaves behind (report summary, run-phase activity, an objection raised and dropped, driver/monitor/scoreboard messages) and reports their absence, because absence is what the false pass looks like. If the run also exited 0, it says so explicitly and tells you to review the golden logs too.
3. Finds the port failures before you pay for a compile. scan_sources.py scans your tree for ten catalogued signatures and prints the cause and the fix per site: starting_phase used as a variable, deprecated-API macros (uvm_do and family), enforced encapsulation, integer literals assigned to enums, non-blocking assignment to class members, hierarchical bind, assignment to input ports, randc, flattened structs, SVA sequences with temporal ranges.
This matters because of arithmetic, not tidiness. One compile of a large UVM design was measured at up to 12,000 seconds — three and a half hours. Finding six failures one abort at a time costs a day. Finding them in one scan costs a second.
The knowledge behind it
Six reference files, each built from measured material rather than general advice:
| File | What is in it |
|---|---|
false-pass.md | The release boundary, the objection-trip mechanism, how to detect it by hand, and the golden-log trap that keeps it alive in CI |
signatures.md | S01–S10 and L01–L09 written out with cause, fix and confidence grade, plus the macro-shim-versus-rewrite trade-off as a decision table |
compile-economics.md | The measured numbers (~10,000 generated C++ classes, ~4,000 s serial, 12,000 s worst case, down to ~20 min tuned) and the two cost centres: parallelism on the compile, RAM on the link stage |
assertions.md | The subset that works (##1, $past), the subset not to attempt (SVA sequences — and why, from the people who maintain the scheduler), and the $past-plus-modelling-logic rebuild that actually got bus assertion IP ported |
limits.md | Two-state, no gate-level+SDF, no mixed-signal, not a sign-off simulator — and the division of labour that follows: develop the testbench here, run sign-off where it belongs |
bug-report.md | Why an unminimised report goes nowhere (your 10 lines pull in 100,000 underneath) and what a usable one contains |
Honest about its edges
Each signature carries a grade: reported means it was named as a concrete port failure; derived means standard library knowledge applied to that failure mode. The survey behind this catalogued 33–34 distinct failure signatures; roughly fifteen were documented in enough detail to pin a cause and a fix, and only those are here. No invented entries fill the gap, and the scanner says plainly that a clean scan is not a promise that the compile will pass.
The compile-tuning knowledge stops where the evidence stops: -j and the link stage's memory appetite are established, and no magic flag combination is claimed beyond them.
What you get
SKILL.mdwith a six-step workflow, a worked example you can reproduce from the bundled fixtures, ordered troubleshooting and an escalation rule- Three Python scripts, pure standard library, each with
--selftestrunning positive and negative controls - Two example inputs: a legacy sequence carrying six real failures, and a false-pass log
- Six reference files, proprietary licence included
Local-first and quiet: no network access, no telemetry, nothing phoned home, no files written to your tree. Runs on an air-gapped machine. Works with any agent that reads the SKILL.md standard.
Who it is for
Teams porting UVM off a commercial licence. Anyone whose nightly regression is green and who cannot quite explain why the waveform looks empty. Groups using AI to generate UVM code, where the compiler-in-the-loop iteration count is the whole cost model and a licence checkout per iteration is the thing that kills it.
Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for Testing & Debugging.
No support for four-state logic, SDF back-annotation, or mixed-signal. Temporal assertions are restricted to a working subset. Requires Verilator release pinning for reproducible results.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before buying a skill.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Money-back guarantee
Doesn't do what its page promises? You get your money back.
Trust & safety
Security scan
Security scan passed 22 days ago
- Software
Python 3.8+
- Optional
- Verilog/SystemVerilog simulatorUVM library
Python needs only its standard library. An open-source simulator and UVM library are only needed to act on the findings.