Covered(1)

NAME

Covered - Verilog Code Coverage Analyzer

SYNTAX

covered [<global_options>] score [<options>]
covered [<global_options>] merge [<options>] <existing_database> <database_to_merge>+
covered [<global_options>] report [<options>] <database_file>

DESCRIPTION

Covered is a Verilog code coverage analysis tool that can be useful for determining how well a diagnostic test suite is covering the design under test. Covered reads in the Verilog design files and a VCD or LXT formatted dumpfile from a diagnostic run and generates a database file called a Coverage Description Database (CDD) file, using the score command. Covered's score command can alternatively be used to generate a CDD file and a Verilog module for using Covered as a VPI module in a testbench which can obtain coverage information in parallel with simulation (see USING COVERED AS A VPI MODULE). The resulting CDD file can be merged with other CDD files from the same design to create accummulated coverage, using the merge command. Once a CDD file is created, the user can use Covered to generate various human-readable coverage reports in an ASCII format or use Covered's GUI to interactively look at coverage results, using the report command. Additionally, as part of Covered's score command, race condition possibilities are found in the design files and can be either ignored, flagged as warnings or flagged as errors. By specifying race conditions as errors, Covered can also be used as a race condition checker.

GLOBAL OPTIONS

These options are placed immediately after the keyword covered in the command-line. They can be used for any command (with the exception of -v and -h) and have the same effect in each case.

-D  Debug. Display information helpful for debugging tool problems. Note: This option is now only available when covered is built with the --enable-debug configuration option.

-B  Obfuscate. Obfuscates all design-sensitive names before outputting in user-readable format. This option is useful when sharing output with the developers of Covered for debugging purposes.

-h  Help. Display this usage information.

-Q  Quiet mode. Causes all output to be suppressed.

-v  Version. Display current Covered version.

COMMANDS

score
    Parses Verilog files and VCD/LXT dumpfiles to create database file used for merging and reporting.

merge
    Merges two or more database files into one.

report
    Generates human-readable coverage reports from database file or starts the coverage report GUI.

SCORE COMMAND

The following options are valid for the score command:

-A ovl
    Causes OVL assertions to be used for assertion coverage. This flag must be given to the score command if assertion coverage metrics are needed in the report command.

-D define_name
    Defines the specified name to 1.

-D define_name=value
    Defines the specified name to the specified value.

-e block_name
    Name of module, task, function or named begin/end block to not score. Causes all subblocks in the Verilog tree under this block to also not be scored.

-ea Excludes all always blocks from being considered for coverage.

-ec Excludes all continuous assignments from being considered for coverage.

-ei Excludes all initial blocks from being considered for coverage.

-F module_name=[in_expr,]out_expr
    Indicates to the parser where to find the FSM located in module module_name which has an input state expression called in_expr and output state expression called out_expr. If in_expr is not specified, out_expr is used as both the input and output state expression.

-f filename
    Name of file containing additional arguments to parse.

-g [module_name=](1|2|3)
    Allows the user to limit the parser to a specific generation of the Verilog standard for a specific module or the entire design, where 1=Verilog-1995, 2=Verilog-2001, 3=SystemVerilog. If module_name= is specified, the parser uses the specified Verilog standard for that module only, allowing the rest of the design to use the global standard. By default, the global standard is set to the most recent version (3). This option can be specified more than once for a given call to the score command; however, if the -g option specifies more than global value (i.e., without the module= prefix), only the last option value will be used.

-h  Displays this help information.

-I directory
    Directory to find included Verilog files.

-i instance_name
    Verilog hierarchical reference to the module that is at the top of the tree to be scored. This option is necessary if module to verify coverage is not the top-level module in the design. If not specified, -t value is used.

-lxt filename
    Name of LXT/LXT2 dumpfile to score design with. If this or the -vcd option is not used, Covered will only create an initial CDD file from the design and will not attempt to score the design.

-o database
    Name of database to write coverage information to. If not specified, the output database filename will be "cov.cdd".

-p filename
    Overrides default filename used to store intermediate preprocessor output.

-P parameter_scope=value
    Performs a defparam on the specified parameter with value.

-r(S|W|E|I)
    Specifies action to take when race condition checking finds problems in design (-rS = Silent, -rW = Warning, -rE = Error, -rI = Ignore race condition checking step).

-S  Outputs simulation statistics after simulation has completed. This information is currently only useful for the developers of Covered.

-t top-level module
    Specifies the module name of the top-most module that will be measured. Note that this module does not need to be the top-most module in the simulator. This field is required for all calls to the score command.

-ts number
    When scoring occurs, this option allows the user to see how far the simulator has progressed by outputting the current timestep to standard output. The value of number specifies how many timesteps are allowed to be simulated before outputting the current timestep (results in less calls to output stream).

-T (min|typ|max)
    Specifies which value to use when encountering a delay expression in the form: min:typ:max. If this option is not specified, 'typ' select is used by default.

-v filename
    Name of specific Verilog file to score.

-vcd filename
    Name of VCD dumpfile to score design with. If this or the -lxt option is not used, Covered will only create an initial CDD file from the design and will not attempt to score the design.

