Custom Plusargs in Tests: Map CLI Knobs Into cfg Objects

When custom plusargs are justified

Custom flags are appropriate for top-level scenario overrides — transaction counts, protocol modes, feature toggles. Deeply structured config belongs in cfg objects, not dozens of CLI flags.

[TEST][ENV] good custom plusarg targets

+SEQ_COUNT=2000        -> cfg.seq_count
+MODE=strict            -> cfg.protocol_mode enum
+DISABLE_SB=1           -> cfg.enable_scoreboard
+BURST_MAX=16           -> cfg.max_burst_len

avoid:
  +AGENT0_DRV_DELAY=3   -> too granular; use cfg object fields

function void parse_custom_knobs(uvm_cmdline_processor clp);
  string vals[$];

  if (clp.get_arg_values("+SEQ_COUNT=", vals) > 0) begin
    int n = vals[0].atoi();
    if (n <= 0) `uvm_fatal("CLI", $sformatf("bad SEQ_COUNT=%s", vals[0]))
    cfg.seq_count = n;
  end

  if (clp.get_arg_values("+MODE=", vals) > 0) begin
    if (!cfg.set_mode_from_string(vals[0]))
      `uvm_fatal("CLI", $sformatf("unknown MODE=%s", vals[0]))
  end
endfunction

Key takeaways

• Custom plusargs should map to typed cfg fields with validation.

• Fail fast on unknown modes or out-of-range numeric values.

• Document every supported flag in a registry shared with CI scripts.

Common pitfalls

• Accepting silent defaults when an unknown +MODE= is provided.

• Using plusargs for hierarchical per-agent knobs better suited to cfg.

• Inventing new flag names per author instead of a team registry.

Flag registry and child-test policy

Child tests adjust scenario intent through cfg and hooks — not by adding private plusarg parsers.

Registry template

[TEST] plusarg registry (excerpt)

| Flag          | Type    | Default | Maps to            |
|---------------|---------|---------|--------------------|
| +SEQ_COUNT=   | int>0   | 100     | cfg.seq_count      |
| +MODE=        | enum    | normal  | cfg.protocol_mode  |
| +ERR_INJECT   | bool    | 0       | cfg.inject_errors  |
| +DISABLE_SB   | bool    | 0       | cfg.enable_sb=0    |

• Review new flags in PR checklist — one owner for the registry.

• Version the registry alongside testlist changes.

• Gate experimental flags behind +EXPERIMENTAL to avoid nightly surprises.

Boolean vs value flags

// Presence flag
if (clp.get_arg_matches("+ERR_INJECT", vals))
  cfg.inject_errors = 1;

// Explicit disable (overrides default enable)
if (clp.get_arg_values("+DISABLE_SB=", vals) > 0)
  cfg.enable_scoreboard = (vals[0] == "0") ? 0 : 1;

simv +UVM_TESTNAME=error_injection_test +ERR_INJECT +SEQ_COUNT=50
simv +UVM_TESTNAME=smoke_sanity_test +DISABLE_SB=1

Common pitfalls

• Boolean flags with ambiguous semantics (+FOO=0 vs absent).

• Child tests overriding cfg after plusarg parse without calling super.

• Registry drift — scripts use flags removed from parser months ago.