lazyuvm 0.7.4

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.

The same reviewed lazyuvm.toml knowledge can feed UVM starters, cocotb starters, firmware-facing C headers, source traceability, pack compatibility checks, and CI evidence. UVM is one export target, not the whole product.

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 Boundary

LazyUVM is a local-first Git-native verification knowledge layer.

LazyUVM is not a simulator.
LazyUVM is not a vManager replacement.
LazyUVM is not sign-off verification.

It is the local layer for project bring-up, reviewed protocol/register/behavior knowledge, accepted waivers, pattern reuse, manifests, and CI-readable evidence.

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/cocotb artifacts, emit tool commands, list export targets, and run smoke checks.	check, uvm, cocotb, tools emit, tools targets, 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, snapshot, and export facts-only AI/reviewer context from the local verification knowledge that a team has reviewed.	know query, know context, 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
  -> UVM/cocotb starters + C headers + traceability + manifests + CI gate reports

Local AI Over Facts

LazyUVM does not ask AI to sign off RTL. It first turns local project state into reviewable facts, then optionally asks local Ollama to explain those facts:

lazyuvm gate --update-manifest --json-out LazyUVM_Gate.json
lazyuvm know context "coverage closure" --gate-json LazyUVM_Gate.json --out LazyUVM_AI_Context.json
lazyuvm know context-verify LazyUVM_AI_Context.json
lazyuvm know bundle --context-json LazyUVM_AI_Context.json --out-dir LazyUVM_AI_Review
lazyuvm know digest --context-json LazyUVM_AI_Context.json --out LazyUVM_AI_Digest.md
lazyuvm know checklist --context-json LazyUVM_AI_Context.json --out LazyUVM_AI_Checklist.md
lazyuvm know prompt --context-json LazyUVM_AI_Context.json --out LazyUVM_AI_Prompt.txt
lazyuvm know explain "coverage closure" --context-json LazyUVM_AI_Context.json --json --out LazyUVM_Knowledge_Explain.json
lazyuvm know explain "coverage closure" --gate-json LazyUVM_Gate.json --json --out LazyUVM_Knowledge_Explain.json
lazyuvm know explain "coverage closure" --gate-json LazyUVM_Gate.json --ai --out LazyUVM_Knowledge_Explain.md
lazyuvm know guard --context-json LazyUVM_AI_Context.json --ai-output LazyUVM_Knowledge_Explain.md

know context writes a lazyuvm.ai_context.v1 JSON payload with the same facts-only boundary used by know explain: gate status, pack reuse state, spec trace, coverage trace, waiver doctor state, behavior plan cards, matching knowledge items, and an explicit AI contract. know context-verify checks that saved contract before it feeds downstream tools. know checklist --context-json turns the same artifact into a human review checklist, know digest turns it into a compact PR summary, know prompt renders a safe local-AI prompt, and know bundle --context-json writes the context, verification report, digest, checklist, and prompt into one review directory. know explain --context-json can reuse the same context in CI or local review. AI output is a local reading aid, not a reviewed fact or root-cause decision; know guard can scan AI drafts for obvious contract violations before sharing them. For the copy/pasteable v0.6 review loop, run lazyuvm demo ai-review or read docs/ai_review_workflow.md. For security review of optional local AI, see docs/local_ai_security.md.

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 regs --c-header --out regs.h
   lazyuvm cocotb --out-dir generated_cocotb
   lazyuvm spec --cocotb-plan --out LazyUVM_cocotb_plan.md
   lazyuvm spec --cocotb-plan --json --out LazyUVM_cocotb_plan.json
   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 --cocotb
   

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

   lazyuvm know query "apb timeout"
   lazyuvm know context "coverage closure" --out LazyUVM_AI_Context.json
   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.

Documentation Map

The README is the product overview and first workflow. Longer guides live in docs/README.md.

Use one of these paths:

Path	Best first command	Longer guide
First project / team governance	lazyuvm demo governance	docs/team_governance_demo.md
CI warning or failed PR	lazyuvm demo next-steps	docs/pr_workflow_cookbook.md
Export UVM, cocotb, C headers, and CI evidence	lazyuvm demo export-governance	docs/export_governance_demo.md
Local pack reuse	lazyuvm demo pack-reuse	docs/pack_reuse_workflow.md
Facts-only local AI review	lazyuvm demo ai-review	docs/ai_review_workflow.md

The important adoption rule is to start small: commit lazyuvm.toml, run the gate locally, then add governance, pack reuse, and local AI review only when the team needs them.

PR Dashboard

The v0.1.9 development cycle makes the pull-request first screen shorter. A gate report now starts with a compact dashboard before the full reviewer-action table and step evidence:

## PR Dashboard

- Gate: `PASS`
- Top action: blocker - Review newly introduced blocking waiver issues. (`coverage_report.L999`)
- Reproduce / repair: `lazyuvm baseline diff`
- Waiver delta: +2 new, +1 blocking, +1 expiring soon
- Coverage closure: 3 action(s), 0 accepted waiver(s)
- Behavior action: 1 action(s), first `apb_timer.apb_access_completes`

Generated init-ci workflows lift this section into the GitHub Actions summary before the longer report. The intent is simple: reviewers should see the gate state, first action, waiver movement, coverage-closure debt, and first behavior plan link before scrolling through artifacts.

Behavior-Driven Plans

The v0.1.7 development cycle connects reviewed behavior specs to the plans a reviewer needs next: RAL interactions, directed sequences, scoreboard expectations, and coverage closure stimulus. Try the runnable governance demo:

lazyuvm spec --config examples/governance_demo.toml --sequence-plan --out LazyUVM_Sequence_Plan.md
lazyuvm regs --config examples/governance_demo.toml --ral-plan --out LazyUVM_RAL_Plan.md
lazyuvm spec --config examples/governance_demo.toml --coverage-plan --out LazyUVM_Coverage_Plan.md
lazyuvm spec --config examples/governance_demo.toml --scoreboard-plan --out LazyUVM_Scoreboard_Plan.md

Each behavior plan card shows linked register/field context, related coverage holes, accepted waivers, review actions, and sequence-level closure ideas for unwaived holes. The plan remains review-first Markdown; generated starter code comes after the plan is clear.

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. For the current v0.1.7 development direction, see docs/behavior_driven_plans.md. For the current v0.1.8 development direction, see docs/local_ai_fact_explain.md. For the current v0.1.9 development direction, see docs/reviewer_action_workflow.md. For the v0.2.x adoption and governance direction, see docs/legacy_cli_cleanup.md, docs/v0.3_readiness.md, and docs/releases/v0.2.9.md. For the v0.4 export-target direction, see docs/export_targets.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 for compatibility, 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.

Migrating From Old Direct Flags

If an older script starts with bare flags such as lazyuvm --filelist ..., lazyuvm --analyze-log ..., or lazyuvm --cache-review ..., it still works for now and prints a warning. For repeatable project work, migrate it to the project-command surface:

# Old one-off shape
lazyuvm --filelist files.f --checks

# Preferred v0.2.x project shape
lazyuvm init --filelist files.f --top your_top
lazyuvm check
lazyuvm gate --update-manifest

Use lazyuvm legacy ... only when you intentionally need the old one-off scanner behavior. For concrete before/after examples covering checks, log triage, pattern packs, coverage closure, and CI, see docs/legacy_cli_cleanup.md. You can also print the short terminal version:

lazyuvm demo migration

Release Status

Current repository version: 0.7.4

Latest tagged release: 0.7.4

Latest PyPI release: verify with python3 -m pip index versions lazyuvm

• See CHANGELOG.md for the release history.
• See RELEASE_CHECKLIST.md before cutting a tag.
• See docs/releases/v0.7.4.md for the latest tagged 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 --cocotb

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. Use --run-cocotb-smoke only after the generated cocotb starter has been reviewed against the project's simulator assumptions.