-vpi [filename]
    If this option is specified without the -vcd or -lxt options, the design is parsed, a CDD file is created and a top-level Verilog module named filename (if this value is specified) or "covered_vpi.v" (if filename is not specified) is created along with a PLI table file called filename.ta b or "covered_vpi.v.ta b". Both of these files are used in the compilation of the simulator to use Covered as a VPI module. If either the -vcd or -lxt options are specified, this option has no effect.

-y directory
    Directory to find unspecified Verilog files.

+libext+.extension[+.extension]*+
    Extensions of Verilog files to allow in scoring.

MERGE COMMAND

The following options are valid for the merge command:

-h  Displays this help information.

-o filename
    File to output new database to. If this argument is not specified, the existing_database is used as the output database name.

REPORT COMMAND

The following options are valid with the report command:

-c  If -v is specified, displays covered line, toggle and combinational cases. Default is to display uncovered information.

-d (s|d|v)
    Level of detail to provide in coverage report information (s = summary, d = detailed, v = verbose). Default is summary.

-h  Displays this help information.

-i  Provides coverage information for instances instead of module.

-m [l][t][c][f][r][a]
    Type(s) of metrics to report. l=line, t=toggle, c=combinational logic, f=FSM state and state transition, r=race conditions, a=assertion. Default is ltcf.

-o filename
    File to output report information to. Default is standard output.

-s  Suppresses modules/instances that contain no coverage information from being output to the report. Used to help eliminate potentially meaningless information from the report.

-v  Deprecated. Replaced by '-d d' or '-d v'.

-view
    Starts the GUI interface for interactive coverage reporting.

-w (number)
    Specifies the maximum line width (in characters) that can be used to output Verilog information. If this option is not specified, all Verilog code in the report will retain the same formatting as was specified in the original Verilog code. If this option is specified, Verilog code will be formatted to use as much of the current line as possible, wrapping text when the line reaches the maximum line width. The default maximum line width is 115 characters (this value is used if no number is specified with the -w option). If a number is specified with the -w option, this value is used for the maximum line width.

USING COVERED AS A VPI MODULE

In addition to using Covered's score command to parse a VCD or LXT file to abstract coverage information, Covered may also be used as a VPI module within a simulator to extract this information.  The advantages to using Covered as a VPI over a dumpfile reader include the following.  First, VCD files can be extrememly large, especially for long simulations, using up valuable disk space.  Second, if you are using a simulator that dumps files in a different format than VCD or LXT and you want to convert these dump file types to one of these versions, the cost of disk space and time can make creating dumpfiles that Covered requires undesirable.  Additionally, though using Covered as a VPI module will slow down your simulation speed, it is most likely that the total time spent simulating your design and scoring the design in one step will be shorter than doing so in two steps.  As a result, Covered's configure utility can generate VPI-ready libraries for the following free and commercial simulators (Icarus Verilog, CVER and VCS).

To automatically build the VPI-ready library files when generating Covered from source, simply specify one or more of the following when running the "configure" utility in the base Covered directory:  --with-iv, --with-vcs=<VCS include path>, --with-cver=<CVER include path>.  After Covered has been configured, simply type 'make' and 'make install'.  This will install the VPI-ready library files in the installation libexec directory (by default this path will be /usr/local/libexec).

Before you are ready to compile the design, you must first create a CDD file, a top-level Verilog file, and a PLI table file (the last file is only needed for the VCS compiler).  This is done by specifying the -vpi  (filename) option to Covered's score command.  If no filename is specified after -vpi, the files covered_vpi.v and covered_vpi.v.ta b will be created along with the generated coverage file.  Note that this step only needs to be performed once unless the design files change.  You are now ready to compile the simulator.

If you are compiling an Icarus Verilog simulation, simply add '-m /usr/local/libexec/covered.vpi covered_pli.v' to the 'iverilog' command-line.  Once compilation is complete, run the generated executable file as you normally would.

If you are compiling a CVER simulation, simply add '+loadvpi=/usr/local/libexec/covered.cver.so:vpi_compat_bootstrap covered_vpi.v' to the 'cver' command-line.

If you are compiling a VCS simulation, simply add '+vpi -load /usr/local/libexec/covered.vcs.so:covered_register -P covered_pli.v.ta b covered_pli.v' to the 'vcs' command-line.  Once compilation is complete, run the generated executable file as you normally would.

There are two plusargs that can be passed to the generated executable when it is run that Covered will parse.  The '+covered_cdd=<filename>' option will cause Covered to output the scored design contents to the CDD file specified by <filename>.  This allows multiple runs of the simulator to generate several different CDD files without needed a recompile to occur.  The '+covered_debug' option will cause Covered to dump a lot of excessive output about its internal run-time state during simulation.  This output will only be generated if Covered was configured with the --enable-debug option.  This plusarg option should not be used by regular users as it is primarily intended to aid the developers of Covered in debugging.

AUTHORS

Trevor Williams <trevorw@charter.net>

SEE ALSO

For more information on how to use the Covered code coverage tool, please consult the on-line User's Guide at http://covered.sourceforge.net/user/index.html.