lazyuvm 0.1.6

Local-first RTL verification knowledge platform for UVM scaffolds, reviewed maps, pattern packs, and CI gates.

LazyUVM

LazyUVM is a local-first RTL verification knowledge platform. Bootstrap UVM environments, capture reviewed verification knowledge, and generate CI-readable evidence from local RTL projects.

It is deliberately local-first: no required cloud service, no required Python packages, and optional Ollama summaries only when a user explicitly asks for local AI help.

The LazyUVM checked badge means the repository's smoke checks pass on GitHub Actions. It is a quick project-health signal, not silicon sign-off.

Product Shape

LazyUVM has four connected workflows:

Layer	What it does	Main commands
Bootstrap	Scan RTL, resolve filelists, infer obvious protocols, generate starter UVM/SVA/coverage, and run smoke checks.	check, uvm, quality, report, regress
Knowledge	Commit reviewable protocol maps, register maps, behavior specs, reviewed patterns, and portable bundles.	regs, spec, pack, suggest-protocol-map, suggest-register-map
Workflow	Search, explain, recommend, trace, and snapshot the local verification knowledge that a team has reviewed.	know query, know explain, know recommend, know trace, know manifest
CI Gate	Turn the reviewed knowledge state into repeatable Markdown/JSON evidence for pull requests and releases.	gate, init-ci, baseline diff, pack manifest-verify

The useful moat is the Git-friendly knowledge format, not hidden telemetry:

RTL + protocol maps + register maps + behavior specs + reviewed pattern packs
  -> LazyUVM
  -> starter artifacts + traceability + manifests + CI gate reports

Typical Team Workflow

Most teams should start with the short project commands, then drop into the older direct flags only for one-off scans.

1. Initialize the project once:

   lazyuvm init --filelist path/to/files.f --top your_top_module
   

2. Commit the reviewed project knowledge:

   lazyuvm suggest-protocol-map --module your_top_module --out suggested_protocol.toml
   lazyuvm suggest-register-map --module your_top_module --out suggested_registers.toml
   lazyuvm regs
   lazyuvm spec
   

3. Run the daily local gate:

   lazyuvm check
   lazyuvm quality --strict
   lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json
   

4. Wire the same flow into GitHub Actions:

   lazyuvm init-ci --filelist path/to/files.f --top your_top_module --repo OWNER/REPO
   

5. During review, inspect the evidence instead of rereading every config file:

   lazyuvm know query "apb timeout"
   lazyuvm know trace --out LazyUVM_Traceability.md
   lazyuvm know manifest-verify LazyUVM_Knowledge_Manifest.json
   lazyuvm gate --strict --manifest LazyUVM_Knowledge_Manifest.json
   

   Traceability links behavior specs to register maps, reviewed debug patterns, and configured coverage holes from reports.coverage_report.

For the coverage governance loop, see docs/team_governance_workflow.md. It walks through coverage holes, reviewable fix drafts, accepted waivers, baseline deltas, and CI gate evidence as one pull-request workflow. The runnable sample config is examples/governance_demo.toml; run lazyuvm demo governance to print the copy/paste command loop for that sample. For the reviewer side of the same flow, see docs/team_governance_pr_review.md.

Why This Exists

Research frameworks such as UVLLM and UVMarvel explore ambitious LLM-driven RTL verification flows. Commercial EDA tools own sign-off verification. LazyUVM is deliberately narrower: it targets the local first mile where a student, junior engineer, or small team needs project setup, starter artifacts, reviewed knowledge, and CI evidence in a few minutes.

Area	Research Frameworks	LazyUVM
Goal	Broad automated verification research	Local verification bootstrap and knowledge reuse
Setup	Larger framework and experiment flow	pipx install lazyuvm, then lazyuvm init
AI	Often benchmarked with large LLM workflows	Optional local Ollama explanations over LazyUVM facts
First use	Read paper, configure stack, run experiments	Commit lazyuvm.toml, run lazyuvm gate
Current strength	Full research pipeline	Team-owned protocol/register/spec/pattern knowledge in Git

LazyUVM is not a replacement for sign-off verification. It is the local layer before that: the place where teams make the first environment, document why checks exist, preserve recurring debug knowledge, and keep CI honest.

For the current package boundary, known limits, and modularization roadmap, see docs/architecture.md.

