The score command is initiated with the following call:

covered [global_options] score -t top_module [options]

The top_module parameter is required for the scoring purposes and represents the top-most module that will be covered. It is important to note that Covered does not need to parse the entire DUT. It only parses that part of the design which will receive coverage results. More on this will be described Section 9.3, “Specifying What to Cover” below.

The following table describes the additional options that can be passed to the score command. Note that it is optional in how you tell Covered where to find the Verilog design files; however, it is not optional to exclude the Verilog files. If no Verilog can be found that contains at least the top instance, Covered will generate an error message to the user specifying that it was unable to find the required Verilog modules.

Covered is not a logic simulator and, therefore, is not required to parse the entire DUT. True simulation is performed by the Verilog simulator used to generate the VCD/LXT2/FST dumpfile. Covered, therefore, is given the ability to parse only the part of the DUT that is to be scored for coverage. Having this ability to ignore parts of the DUT has several advantages in the way of performance. Less memory is necessary for coverage simulation/ calculation. Additionally, less processing is also required which leads to faster turnaround. On the other hand, since Covered ignores the parts of the design not being scored, some information is not automatically extracted by Covered that is required for scoring the specified part of the DUT. The defparam statement is one such statement. More on this is mentioned in the following section.

The following example describes a complete DUT and how to cause Covered to score various parts of the DUT.

Figure 9.1. Hierarchical Tree View of Example DUT

Assume that the following Verilog modules are used to create this tree.

To get coverage for the entire design, the covered command line would be:

covered score -t test -i test (rest of command-line)

Because both the -t and -i options are the same value (the module name is the same as the instance name), only the -t option needs to be specified. If the -i option is not specified, Covered will assume that the instance name of the top module is the same name as the top module itself. Note that the -t option always needs to be specified for the score command.

To get coverage for the instance foo and all modules below it, the covered command line would be:

covered score -t foomod -i test.foo (rest of command-line)

In this case, we do not wish to score the module test (the top-level file for the design) but rather wish to gain coverage information for module foomod and all instantiated modules underneath it. Since foomod is not the top-level design file, the -i option must be specified to tell Covered what the hierarchical scope of the top-level score file is in relation to the entire design. The main reason why this is necessary is so that Covered will be able to locate the dumpfile information for the modules/instances that need to be scored.

To get coverage for only the instance foo (and none of the modules instantiated below it in the hierarchy), Covered command-line would look like the following:

covered score -t foomod -i test.foo -e amod -e bmod

Here we see the use of the -e option, it takes a module name as its value. When a module with the matching name is found in the hierarchy, it and all of its submodules are removed from coverage. You may specify as many -e arguments as necessary to select the appropriate modules to cover.

To get coverage for the instance foo and all modules below it, in addition to the instance bar, you would have to run Covered twice (once for each top instance).

The -vcd vcd_dumpfile, -lxt lxt_dumpfile or -fst fst_dumpfile parameter is simply the name of the VCD/LXT2/FST dumpfile that contains all of the module instances selected by the -t parameter (in combination with the -e option -- see below).

Besides the -e option (scope exclusion), Covered comes equipped with several other means of excluding codes from coverage consideration. The -ea, - ec, -ei and -ef exclusion options cause Covered to not simulate always blocks, continuous assignment blocks, initial blocks and final blocks, respectively, allowing for additional score command performance enhancement opportunities. These options affect all code that is under coverage consideration for the current score command, and cannot be turned on/off on an individual basis.

  module foo;

    // coverage off
    ...
    // coverage on

  endmodule;
          

  module foobar;

    reg b, c, d, e;

    // coverage off

    wire a;

    // coverage off
    assign a = b & c;
    // coverage on

    assign e = ~d;
    // coverage on

  endmodule
          

The defparam statement can override any parameter specified in the DUT from any module in the DUT. Since parameter information is not typically specified in VCD/LXT2/FST dumpfiles, Covered needs to know about all parameter values at score time. Since all defparam statements are ignored by the Covered parser (even those in the DUT being scored), the user must inform Covered of any parameters that need to be overridden. This is accomplished with the -P option to the score command.

