Plusargs & Test Selection Hub: Runtime Control Without Recompile

Overview

Plusargs are the runtime API between regression scripts and your UVM testbench. A single compiled simv image can run hundreds of scenarios when test selection and knobs arrive from the command line.

In env-test workflows, plusargs serve three roles: select the test class , tune scenario knobs into cfg objects , and connect CI matrices to UVM without source edits .

Sub-lessons in this topic

1. uvm-testname-selection - run_test() and +UVM_TESTNAME factory selection.

2. cmdline-processor-test - uvm_cmdline_processor usage from base_test.

3. custom-plusargs-test - project knobs mapped into typed cfg fields.

4. regression-matrix-env - shell/CI expansion across tests, seeds, and modes.

5. build-phase-plusarg-read - parse timing before env consumes cfg.

6. plusargs-debug-patterns - deterministic triage for CLI mismatches.

[TEST][UVM][ENV] plusarg control plane

shell / CI
  simv +UVM_TESTNAME=<test> +KNOB=val +UVM_VERBOSITY=...
           │
           ▼
top.sv
  run_test()  ──► factory builds selected uvm_test
           │
           ▼
base_test::build_phase
  uvm_cmdline_processor::get_inst()
    -> parse built-ins + custom args
    -> map into env_cfg
    -> config_db::set("env*", "cfg", cfg)
           │
           ▼
env / agents consume cfg (no scattered $value$plusargs)

# One binary, many scenarios
simv +UVM_TESTNAME=smoke_sanity_test +ntb_random_seed=42
simv +UVM_TESTNAME=burst_traffic_test +SEQ_COUNT=2000 +ntb_random_seed=42
simv +UVM_TESTNAME=error_injection_test +ERR_INJECT +UVM_VERBOSITY=UVM_MEDIUM

Key takeaways

• Plusargs decouple regression orchestration from compile-time test selection.

• Parse once in base_test and publish typed cfg — not ad-hoc reads everywhere.

• Log resolved CLI values every run for replayable triage.

Common pitfalls

• Hardcoding run_test("fixed_test") in top.sv for every build.

• Scattering $value$plusargs across env, agents, and sequences.

• Silent defaults when arg names are misspelled or never validated.

Env-test plusarg contract

Treat the command line as a public interface. Tests own parsing; env and agents consume cfg objects only.

Ownership boundaries

[TEST] owns:
  - run_test() / +UVM_TESTNAME selection
  - uvm_cmdline_processor pass in build_phase
  - mapping CLI -> env_cfg fields
  - logging resolved knob table

[ENV] owns:
  - config_db get of typed cfg
  - validation of required cfg fields
  - no direct plusarg reads

• Keep custom arg names in one registry document shared with CI.

• Prefer built-in UVM plusargs before inventing project flags.

• Every matrix cell should be replayable from logged test + seed + args.

virtual function void configure_from_plusargs();
  uvm_cmdline_processor clp = uvm_cmdline_processor::get_inst();
  string vals[$];
  if (clp.get_arg_values("+UVM_TESTNAME=", vals) > 0)
    `uvm_info("CLI", $sformatf("test=%s", vals[0]), UVM_LOW)
  parse_custom_knobs(clp);
  log_resolved_cfg();
endfunction

[TEST][UVM] release gate

- top calls run_test() without hardcoded name
- base_test parses plusargs before env creation
- cfg object holds all runtime knobs
- regression script documents every supported flag