16 

9   The score Command

9.1  Usage

The score command is initiated with the following call:

covered 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 in section 9.3 below.

9.2  Options

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.

9.3  Specifying What to Cover

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/LXT 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

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

• module "test" instantiated as "test" in the above figure
• module "foomod" instantiated as "foo"
• module "barmod" instantiated as "bar"
• module "amod" instantiated as "a"
• module "bmod" instantiated as "b"

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

Command

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:

Command

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:

Command

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> or -lxt <lxt_dumpfile> parameter is simply the name of the VCD/LXT dumpfile that contains all of the module instances selected by the -t parameter (in combination with the -e option -- see below).

9.4  Overriding Parameters (-P option)

As mentioned in Section 9.3, Covered does not pay attention to the entire DUT. This allows it to be more flexible and more efficient in memory and processing requirements. This also has a down-side in that certain parts of the DUT are not parsed which can affect other parts of the DUT (parts needing to be scored). More specifically, parameter overriding which are accomplished with the defparam command.

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/LXT 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:

Option Example

-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.

9.5  Scoring FSMs

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.

1. The FSM is a synchronous design with edge-triggered flip-flops.
2. There are no FSMs embedded in another FSM.
3. The FSM is not a pipe-lined system.
4. The entire FSM must exist within the same module.
5. All state registers/variables must be less than 2^16 bits in width.

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:

FSM score option

-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.

Example 1

-F foobar=a

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

Example 2

-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.

Example 3

-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.

Example 4

-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.

9.6  Other Notes

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.

[  Contents  |  First Page  |  Previous Page  |  Home   | Next Page  |  Last Page  ]