Installation

From a local checkout:

python3 -m pip install -e .
lazyuvm --version
lazyuvm --help
lazyuvm legacy --help  # advanced one-off scan flags

From the current main branch:

pipx install git+https://github.com/jeonghunx/LazyUVM.git

From PyPI's latest release:

pipx install lazyuvm

Contributors can still run python3 rtl_scout.py ... directly from the repository, but lazyuvm ... is the preferred CLI. Top-level lazyuvm --help shows the project-command workflow. Use lazyuvm legacy --help only when you need the older direct flags such as --tb-dir, --uvm-dir, --analyze-log, or --analyze-coverage. Use lazyuvm <command> --help or lazyuvm help <command> for detailed command options. Calling those direct flags without the legacy subcommand now prints a deprecation warning to stderr. The flags still work for compatibility, but new automation should prefer lazyuvm.toml plus project commands such as lazyuvm check, lazyuvm uvm, and lazyuvm gate.

Release Status

Current repository version: 0.1.6

Latest PyPI release: 0.1.6

• See CHANGELOG.md for the release history.
• See RELEASE_CHECKLIST.md before cutting a tag.
• See docs/releases/v0.1.6.md for the latest release note.
• The GitHub Actions badge should be green before cutting a release tag.
• PyPI publishing is configured through .github/workflows/release.yml and PyPI Trusted Publishing.

Quick Start

From a checkout of the current main branch:

cd "/mnt/c/Users/jeonghun-dev/Documents/New project"

lazyuvm --version
lazyuvm check
lazyuvm report
lazyuvm regress
lazyuvm uvm
lazyuvm baseline save
lazyuvm baseline diff
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --no-ai

lazyuvm init writes a project-owned lazyuvm.toml. Commit that file so teammates and CI can run the same local verification flow without copying long command lines.

For a new RTL project:

lazyuvm init --filelist path/to/files.f --top your_top_module

For a new GitHub project that should get the full LazyUVM workflow:

lazyuvm init-ci --filelist path/to/files.f --top your_top_module --repo OWNER/REPO

The generated workflow installs LazyUVM from the package source passed with --package. The default is the PyPI package, lazyuvm. During unreleased development, pass a Git URL if you intentionally want CI to install from a branch.

For focused one-off examples, see the sections below for filelists, tool commands, regression, coverage triage, hierarchy, auto-run, log analysis, and reviewed pattern packs.

Project Config

lazyuvm.toml is the sticky project entry point:

[project]
filelist = "examples/files.f"
top = "apb_timer"
no_ai = true
ollama_model = "llama3.2:1b"
ai_timeout = 60
no_lint = false

[reports]
auto_dir = ".lazyuvm"
report = "LazyUVM_Report.md"
regress_file = "examples/regress.yaml"
regress_dir = ".lazyuvm_regress"
regress_report = "LazyUVM_Regression.md"
uvm_dir = "generated_uvm"
seeds = "1"
baseline = "lazyuvm_baseline.json"
coverage_report = "examples/coverage_report.txt"
coverage_threshold = 90.0

[registry]
cache_dir = ".lazyuvm_cache"
registry_dir = ".lazyuvm_registry"

[knowledge]
strict_modules = ["apb_timer", "axi_lite_gpio"]
strict_checks = ["missing_protocol_maps", "missing_register_maps", "no_reviewed_patterns"]
strict_require_registry_bundles = false
explain_query = "apb timeout"

[knowledge.trace]
ignored_signals = ["clk", "pclk", "aclk", "reset", "resetn", "rst_n", "presetn", "aresetn"]
min_pattern_signal_overlap = 2

[behaviors.apb_timer.apb_access_completes]
description = "APB access must eventually complete once setup/access is active"
protocol = "APB"
trigger = "psel && penable"
expect = "pready"
within_cycles = 16
severity = "error"
registers = ["counter"]
fields = ["counter.value"]

Once the config is committed, the project workflow becomes short and repeatable:

lazyuvm check     # hierarchy + static RTL checks
lazyuvm report    # auto-run + Markdown report
lazyuvm regress   # regress.yaml or seed regression
lazyuvm uvm       # generated UVM/SVA/coverage/bind skeletons
lazyuvm spec      # validate behavior/spec intent maps
lazyuvm regs --ral-plan --out LazyUVM_RAL_Plan.md
lazyuvm spec --ral-plan --out LazyUVM_RAL_Plan.md
lazyuvm spec --plan --out LazyUVM_Spec_Plan.md
lazyuvm spec --sequence-plan --out LazyUVM_Sequence_Plan.md
lazyuvm spec --coverage-plan --out LazyUVM_Coverage_Plan.md
lazyuvm spec --scoreboard-plan --out LazyUVM_Scoreboard_Plan.md
lazyuvm spec --sva-dir generated_specs
lazyuvm spec --sequence-dir generated_sequences
lazyuvm spec --coverage-dir generated_behavior_coverage
lazyuvm baseline save
lazyuvm baseline diff
lazyuvm pack stats
lazyuvm know trace --out LazyUVM_Traceability.md
lazyuvm know trace --json --out LazyUVM_Traceability.json
lazyuvm know manifest --out LazyUVM_Knowledge_Manifest.json
lazyuvm know manifest-verify LazyUVM_Knowledge_Manifest.json
lazyuvm know query "apb timeout"
lazyuvm know recommend
lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json

The reviewable knowledge formats behind this workflow are documented in docs/knowledge_formats.md.

lazyuvm know trace filters pattern links with [knowledge.trace]. Keep the default clock/reset ignores, raise min_pattern_signal_overlap, or add noisy project-wide handshakes to ignored_signals when traceability rows are being linked by generic signals instead of useful debug evidence. Use --json when CI jobs, dashboards, or local-AI workflows need the same traceability matrix as a stable lazyuvm.traceability.v1 payload. lazyuvm know manifest fingerprints the current project knowledge sources (lazyuvm.toml, local pattern cache, registry index) and records knowledge counts plus traceability summary as a lazyuvm.knowledge_manifest.v1 payload. lazyuvm know manifest-verify checks that saved snapshot against the current local files, counts, and traceability settings so CI can catch stale knowledge manifests before review.

lazyuvm know query is the first knowledge-workflow command: it groups matching protocol maps, register/spec maps, reviewed patterns, packs, and bundles for one local question. It does not upload project data or ask an AI by default:

lazyuvm know query "pready never asserted"
lazyuvm know query "ctrl enable" --out LazyUVM_Knowledge_Query.md
lazyuvm know explain "apb timeout"
lazyuvm know explain "apb timeout" --ai --out LazyUVM_Knowledge_Explain.md
lazyuvm know explain "apb timeout" --json --out LazyUVM_Knowledge_Explain.json
lazyuvm know recommend --out LazyUVM_Knowledge_Recommend.md
lazyuvm know recommend --json --out LazyUVM_Knowledge_Recommend.json
lazyuvm know recommend --strict --module apb_timer
lazyuvm know doctor --strict

know explain keeps the trust boundary explicit: LazyUVM finds local facts from maps, reviewed patterns, packs, and bundles; optional --ai asks local Ollama to turn those facts into a readable debug note. The AI output is a reading aid, not a verified root-cause diagnosis. Use --json when CI jobs, dashboards, or future local-AI workflows need the same facts as a stable lazyuvm.knowledge_explain.v1 payload. Generated lazyuvm init-ci workflows upload both explain and recommend reports as Markdown/JSON artifacts so project knowledge can be reviewed without scraping terminal logs.

Use --strict when CI should fail on missing core project knowledge such as protocol maps, register maps, or reviewed patterns. Registry bundles are reported as recommendations, but they are not strict blockers by default. Projects can pin that policy in [knowledge]: use strict_modules to limit the enforced entry points, strict_checks to choose blocker recommendation codes, and strict_require_registry_bundles = true when a team bundle is mandatory. know recommend --strict and know doctor --strict use the same policy so local diagnostics and CI gates agree.

The repository includes a portable example bundle:

lazyuvm pack bundle-validate examples/team_knowledge_bundle.json
lazyuvm pack bundle-import examples/team_knowledge_bundle.json --maps-out lazyuvm_imported_maps.toml

For the full local publish/pull loop, see docs/team_registry_demo.md.

The checked GitHub Actions workflow also smoke-tests this knowledge loop by validating the example bundle, running know query / know recommend, uploading the Markdown and JSON recommendation reports as an artifact, writing a short baseline/knowledge summary to the GitHub Actions run summary, and round-tripping a bundle through a temporary self-hosted registry.