The first value in the -P option is the hierarchical reference to the parameter that needs to be overridden. The second value (following the '=' sign) specifies the value to assign the parameter to. This will override any default value assigned to that parameter. The user may not override the same parameter value twice on the command-line. Additionally, if the parameter is already being overridden in the design via an inline parameter override (parameter overrides specified in the '#(...)' part of the module instantiation).

As an example of how to override a parameter value on the score command-line, let's assume that there is a parameter called 'google' in the module called 'amod' used in the example in Section 9.3. The parameter definition in this module looks like the following:

parameter google = 4'hf;

To override this value to a new value of 18, use the following option in the score command:

-P test.foo.a.google=18

In this example, notice that we have not only changed the value of google, but we have also changed the bit-width of google from 4 bits to 32 bits (the size of an integer). This is considered legal behavior by Covered.

It is also possible to specify non-integer values to the parameter override option. Decimal, binary, octal and hexidecimal values may also be specified, using the same syntax as they are specified in Verilog. The following examples would also be other ways to override the value to 18.

  -P test.foo.a.google=5'b10010
  -P test.foo.a.google=4'o22
  -P test.foo.a.google=12'h12
  -P test.foo.a.google='d18
      

In fact, you may specify any value (with the exception of real numbers) to override a parameter, including the following value types: 'x', 'X', 'z', 'Z', '_', '?'. This means that unknowns may be specified in a parameter. Note that this may generate user reported errors if parameters overridden to unknown values are used in mathematical equations or are used to specify the width of wires, regs, etc.

If a defparam statement is encountered in the DUT being scored, a warning message will be output to the user specifying that it has encountered a defparam statement. The defparam statement is ignored by Covered; however, if the parameter that it is overridding is used in the DUT being scored, the results of Covered may differ from actual simulation results. As such, please review all of these warning types to determine if the parameter should be overridden or not. If defparams are not parsed (seen by Covered), no such warning will be output. Please review the DUT for defparams which affect the DUT being scored.

At this time Covered does not have the ability to automatically extract FSM information from the design. As a result, it is up to the user to specify FSM information for Covered to use in scoring FSMs. The ability to automatically extract FSM information is planned to be supported in the future; however, it is always a good idea to allow the user to specify and potentially override Covered's automatic extraction in the case where Covered either misses an FSM or incorrectly determines logic to be an FSM in cases where none exists. The information specified in this section describes how to tell Covered where an FSM exists within the design as of the current development version of Covered.

First, we need to make a few assumptions about the type of FSMs that Covered will be able to handle and, in the future, identify.

There is currently only one way, via the command-line, to specify to Covered where to find FSMs within the design. In the future, the inline Verilog-2001 "$attribute" function will be used to also allow the user to specify to Covered where an FSM is located. Using the command-line method, no changes need to be to source Verilog code for Covered's purposes.

To specify where an FSM exists within the design, the -F option must be specified to Covered's score command. Each -F option specifies one FSM within the design. Multiple -F options to the score command are allowed, allowing more than one FSM to be scored simultaneously. The -F option takes one argument that is subdivided into two or three parts:

-F module=(input_state_expression,)output_state_expression

The module specifies the Verilog module where the FSM state variables exist. The input_state_expression specifies the name of the variable(s) that represent the input state of the state machine. The output_state_expression specifies the name of the variable(s) that represent the output state of the state machine. Most FSMs have one variable as the input state (in most cases a registered version of the output state) such that the input variable is different than the output variable of the state machine. Specifying both variables in the -F option provides the user to more accurately specify to Covered the FSM. In the case that an FSM has the same variable for the input and output state, the user must specify only the output state variable (omitting the input_state_expression and comma character in the argument).

The input and output expression to the -F command can represent any signals, parts of signals, or combinations of signals. Constant values or parameters in the specification of the input/output expression is currently not supported (in fact, there are no future plans to support this behavior unless user-feedback demands it). The following examples show various legal ways to specify input/output expressions. The syntax is limited to what it shown in these examples.

-F foobar=a

Example 1 specifies that the entire vector called "a" should be considered both the input and output state variable.

-F foobar=a[2]

Example 2 specifies that bit 2 of the vector called "a" should be considered both the input and output state variable.