The sections below prefer project commands. Legacy direct-flag examples are called out explicitly and can be run with lazyuvm legacy ... when you need a one-off scan outside a configured project.

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
c_header = "regs.h"
c_header_prefix = "LAZYUVM"

[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 "coverage closure" --gate-json LazyUVM_Gate.json --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, bundles, coverage trace, waivers, behavior plan cards, and optionally a lazyuvm.gate.v1 JSON artifact; 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
lazyuvm pack --config examples/apb_timer_cocotb/lazyuvm.toml doctor --dependencies --lockfile examples/apb_timer_cocotb/evidence/LazyUVM_Pack_Lock.json --strict

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 init --filelist examples/files.f --top apb_timer
lazyuvm check
lazyuvm report

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. lazyuvm report 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 tools emit verilator
lazyuvm tools emit vcs
lazyuvm tools emit questa

Example output:

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

The project command reads lazyuvm.toml, so the filelist, include dirs, defines, and default top/module stay in one reviewable place. When you pass --module, LazyUVM treats it as the top/module hint:

lazyuvm tools emit verilator --module chip_top
lazyuvm tools emit vcs --module chip_top
lazyuvm tools emit questa --module chip_top

For a one-off command outside a configured project, the legacy compatibility surface still exists:

lazyuvm legacy --filelist examples/files.f --emit-tool verilator

Regression Runner

For a small local regression:

lazyuvm 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 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 init --filelist examples/files.f --top apb_timer --regress-file examples/regress.yaml
lazyuvm regress --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 configured project, prefer the knowledge workflow. Put the coverage report path under [reports].coverage_report, then run:

lazyuvm know coverage --out LazyUVM_Coverage_Trace.md
lazyuvm gate --coverage-report examples/coverage_report.txt --json-out LazyUVM_Gate.json

For a one-off text coverage report outside a configured project, use the legacy compatibility surface:

lazyuvm legacy --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 legacy --analyze-coverage examples/coverage_report.txt --coverage-threshold 80 --no-ai

To write the analysis to a file:

lazyuvm legacy --analyze-coverage examples/coverage_report.txt --coverage-md LazyUVM_Coverage.md --no-ai
lazyuvm legacy --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 legacy --analyze-coverage examples/coverage_report.txt --coverage-stimulus-dir generated_stimulus --module apb_timer --no-ai
lazyuvm legacy --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 configured projects, lazyuvm check prints hierarchy and top-candidate context as part of the local health check:

lazyuvm check

For a one-off folder scan, use the legacy compatibility surface:

lazyuvm legacy --hierarchy examples
lazyuvm legacy --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 configured projects, lazyuvm check includes lightweight width solving when it can infer enough local context. For a one-off parameterized design:

lazyuvm legacy --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 check

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 report

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 report --no-lint

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 triage --log examples/sim_error.log --no-ai
lazyuvm triage --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 triage --log examples/sim_error.log --ai --ollama-model llama3.2:1b

Spec-Aware Log Cross-Check

For a small spec/log comparison:

lazyuvm triage --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 triage --log examples/timing_trace.log --spec examples/spec.txt --learn-cache --no-ai
lazyuvm legacy --analyze-coverage examples/coverage_report.txt --learn-cache --no-ai
lazyuvm pack report

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

lazyuvm triage --log examples/timing_trace.log --spec examples/spec.txt --use-pack --no-ai
lazyuvm legacy --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 triage --log examples/timing_trace.log --learn-cache --cache-dir /tmp/lazyuvm_cache --no-ai
lazyuvm triage --log examples/timing_trace.log --use-pack --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 pack export lazyuvm_patterns.json
lazyuvm pack import lazyuvm_patterns.json
lazyuvm pack 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 pack report
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

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 and pack 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 pack --registry-dir /shared/lazyuvm_registry publish apb_smoke
lazyuvm pack --registry-dir /shared/lazyuvm_registry list
lazyuvm pack --registry-dir /shared/lazyuvm_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 pack stats
lazyuvm pack prune 100
lazyuvm pack stats

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

lazyuvm pack export lazyuvm_patterns_backup.json
lazyuvm pack 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.