Master the Power of Plusargs in SystemVerilog: Must-Know Tips

A good testbench should not need a rebuild every time you want a different test or a higher debug level. Plusargs give you that control from the command line. The compiled image stays the same, and you steer its behaviour with switches when you run it.

A simple way to picture it

Think of a coffee machine with buttons on the front. The machine is built once, but each morning you press different buttons for a small or large cup, extra shot, or decaf. You do not rebuild the machine to get a different drink; you just press the buttons at the time you use it. Plusargs are those buttons: the compiled testbench is the machine, and the switches you type when you run it are the button presses.

The two system functions

SystemVerilog gives you two functions to read plusargs. Both search the list of run time arguments and return a one bit result you can test in an if.

If $value$plusargs does not find a match, it returns 0 and leaves the variable unchanged, so always give the variable a sensible default first.

Example 1: turn a mode on with $test$plusargs

Use $test$plusargs for on or off switches. Here a debug section runs only when you pass the flag on the command line.

module test_flag;
  initial begin
    if ($test$plusargs("DEBUG"))
      $display("DEBUG mode is ON");
    else
      $display("DEBUG mode is OFF");
  end
endmodule

// Run with:  +DEBUG   -> prints "DEBUG mode is ON"
// Run without it       -> prints "DEBUG mode is OFF"

Example 2: read a value with $value$plusargs

Use $value$plusargs to read a value into a variable. The format specifier says what type to read: %s for a string, %d for a decimal number, and so on. Set a default first so a missing switch is safe.

module read_value;
  initial begin
    string test_name = "smoke_test";   // default
    int    num_txn   = 10;              // default

    void'($value$plusargs("TEST=%s", test_name));
    void'($value$plusargs("NUM=%d", num_txn));

    $display("Running test = %s with %0d transactions", test_name, num_txn);
  end
endmodule

// Run with:  +TEST=axi_test +NUM=50
// prints:    Running test = axi_test with 50 transactions

Example 3: a real seed and config pattern

A common real use is to control the random seed and pick a config from the command line, so one build can run many different runs in regression. Here the code reads a seed and a mode, and falls back to defaults when a switch is missing.

module run_control;
  initial begin
    int    seed = 1;
    string mode = "normal";

    if (!$value$plusargs("SEED=%d", seed))
      $display("No SEED given, using default %0d", seed);
    void'($value$plusargs("MODE=%s", mode));

    $display("seed=%0d mode=%s", seed, mode);
    // use seed to control randomization, mode to pick a config
  end
endmodule

// Run with:  +SEED=42 +MODE=stress
// prints:    seed=42 mode=stress

Expected output, in plain words

In example 1 the DEBUG line prints ON only when you add the switch. In example 2 the run prints the test name and count you passed, or the defaults if you passed nothing. In example 3 a missing SEED prints the fallback note and keeps the default, while a given SEED and MODE are echoed back.

Note: these outputs describe what the code is written to produce, based on a read of the IEEE 1800 LRM. The exact switch syntax can vary slightly by simulator, so check your tool docs and run it yourself to confirm.

When to use plusargs

• You want to pick a test, seed, or config at run time without recompiling.
• You want a debug or logging mode you can turn on only when needed.
• You run many variations in a regression from one compiled image.
• You want quick manual control while bringing up a new block.

Common mistakes to avoid

• No default value: if $value$plusargs does not match, your variable keeps its old value, so set a sensible default first.
• Wrong format specifier: reading a number with %s or a string with %d gives surprising results. Match the specifier to the type.
• Ignoring the return value: the return flag tells you whether the switch was present. Use it when the difference matters.
• Expecting compile time effect: plusargs are read at run time, so they cannot add or remove code. For that you need a compile macro.

Plusargs vs compile macros

Plusargs are read while the simulation runs, so the whole design is compiled and you change behaviour at run time. A compile macro such as an ifdef decides what code is even built, so changing it needs a recompile. We compare these two in detail in our guide on ifdef vs plusargs.

For more run time control patterns, see our SystemVerilog tutorials and interview questions.

Frequently asked questions

Share this post: on Twitter on Facebook