Custom Protocol Maps

LazyUVM first tries protocol inference from familiar names such as psel, penable, and awvalid. Real projects often use names like cfg_sel, cfg_enable, or cfg_ack. Add a [protocols.<module>] section to lazyuvm.toml when a module uses project-specific naming:

[protocols.cfg_timer]
protocol = "APB"
pclk = "clk"
presetn = "rst_n"
paddr = "cfg_addr"
psel = "cfg_sel"
penable = "cfg_enable"
pwrite = "cfg_write"
pwdata = "cfg_wdata"
prdata = "cfg_rdata"
pready = "cfg_ack"
pslverr = "cfg_err"

Then run the normal project command:

lazyuvm uvm --config examples/custom_protocols.toml --uvm-dir /tmp/lazyuvm_custom_uvm

Generated UVM/SVA/coverage files use the real project port names while keeping the APB starter behavior. This is explicit project mapping, not semantic protocol discovery.

lazyuvm check, lazyuvm report, lazyuvm regress, lazyuvm baseline, and lazyuvm uvm validate these maps before trusting them. Missing required protocol signals, unknown canonical keys, and mapped ports that do not exist in the RTL are reported as errors.

To draft a map for custom names, use the suggestion command:

lazyuvm suggest-protocol-map examples/cfg_timer.sv --module cfg_timer --out suggested_protocols.toml
lazyuvm suggest-protocol-map --config examples/custom_protocols.toml --out suggested_protocols.toml

The output is a reviewable TOML snippet with per-signal confidence comments. It is not applied automatically; merge it into lazyuvm.toml only after review and validation.

Register/Spec Maps

Protocol maps explain how project-specific port names map onto APB/AXI-style signals. Register/spec maps explain what project registers mean. This is how LazyUVM avoids pretending that AI inferred ctrl[0] = enable; the team writes that knowledge once and commits it:

[registers.cfg_timer.timer_value]
address = "0x00"
width = 32
access = "rw"
reset = "0x00000000"
description = "Timer value register"

[fields.cfg_timer.timer_value.value]
bits = "31:0"
access = "rw"
reset = "0x00000000"
description = "Current timer value"

Validate and print the map:

lazyuvm regs --config examples/custom_protocols.toml

To draft a register/spec map from obvious signal names, use:

lazyuvm suggest-register-map examples/cfg_timer.sv --module cfg_timer --out suggested_registers.toml

The output is also review-first. LazyUVM may suggest timer_value as a register candidate, but address and reset facts remain TODO until the team checks the spec. Merge the snippet only after review, then run lazyuvm regs and lazyuvm check.

lazyuvm check and lazyuvm baseline save also validate register/spec maps, so broken team knowledge fails early instead of silently feeding bad generated artifacts.

Artifact Quality Gate

lazyuvm quality generates the UVM/SVA/coverage starter set into a quality workspace and checks that the artifact set is complete and structurally sane:

lazyuvm quality --config examples/custom_protocols.toml

It verifies required files, package includes, filelist references, missing-signal placeholders, TODO/FIXME markers, and balanced SystemVerilog structures such as module/endmodule, class/endclass, and task/endtask.

The same report now includes a knowledge recommendation summary so CI reviewers can see protocol-map, register-map, reviewed-pattern, and bundle gaps next to artifact quality findings.

This is a local CI smoke gate for generated starters. It does not claim to replace a commercial simulator compiling full UVM with a vendor library. Use --strict when you want warnings to fail CI too.

Project Gate

lazyuvm gate is the team-facing entry point for the local verification knowledge workflow. It combines project input checks, protocol/register/behavior map validation, generated-artifact quality, strict knowledge policy, pattern pack validation, knowledge manifest verification, and configured coverage triage into one Markdown/JSON report:

lazyuvm gate
lazyuvm gate --strict --manifest LazyUVM_Knowledge_Manifest.json
lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json

Use --update-manifest when intentionally refreshing the reviewed project knowledge snapshot. In CI, use --strict with a committed manifest when you want changes to lazyuvm.toml, reviewed patterns, registry state, or traceability settings to fail until the team updates the snapshot deliberately.

Team Knowledge Bundles

