BTF B39 - $test$plusargs(), $value$plusargs()

From: Adam Krolnik (adamk@cyrix.com)
Date: Mon Jun 14 1999 - 10:25:40 PDT

Proposal addition:

It was noted that the more fundamental (and existing) system function
$test$plusargs() is not part of the standard. This proposal will
define both of these system functions for consideration in the standard.

Add to section 16,

Command line input [16.11]
$test$plusargs
$value$plusargs

<p>Add sections:

16.11 "Command line input"

An alternative to reading a file to obtain information for
use in the simulation is specifying information with the
command to invoke the simulator. This information is in
the form of a optional argument provided to the simulation.
These arguments are visually distinguished from other
simulator arguments by the starting with the plus ('+') character.
These arguments, referred to below as plusargs, are accessible
through the following system functions.

16.11.1 $test$plusargs (string)

This system function searches the list of plusargs for the provided
string. The plusargs present on the command line are searched in
the order provided. If one matches all characters in the provided
string, a result of 1'b1 is returned. If no plusarg from the command
line matches the string provided, the result of 1'b0 is returned.

Example:

Run simulator with command:

% <simulator> +HELLO

Verilog code

initial begin
  if ($test$plusargs("HELLO")) $display("Hello argument found.")
  if ($test$plusargs("HE")) $display("The user wants male outputs.");
  if ($test$plusargs("H")) $display("Argument starting with H found.");
  if ($test$plusargs("HELLO_HERE")) $display("Long argument.");
  if ($test$plusargs("HI")) $display("Simple greeting.");
end

This would produce the following output:

Hello argument found.
The user wants male outputs.
Argument starting with H found.

<p><p>16.11.2 $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
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):

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

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.

Examples:

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

<p>// 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[255:0]))
  begin
  $display("Running test %0s.", testname);
  startTest();
  end
  
// Get frequency from command line; set default if not specified.
if (!$value$plusargs("FREQ=%0F", frequency[63:0]))
  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'
   

<p><p> Adam Krolnik
    Verification Engineer
    Cyrix - NSC.
    Richardson TX. 75085

This archive was generated by hypermail 2.1.4 : Mon Jul 08 2002 - 12:53:27 PDT and
sponsored by Boyd Technology, Inc.