-F foobar=a[3:1]

Example 3 specifies that bits 3:1 of the vector called "a" should be considered both the input and output state variable.

-F foobar={a,b}

Example 4 specifies that vectors "a" and "b" should be concatenated to form the input/output state variable. Only one set of curly brackets may be used to specify a concatenated state expression; however, 2 or more signals may be specified within those brackets.

Any combination of the above four examples can be used to formalate the input state expression or the output state expression.

If the user specifies an FSM that Covered is not able to find (either the module was not included in the design that Covered is scoring or the FSM uses Verilog code that Covered is not able to handle), an error message is displayed to the user. It is then up to the user to determine if the FSM was incorrectly specified to Covered or otherwise. This warning is not considered to be a bug in Covered (unless of course, it can be proven that the FSM should have been found).

At the current time, Covered does not have the ability to extract the states and state transitions of the specified FSM from the design. Currently, it also doesn't have the ability to specify this information in other ways. To provide meaningful coverage information for the FSM, Covered outputs all hit states and state transitions in the report when all achievable states and state transitions are not known. This information will be able to be specified by the user in future versions of Covered, with the ability to automatically extract this information also in the works.

Though Covered has support for many Verilog-1995, Verilog-2001 and SystemVerilog constructs there are handful of supported constructs that are dependent on correct simulation ordering to provide accurate coverage information. In certain cases, Covered will be able to accurately determine the order of simulation, but in some cases, it may not. In these cases, it is best for Covered to run in a "conservative" mode of operation whereby logic blocks that contain these code issues are removed from coverage consideration. Removing logic blocks does not have a negative impact (in terms of coverage accuracy) on the rest of the design. The only negative consequence is that no coverage results can be obtained for a given logic block.

For example, consider the following code:

  module main;
    foo a();
    bar b();
  endmodule

  module foo;
    integer a;
    initial begin
      #10;
      a = $random;
    end
  endmodule

  module bar
    integer a;
    initial begin
      #5;
      a = $random;
    end
  endmodule
      

If only module "foo" is chosen to gather coverage information, the call to the $random function will result in a value that will not match the actual simulation if the -conservative option is not specified. This is due to the ordering importance of $random system task calls. The first call to $random will return a value of X while the second call will return a value of Y. If we remove the code that calls $random the first time, the code that still calls X will receive the incorrect value. This discrepancy in simulation results will result in incorrect coverage results.

If the -conservative option is specified to the score command, Covered will automatically remove any coverage blocks that make a call to the $random system function from coverage consideration and any assigned values within these removed blocks will get their value from the dumpfile instead of being calculated by Covered directly. This will result in correct coverage information for the module "foo".

The constructs that can cause issues with Covered simulation correctness (in some situations) are the following:

It is currently up to the user to determine whether liberal or conservative coverage accumulation should occur and use the -conservative option to the score command as needed.

Covered supports the $test$plusargs and $value$plusargs system function calls and, as such, runtime command-line options are allowed to be specified when scoring the design. To specify plusargs to the score command, simply specify them anywhere after the score command keyword just as you would specify them to a simulator. Any plusargs specified to the score command which are not recognized for compilation purposes are used for $test$plusargs and $value$plusargs comparisons,

Note that specifying plusargs to the score command is only necessary when the score command is given either the -vcd, -lxt or -fst options. If the VPI method of coverage scoring is used, specify the plusargs to the simulation runtime as required. Covered will automatically extract the plusargs from the simulator runtime for its purposes.

When the Verilog files are parsed, a preprocessor is run on each file that is to be read in by Covered. The preprocessor generates an intermediate form of each file, resolving defined values and included files. The intermediate form is output to a file which is called "tmpXXXXXX" where XXXXXX represents some alphanumeric sequence chosen by the OS via the mkstemp() function. The file is guaranteed to be unique to all other files in the directory and it is automatically removed by Covered when parsing is completed.

If the user does not want Covered to use this naming convention for specifying this file, the user may use the -p option (see Options section above) to override the default name. Covered will then use this filename instead of generating a unique name. Make sure that the file specified does not contain any useful data since Covered will overwrite this file when the score command is run.