Command-Line Control with uvm_cmdline_processor

Overview

Production regressions are controlled at runtime, not by recompiling for each scenario. UVM command-line capabilities are the mechanism that makes this practical: selecting tests, tuning verbosity, injecting config_db values, and reading custom project knobs.

This topic organizes command-line control into five layers: built-ins first (where possible), then targeted config injection, then safe custom parsing, then matrix automation, and finally lifecycle timing rules so parsing occurs before components consume values.

Treat CLI values as part of your verification interface contract : typed, validated, logged, and reproducible. Undisciplined plusarg usage causes silent defaults, non-replayable failures, and noisy triage.

Lessons in this topic

1. Built-in UVM Plusargs — using +UVM_TESTNAME, +UVM_VERBOSITY, and related controls correctly.

2. uvm_set_config from CLI — injecting config_db values without source edits.

3. Custom Plusargs — robust parsing, validation, and fallbacks for project-specific knobs.

4. Regression Matrix — systematic expansion across tests, seeds, modes, and knobs.

5. build_phase Parsing — ensuring command-line values are parsed early and consumed safely.

Runtime configuration dataflow

Legend: [UVM] [ADV] [REG]

  shell command
    simv +UVM_TESTNAME=foo +NUM_TXN=500 +MODE=strict ...
                       │
                       ▼
  [UVM] uvm_cmdline_processor singleton
                       │
              parse + validate + defaults
                       │
                       ▼
  [ADV] config surface
    - built-in controls (+UVM_*)
    - config_db injection (+uvm_set_config_*)
    - custom args (+NUM_TXN, +BURST_MAX)
                       │
                       ▼
  [REG] regression observability
    - log resolved values
    - tie values to seed/signature
    - replay exact failing cell

[ADV] anti-pattern warning

  Bad: recompile for every knob change
    -> slow matrix expansion, stale binaries, low reproducibility

  Better: one compiled image + runtime knobs
    -> fast sweep, deterministic replay, CI-friendly workflows

Key takeaways

• Runtime CLI control is foundational for scalable UVM regressions.

• Prefer built-in UVM plusargs before inventing custom knobs.

• Every parsed value should be validated, logged, and replayable.

• Parsing timing matters: resolve knobs before build/connect consumers run.

Common pitfalls

• Reading custom plusargs late and missing configuration windows.

• Silent defaulting when arg names are misspelled.

• Unlogged runtime knobs that make failures hard to replay.