LazyUVM's moat is reviewed local knowledge, not secret telemetry. A team can export protocol maps, register/spec maps, and reviewed pattern cache entries as one portable bundle:

lazyuvm pack --config examples/custom_protocols.toml bundle-export team_cfg_timer_bundle.json
lazyuvm pack bundle-validate team_cfg_timer_bundle.json
lazyuvm pack manifest team_cfg_timer_bundle.json --out team_cfg_timer_bundle.manifest.json
lazyuvm pack manifest-verify team_cfg_timer_bundle.manifest.json --artifact team_cfg_timer_bundle.json
lazyuvm pack bundle-import team_cfg_timer_bundle.json --maps-out lazyuvm_imported_maps.toml
lazyuvm pack bundle-diff old_bundle.json team_cfg_timer_bundle.json

Importing a bundle merges reviewed patterns into the local cache, but it does not silently edit lazyuvm.toml. Protocol/register map sections are written to a reviewable TOML snippet so a human can inspect them before merging. lazyuvm pack manifest writes a lazyuvm.trust_manifest.v1 JSON sidecar with the artifact SHA-256 digest, LazyUVM version, current git commit, and review policy. It is provenance metadata, not a cryptographic signature. lazyuvm pack manifest-verify checks that the current artifact still matches the recorded digest and size, making the manifest usable as a lightweight CI gate.

Self-hosted teams can publish and pull bundles through the file-based registry:

lazyuvm pack --config examples/custom_protocols.toml bundle-publish cfg_timer_basics
lazyuvm pack bundle-pull cfg_timer_basics --maps-out lazyuvm_imported_maps.toml

Search the accumulated local knowledge without opening every JSON/TOML file by hand:

lazyuvm know search apb timeout
lazyuvm know show protocols.cfg_timer
lazyuvm know doctor

CI Bootstrap

lazyuvm init-ci creates the files a project needs to make LazyUVM part of the normal team workflow:

lazyuvm.toml
regress.yaml
LAZYUVM_BADGE.md
.github/workflows/lazyuvm.yml

The generated workflow installs LazyUVM from the package source passed with --package, runs lazyuvm check, lazyuvm report, lazyuvm regress, validates the local pattern-pack state, and then compares against lazyuvm_baseline.json when one exists. If no baseline exists yet, CI saves an initial one for that run so the workflow can pass before the team commits a reviewed baseline. Add --strict-knowledge when the generated workflow should fail on the configured [knowledge] policy from day one.

Baseline snapshots also track local knowledge counts such as protocol maps, register maps, fields, reviewed patterns, and registry bundles. That makes lazyuvm baseline diff show whether the team's reusable verification memory is growing along with the RTL checks.

Use --force only when you intentionally want to overwrite generated files.

Team Pattern Packs

lazyuvm pack is the product-style workflow for team-reviewed local bug patterns. It uses the [registry] paths in lazyuvm.toml, so teams can share trusted patterns without any external service:

lazyuvm pack report
lazyuvm pack search paddr
lazyuvm pack show b5064cf
lazyuvm pack review b5064cf --note "APB setup/access timeout seen in smoke regressions"
lazyuvm pack export team_apb_patterns.json
lazyuvm pack import team_apb_patterns.json
lazyuvm pack publish apb_smoke
lazyuvm pack list
lazyuvm pack pull apb_smoke
lazyuvm pack validate
lazyuvm pack doctor --strict
lazyuvm pack doctor

By default, lazyuvm pack export exports only reviewed entries. Use --all when you deliberately want a raw cache backup. Use pack validate before publishing or sharing a team pack. It checks for empty packs, missing metadata, unreviewed registry entries, and reviewed entries without review notes. Use pack doctor --strict in CI when you want the same health check to fail on validation issues. Use plain pack doctor when a teammate says their cache or shared registry is not behaving as expected.

Generated files appear under:

generated_uvm/apb_timer/

The UVM generator now also writes assertion and coverage sentinels:

generated_uvm/apb_timer/lazyuvm_apb_timer_sva.sv
generated_uvm/apb_timer/lazyuvm_apb_timer_coverage.sv
generated_uvm/apb_timer/lazyuvm_apb_timer_bind.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_sva.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_coverage.sv
generated_uvm/axi_lite_gpio/lazyuvm_axi_lite_gpio_bind.sv

