SystemVerilog Command Line Arguments

Every now and then you come across the need to avoid testbench recompilation, and instead be able to accept values from the command line just like any scripting language like bash or perl would do. In SystemVerilog, this information is provided to the simulation as an optional argument always starting with the + character. These arguments passed in from the command line are accessible in SV code via the following system functions called as plusargs.

Syntax

	$test$plusargs (user_string)
	
	$value$plusargs (user_string, variable)

$test$plusargs

The function $test$plusargs is typically used when a value for the argument is not required. It searches the list of plusargs for a user specified string. A variable can also be used to specify the string, and any null character will be ignored. If the prefix of one of the supplied plusargs matches all characters in the provided string, the function will return a non-zero integer, and otherwise zero.

Example

module tb;
  initial begin
    if ($test$plusargs ("STANDBY"))
      $display ("STANDBY argument is found ...");
    
    if ($test$plusargs ("Standby"))
      $display ("Standby argument is also found ...");
    
    if ($test$plusargs ("STAND"))
      $display ("STAND substring is found ...");
    
    if ($test$plusargs ("S"))
      $display ("Some string starting with S found ...");
    
    if ($test$plusargs ("T"))
      $display ("Some string containing T found ...");
    
    if ($test$plusargs ("STAND_AT_EASE"))
      $display ("Can't stand any longer ...");
    
    if ($test$plusargs ("SUNSHADE"))
      $display ("It's too hot today ...");
    
    if ($test$plusargs ("WINTER"))
      $display ("No match.. ");
  end
endmodule

When the code shown above is compiled and simulated with a run-time argument +STANDBY, where STANDBY is the string plusarg provided to the simulation tool, we get an output like shown below. Notice that the plusarg is case-sensitive, and matches both "S" and "STAND" even though the string provided is "STANDBY".

ncsim> run
STANDBY argument is found ...
STAND substring is found ...
Some string starting with S found ...
ncsim: *W,RNQUIE: Simulation is complete.

$value$plusargs

The $value$plusargs system function also searches the list of plusargs like $test$plusargs, but it has the capability to get a value for a specified user string. If the prefix of one of the supplied plusargs matches all characters in the given user string, the function will return a non-zero value and store the resulting value in the variable provided. If the user string is not found, then the function returns a non-zero value and the variable will not be modified.

The user_string shall be of the form "plusarg_string format_string" where format strings are the same as $display tasks. These format identifiers are used to convert the value provided via command line to the given format and store in a variable.

Example

// Note FS : Format Specifier

module tb;
  initial begin
  	string  	var1, var2;
    bit [31:0] 	data;

    if ($value$plusargs ("STRING=%s", var1))
      $display ("STRING with FS has a value %s", var1);
    
    if ($value$plusargs ("NUMBER=%0d", data))
      $display ("NUMBER with %%0d has a value %0d", data);
    
    if ($value$plusargs ("NUMBER=%0h", data))
      $display ("NUMBER with %%0h has a value %0d", data);
    
    if ($value$plusargs ("NUMBER=%s", data))
      $display ("NUMBER with %%s has a value %0d", data);
    
    if ($value$plusargs ("STRING=", var1))
      $display ("STRING without FS has a value %s", var1);
    
    if ($value$plusargs ("+STRING=%s", var1))
      $display ("STRING with + char has a value %s", var1);

`ifdef RUNTIME_ERR    
    if ($value$plusargs ("STRING=%0d", var2))
      $display ("STRING with %%0d has a value %s", var2);
`endif
  end
endmodule

For different input arguments, we'll get different outputs. Also note that there should not be any space between the user string, = and the value in the command-line expression.

"Joey" can be passed with or without double-quotes.

ncsim> run
STRING with FS has a value Joey
STRING without FS has a value Joey
ncsim: *W,RNQUIE: Simulation is complete.

The value 100 is converted according to different format specifiers and stored in the given variable.

ncsim> run
NUMBER with %0d has a value 100
NUMBER with %0h has a value 256
NUMBER with %s has a value 3223600
ncsim: *W,RNQUIE: Simulation is complete.

The = symbol is missing, and hence failed to be recognized.

ncsim> run
ncsim: *W,RNQUIE: Simulation is complete.

The argument value is an empty string, and hence shows up as empty.

ncsim> run
STRING with FS has a value 
STRING without FS has a value
ncsim: *W,RNQUIE: Simulation is complete.

The simulator looks at the first + character to understand that what comes next until the = as the user string.

ncsim> run
STRING with + char has a value Joey
ncsim: *W,RNQUIE: Simulation is complete.

Even a number is parsed as a string by default.

ncsim> run
STRING with FS has a value 1234
STRING without FS has a value 1234
ncsim: *W,RNQUIE: Simulation is complete.

If the user string matches, but the format specifier is wrong for the kind of data that is being passed in as an argument, you'll get a runtime error. For the above example, use +define+RUNTIME_ERR as a compile time argument and +STRING=Joey.

ncsim> run
STRING with FS has a value Joey
STRING without FS has a value Joey
    if ($value$plusargs ("STRING=%0d", var2))
                      |
ncsim: *E,SYSFMT (./testbench.sv,27|22): $value$plusargs --  value found 'Joey' for plusarg 'STRING=' does not match specified format.
STRING with %0d has a value 
ncsim: *W,RNQUIE: Simulation is complete.