Extracting Values of Plusargs inside a simulation

This article as well as many others appears in Chris' website.

1. Introduction

$value$plusargs (string, variable)

This system function searches the list of plusargs (like the $test$plusargs system function) for a user specified string. If a string is found, the remainder of the string is converted to the type specified in the user string and the resulting value stored in the variable provided. If a string is found the function returns the value 1'b1. If no string is found matching, the function returns the value 1'b0 and the variable provided is not modified.

The user string must be of the form: "'plusarg_string''format_string'". The plusarg string is a name followed by either = or + . The format strings are the same as the $display system tasks. These are the only valid ones (upper and lower case as well as a leading 0 forms are valid):

%b - binary conversion
%d - decimal conversion
%e - real exponential conversion
%f - real decimal conversion
%g - real decimal or exponential conversion
%h - hexadecimal conversion
%o - octal conversion
%s - string (no conversion)
%x - (undergound equivalent for %h)

The first string, from the list of plusargs provided to the simuator, that matches the plusarg_string portion of the string specified by the user will be the plusarg string available for conversion. The remainder string of the matching plusarg (the remainder is the part of the plusarg string after the portion that matches the users plusarg_string) will be converted from a string into the format indicated by the format string and stored in the variable provided.

If the size of the variable is larger than the value after conversion, the value stored is zero padded to the width of the variable. If the variable can not contain the value after conversion, the value will be truncated. If the value is negative, the value shall be considered larger than the variable provided. If characters exist in the string available for conversion that are illegal for the specified conversion, the register should be written  with the value 'bx.

2. Examples:

<simulator> +FINISH=10000 +TESTNAME=this_test +FREQ=5.6666 +FREQUENCY

// Get clock to terminate simulation if specified.

if ($value$plusargs("FINISH=%d", stop_clock)) begin
     repeat (stop_clock) @(posedge clk);
     $finish;
end

// Get testname from plusarg.

if ($value$plusargs("TESTNAME=%s", testname)) begin
    $display("Running test %0s.", testname);
  startTest();
end

// Get frequency from command line; set default if not specified.

if (!$value$plusargs("FREQ=%0F", frequency))
   frequency = 8.33333; // 166MHz;

forever begin
   #frequency clk = 0;
   #frequency clk = 1;
end

This code would have the following effects:

1. The variable 'stop_clock' obtains the value 10000.
2. The variable 'testname' obtains the value 'this_test'.
3. The variable 'frequency' obtains the value '5.6666'; note the final plusarg +FREQUENCY does not affect the value of the variable 'frequency'.

3. Files

The main PLI application is in file value.c. A .tab file for VCS environment will contain the following line.

	$value$plusargs     check=value_check call=value_call size=32 acc=rw:%TASK
	

The corresponding veriuser.c for Verilog-XL is here.

4. Using $value$plusargs with VCS

4.1 Passing integers

The Verilog code:

module test;
integer i, r;

initial begin
  r = $value$plusarg("myint=%d", i);
  $display("Value is %0d", i);
end

endmodule

invoked from Unix with:

> simv +myint=22

will print:

Value is 22

4.2 Passing strings

The Verilog code:

module test;
reg [1000:0] string;

initial begin
   $value$plusarg("mystr=%s", string);
   $display("String is %0s", string);
end

endmodule

invoked from Unix with:

> simv +mystr=cbs

will print:

String is cbs

4.3 Passing filenames

To pass a file name from the command line into a model, use a plus argument.

The Verilog code:

module test;
reg [100:0] s1;

initial begin
   $value$plusarg("MEM=%s", s1);
   $readmemh (s1, memory);
end

endmodule

invoked from Unix with:

> simv +MEM=pgm.txt test.v

will read the file "pgm.txt" . At run time you can now specify a different name, such as +MEM=new.txt This can also be used with SDF file names.

4.4 Changing values at run-time

If you compile a model in VCS with a plus argument, it is "burned" into the simv as a default and does not have to be given at run time.

> vcs -R model.v +myint=22

will print "Value is 22". Running the executable with no switch will print the same thing:

> simv

Value is 22

Running with a different switch will cause the new value to print:

> simv +myint=44

Value is 44

4.5 Compilation

To compile this code with VCS, use:

vcs value.c -P value.tab -CFLAGS "-I${VCS_HOME}/`vcs platform`/lib" mymodel.v

4.6 Limitations

VCS will give the following compile message which can be ignored:

Unknown compile time plus argument ignored: 'myint=22'

Use +plusarg_ignore to turn off this message. If you want to use the plusargs from the compile step during simulations, use +plusarg_save.

These plus arguments can not be in a -f file with VCS 4.0.x and earlier.