The bind files use SystemVerilog bind plus implicit port connections, so the generated sentinels can be attached to the DUT without editing the original RTL.

Generated outputs are ignored by Git because they can be recreated at any time.

Filelist Project Linker

Real RTL projects often compile from a files.f file instead of a single source path. LazyUVM can now use that same project entry point:

lazyuvm --filelist examples/files.f --hierarchy
lazyuvm --filelist examples/files.f --checks
lazyuvm --filelist examples/files.f --auto-run --no-ai

Supported filelist syntax:

+incdir+include
+define+SIMULATION
+define+WIDTH=32
-f nested_files.f
rtl/top.sv
rtl/block.sv

File paths and nested filelists are resolved relative to the filelist that mentions them. --auto-run passes include dirs and defines through to Verilator and Icarus Verilog, then records the exact reproduce commands in the Markdown report.

Tool Command Generator

LazyUVM can turn a project filelist into copy/paste commands for common RTL tools without launching licensed software:

lazyuvm --filelist examples/files.f --emit-tool verilator
lazyuvm --filelist examples/files.f --emit-tool vcs
lazyuvm --filelist examples/files.f --emit-tool questa

Example output:

verilator --lint-only --sv -f examples/files.f
vcs -sverilog -full64 -f examples/files.f
vlog -sv -f examples/files.f

When you pass --module, LazyUVM treats it as the top/module hint:

lazyuvm --filelist examples/files.f --emit-tool verilator --module chip_top
lazyuvm --filelist examples/files.f --emit-tool vcs --module chip_top
lazyuvm --filelist examples/files.f --emit-tool questa --module chip_top

Regression Runner

For a small local regression:

lazyuvm --filelist examples/files.f --regress --seeds 1,2,3 --no-ai

This writes:

LazyUVM_Regression.md
.lazyuvm_regress/

The regression runner:

• generates a smoke testbench for each selected module
• passes +LAZYUVM_SEED=<seed> into vvp
• repeats each module across the requested seed list
• keeps each case in its own workspace folder
• records lint, compile, simulation, and overall PASS/FAIL status in a Markdown matrix

Seed ranges are supported:

lazyuvm --filelist examples/files.f --regress --seeds 1-10 --module chip_top --no-ai

This is still an early screening loop, not signoff. Its job is to make local smoke regressions cheap enough to run constantly.

For a project-owned regression plan:

lazyuvm --regress-file examples/regress.yaml --no-ai

Example regress.yaml:

tests:
  - name: apb_smoke
    files: files.f
    module: apb_timer
    seeds: 1,2

  - name: axi_smoke
    files: files.f
    module: axi_lite_gpio
    seeds: 1,2

Paths in the YAML file are resolved relative to that YAML file, so a test plan under examples/ can simply use files: files.f.

Supported keys:

• name: test name shown in reports
• files or filelist: one filelist path or a short list
• module or top: module to run
• seeds: comma list or range such as 1,2,3 or 1-10

Coverage Triage

For a text coverage report:

lazyuvm --analyze-coverage examples/coverage_report.txt --no-ai

LazyUVM extracts:

• coverage percentages such as line, branch, toggle, and functional coverage
• common vendor-style table rows with covered/total/percent columns
• ratio-only rows such as 0/1 when the row looks like coverage data
• low coverage metrics below a threshold
• explicit miss lines such as 0 hits, Hits: 0, Count = 0, uncovered, not covered, and never hit
• rule-based next stimulus ideas for APB, AXI-Lite, reset, FSM, and toggle holes

To change the low-coverage threshold:

lazyuvm --analyze-coverage examples/coverage_report.txt --coverage-threshold 80 --no-ai

To write the analysis to a file:

lazyuvm --analyze-coverage examples/coverage_report.txt --coverage-md LazyUVM_Coverage.md --no-ai
lazyuvm --analyze-coverage examples/vendor_coverage_report.txt --coverage-json LazyUVM_Coverage.json --no-ai

The JSON output uses the lazyuvm.coverage_analysis.v1 schema and contains parsed metrics, low/missing coverage items, and deterministic next-stimulus ideas so CI, dashboards, or local-AI workflows can consume coverage facts without scraping Markdown.

With Ollama available, omit --no-ai to add a local summary on top of the rule-based findings.

To generate starter SystemVerilog stimulus tasks from the same coverage holes:

lazyuvm --analyze-coverage examples/coverage_report.txt --coverage-stimulus-dir generated_stimulus --module apb_timer --no-ai
lazyuvm --analyze-coverage examples/vendor_coverage_report.txt --coverage-stimulus-dir generated_stimulus --module apb_timer --no-ai

This writes a skeleton such as:

generated_stimulus/lazyuvm_apb_timer_coverage_stimulus.sv

The generated file contains task stubs for holes such as APB wait states, AXI-Lite backpressure, reset edges, toggles, and generic directed bins. It also records parsed targets such as source locations, coverpoints, bins, branch conditions, and likely protocol signals. It intentionally leaves BFM/UVM calls as TODO comments because real projects name their sequence APIs differently.

Hierarchy Scan

For a folder with multiple RTL files:

lazyuvm --hierarchy examples
lazyuvm --hierarchy --module chip_top examples

This prints top-module candidates and a simple instance tree, for example:

chip_top [AXI-Lite 95%, APB 80%]
|-- apb_timer u_timer [APB 90%]
`-- axi_lite_gpio u_gpio [AXI-Lite 100%]

Width Solver

For parameterized designs:

lazyuvm --widths examples/axi_lite_gpio.sv

This resolves simple integer expressions in packed ranges:

axi_lite_gpio:
  parameters:
    ADDR_WIDTH = 12 => 12
    DATA_WIDTH = 32 => 32
  ports:
    input awaddr: [ADDR_WIDTH-1:0] => 12 bits
    input wstrb: [(DATA_WIDTH/8)-1:0] => 4 bits

Static Checks

For a quick local RTL review:

lazyuvm --checks examples

LazyUVM checks what it can prove from the local source:

• unresolved module instances
• unconnected named child ports
• obvious parent/child port width mismatches
• clock-like modules without reset-like inputs
• reset-like ports with suspicious directions

These checks are intentionally conservative: if LazyUVM cannot infer a width confidently, it avoids guessing a mismatch.

Auto-Run Report

For a one-command local triage loop:

lazyuvm --auto-run examples/apb_timer.sv

This writes:

LazyUVM_Report.md
.lazyuvm/

The auto-run loop:

• scans the RTL
• runs lightweight static RTL checks
• generates a starter testbench
• generates UVM skeleton files
• lints the RTL with Verilator when available
• compiles with iverilog
• runs with vvp
• triages lint/compile/simulation logs
• optionally asks local Ollama for an explanation
• writes patch suggestions under .lazyuvm/patches/

If Verilator is not installed or you only want the simulator path:

lazyuvm --auto-run --no-lint examples/apb_timer.sv

Safety rule: LazyUVM does not modify your RTL source files during auto-run. Patch suggestions are isolated for manual review.

Local AI Log Analysis

AI is optional. The rule-based analyzer works without Ollama:

lazyuvm --analyze-log examples/sim_error.log --no-ai
lazyuvm --analyze-log examples/timing_trace.log --no-ai

The log analyzer extracts suspicious lines and a compact timeline before local AI is used:

Timeline:
  100ns L3 [event] signals: psel=1, penable=0, pwrite=1
  120ns L5 [error] signals: penable=1, penable=0, psel=1, pready=0
  130ns L7 [fatal] signals: psel=1, penable=0, pready=0

With Ollama:

curl -fsSL https://ollama.com/install.sh | sh
ollama pull llama3.2:1b

lazyuvm --analyze-log examples/sim_error.log --ollama-model llama3.2:1b

Spec-Aware Log Cross-Check

For a small spec/log comparison:

lazyuvm --analyze-log examples/timing_trace.log --spec examples/spec.txt --no-ai

LazyUVM extracts simple requirement lines containing words such as must, shall, within N cycles, after reset, and remain high until, then compares the supported rules against the log timeline.

Example requirement:

PENABLE must assert one cycle after PSEL is asserted.
PSEL must remain high until PREADY.

The checker is intentionally conservative. It reports direct evidence from the timeline, for example:

Spec expects `penable` after `psel`, but timeline never shows `penable=1` before the failure evidence.

This is a fact cross-check, not a full natural-language spec verifier.

Local Pattern Cache

LazyUVM does not upload project data. By default, it only prints analysis results. If you explicitly add --learn-cache, it stores a small local pattern entry under .lazyuvm_cache/patterns.json.

lazyuvm --analyze-log examples/timing_trace.log --spec examples/spec.txt --learn-cache --no-ai
lazyuvm --analyze-coverage examples/coverage_report.txt --learn-cache --no-ai
lazyuvm --cache-report

After patterns are learned, use --use-cache to compare the current log or coverage report with the local project memory:

lazyuvm --analyze-log examples/timing_trace.log --spec examples/spec.txt --use-cache --no-ai
lazyuvm --analyze-coverage examples/coverage_report.txt --use-cache --no-ai

For a shareable Markdown debug report, use pattern-aware triage:

lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --no-ai
lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --ai

The first command is fully rule-based. The second command adds a local Ollama summary when a model is available. In both cases, LazyUVM uses extracted log facts and local pattern-pack matches as evidence; pattern matches are prior debugging memory, not proof.

After a human confirms the issue, close the debug-to-pack loop in one command:

lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --learn-reviewed --note "confirmed APB setup/access timeout" --no-ai
lazyuvm pack show b5064cf

--learn-reviewed stores the current pattern and marks it reviewed immediately. Use it only after someone has checked the evidence.

The cache keeps normalized fingerprints, categories, repeated-hit counts, signal names found in timelines, and short rule-based hints. Cache matching uses local fingerprints plus category, signal, and hint-token overlap. It is meant to become a private project memory, not hidden telemetry.

Use a custom cache folder when you want to keep experiments separate:

lazyuvm --analyze-log examples/timing_trace.log --learn-cache --cache-dir /tmp/lazyuvm_cache --no-ai
lazyuvm --analyze-log examples/timing_trace.log --use-cache --cache-dir /tmp/lazyuvm_cache --no-ai

For team sharing without a central server, export and import the cache as a plain JSON file:

lazyuvm --cache-export lazyuvm_patterns.json
lazyuvm --cache-import lazyuvm_patterns.json
lazyuvm --cache-report

Import merges by fingerprint. Re-importing the same file updates matching entries instead of duplicating them, so teams can pass around a reviewed pattern pack in source control, chat, or an internal artifact store.

For a reviewed team pattern pack, mark only trusted entries before exporting:

lazyuvm --cache-report
lazyuvm --cache-review b5064cf --review-note "APB setup/access timeout seen in smoke regressions"
lazyuvm --cache-export-reviewed lazyuvm_reviewed_patterns.json
lazyuvm --cache-import lazyuvm_reviewed_patterns.json

The shorter project workflow is preferred once lazyuvm.toml exists:

lazyuvm pack report
lazyuvm pack search paddr
lazyuvm pack show b5064cf
lazyuvm pack review b5064cf --note "APB setup/access timeout seen in smoke regressions"
lazyuvm pack export lazyuvm_reviewed_patterns.json
lazyuvm pack import lazyuvm_reviewed_patterns.json
lazyuvm pack validate

pack review, pack unreview, --cache-review, and --cache-unreview accept unique fingerprint prefixes, so you do not need to type the full hash.

For a self-hosted team registry, publish reviewed packs into a shared folder:

lazyuvm --registry-dir /shared/lazyuvm_registry --registry-publish apb_smoke
lazyuvm --registry-dir /shared/lazyuvm_registry --registry-list
lazyuvm --registry-dir /shared/lazyuvm_registry --registry-pull apb_smoke

With lazyuvm.toml, use the product commands:

lazyuvm pack publish apb_smoke
lazyuvm pack list
lazyuvm pack pull apb_smoke
lazyuvm pack doctor --strict

The registry is just files:

lazyuvm_registry.json
packs/apb_smoke.json

That makes it usable with an internal Git repo, shared drive, artifact store, or any company-controlled file server. No external service is required.

As the cache grows, inspect and prune it:

lazyuvm --cache-stats
lazyuvm --cache-prune 100
lazyuvm --cache-stats

Pruning keeps the highest-count and most recently seen entries first. Use export before pruning if you want a backup:

lazyuvm --cache-export lazyuvm_patterns_backup.json
lazyuvm --cache-prune 100

License

LazyUVM is released under GPLv3. Commercial licensing can be considered separately for companies that need different terms.

This is not legal advice; talk to a lawyer before using any open-source license strategy commercially.