Chapter 7. Getting Started
| Part III. Command-line Usage |

## Chapter 7. Getting Started

## 7.1. Methods for scoring the design

Before you are ready to being scoring, merging and generating coverage reports from the design, you will first need to decide whether you want to post-process VCD/LXT2/FST -formatted dumpfiles generated from simulation, co-process VCD/LXT2/FST -formatted dumpfiles using two processes (one for the simulation process and one for the Covered process) and a Unix FIFO, or whether you want to accummulate coverage information alongside the simulator using the simulator's VPI interface. There are advantages and disadvantages to these methods, so select the method that will best work for you.

### Post-processing VCD/LXT2/FST dumpfiles

Generating post-process coverage information from VCD/LXT2/FST -formatted dumpfiles requires three steps:

1. Compile the simulator to dump in the specified format.

2. Run the simulation.

3. Run Covered's score command using the dumpfile as input along with the design.

Performing these steps will generate the needed CDD file that can be used for merging or reporting. The advantages to this approach is that the steps are fairly simple and are compiler/simulator -independent. However, there are two main drawbacks. First, compiling with dumping enabled often slows simulation by some significant factor. Second, the dumpfiles generated from simulation can often be quite large (especially for VCD dumping), consuming a lot of disk space. Additionally, if your simulator dumps in a format different from VCD, LXT2 or FST, you will need to perform an additional step in transforming the original dumpfile into one of these formats. This is often a time-consuming task if the design and/or dumpfile is significantly large. If you are generating lots of dumpfiles for coverage (say from running a regression), the amount of disk space needed to store these files can be tremendous, making this approach almost not feasible.

### Co-processing VCD/LXT2/FST dumpfiles via FIFO

Generating co-process coverage information from VCD/LXT2/FST -formatted dumpfiles requires four steps:

1. Compile the simulator to dump in the specified format.

2. Create a Unix FIFO via the `mkfifo fifoname` command.

3. Create an empty CDD file for the design using Covered's score command.

4. Run the simulation and Covered's score command simultaneously. The following is an example of a testbench and command-line commands:

   Example 7.1. Running Covered Alongside a Simulation Process Using a Unix FIFO to Pass Dumpfile Information

         # Module listing for file "test.v"
         module tb;
           ...
           initial begin
                   $dumpfile( "dump_fifo" );
                   $dumpvars( 0, tb );
                   ...
           end
           ...
         endmodule

         # Command-line output
         > mkfifo dump_fifo
         > vcs test.v
         > covered score -t tb -v test.v -o test.cdd
         > ./simv &
         > covered score -cdd test.cdd -vcd dump_fifo

The end result of these steps is the same CDD file that results from using the dumpfile method described above. The primary advantages of this approach are that no dumpfiles are actually created, saving on disk space, and it does not significantly slow down the simulation process. Because both simulation and coverage scoring occur simultaneously, there should be a wall clock time improvement with this method.

The drawbacks of this approach are basically that the time improvement won't be significant if you are running on a single processor/core system and that it is restricted to machines that support the Unix fifo (this may not be an actual restriction, however).

### Using the VPI interface to gather coverage information

Generating coverage information using the VPI interface of the simulator requires three main steps:

1. Create a base CDD file from the design along with a top-level Verilog module and PLI table file (this second file is needed for the commercial VCS compiler).

2. Compile the simulator using the Covered VPI module (or shared object).

3. Run the simulation.

The end result of these steps is the same CDD file that results from using the dumpfile method described above. The primary advantage of this approach is that no dumpfiles are required, saving on disk space and dumpfile processing time. The drawbacks of this approach are the following:

1. Simulation runs much slower using the VPI and Covered (most likely slower than creating dumpfiles from the simulator).

2. Covered VPI modules are only available for certain compilers (Icarus Verilog, Cver and VCS currently); however, adding support for other compilers should not be a difficult thing to do.

3. The VPI modules will only work for compilers that support the VPI interface (a Verilog-2001 feature).

## 7.2. What is needed for dumpfile scoring?

Before Covered can be invoked for dumpfile scoring, you must have a simulatable Verilog design and a VCD, LXT2 or FST dumpfile containing information from a simulation run of the design that dumps the module(s) that you want to check for coverage. The VCD dumpfile style was chosen due to its universal support by Verilog simulators while the LXT2 and FST dumpfile styles were chosen due to their compactness and growing support by other open source simulators and dumpfile readers. Once you have these two parts, you are ready to begin generating coverage results.

### Selecting What to Dump

If coverage is being scored via a VCD/LXT2/FST dumpfile, it is necessary for the user to setup $dumpfile and $dumpvars calls to dump the various modules that are being scored. Covered allows the user to do this in one of two ways.

First, the user may hand create these calls within their testbench. If this approach is taken, it is necessary that all modules being scored by Covered be included in the $dumpvars calls. Eliminating scored modules from the dumpfile will result in inaccurate coverage information. Additionally, it is mandatory that the dumpfile start at time 0 and that all dump information be included in the dumpfile (i.e., using the $dumplimit system task could cause dump information to be lost that will result in inaccurate coverage results).

Second, the user may take advantage of Covered's -dumpvars option to the score command. Adding this parameter (and the optional -top_ts option) will create a top-level module file that can be compiled along with the testbench that will dump all of the parts of the Covered design that are needed by Covered. Using this approach will result in the best overall performance for dumpfile coverage accumulation as all unnecessary dump information will be stripped, resulting in both faster simulation and faster coverage scoring.

If the second approach is taken, simply use the score command to parse the design and output an unscored CDD and the dumpvars module, using a command similar to the following:

      covered score -t top -v dut.v -dumpvars dut_dump.v -o dut.cdd

If `timescale is specified at the top of dut.v, it may be necessary for compiling purposes to have the timescale specified at the top of dut_dump.v. To do this, simply specify the -top_ts option in the score command. Note that the example command does not list either the -vcd, -lxt or -fst options. If either of these options are present on the score command-line, the dut_dump.v file will not be created and the score command will attempt to score the design with the specified dumpfile.

After the dut_dump.v file has been created, simply compile it along with your DUT as a top-level module. For example,

      iverilog dut.v dut_dump.v

After the simulation has been compiled and run, a dumpfile called "dut_dump.vcd" (using the above example) will exist in the run directory. This dumpfile can then be used in a second call to the score command via the -vcd, -lxt or -fst options along with the unscored CDD file to create a scored version of the CDD file.

### Creating a VCD dumpfile

By default, the $dumpfile system task call will create a file and populate it with VCD-style dumpfile information. Simply use the resulting VCD dumpfile in the -vcd option to the score command to obtain coverage for that design.

### Creating an LXT2 dumpfile

An LXT2 dumpfile can be created in several different ways depending on the Verilog simulation tool that you are using. If you are using the Icarus Verilog open source simulator, you can simply generate an LXT2-style dumpfile by specifying the -lxt2 option to the simulator command-line. For example, if you had a file called "foo.v" that contained the same $dumpfile and $dumpvars commands used for VCD dumping and compiled it with Icarus Verilog into a VVP file called "a.out", you could cause Icarus Verilog to generate an LXT2 dumpfile (instead of a VCD dumpfile) by calling "vvp a.out -lxt2". This will cause an LXT2 style dumpfile instead of the standard VCD style dumpfile.

You can also transform many different dumpfile formats into an LXT2 style dumpfile with the helper programs that come with the GtkWave waveform viewer.

### Creating an FST dumpfile

An FST dumpfile can be created in several different ways depending on the Verilog simulation tool that you are using. If you are using the Icarus Verilog open source simulator, you can simply generate an FST-style dumpfile by specifying the -fst option to the simulator command-line. For example, if you had a file called "foo.v" that contained the same $dumpfile and $dumpvars commands used for VCD dumping and compiled it with Icarus Verilog into a VVP file called "a.out", you could cause Icarus Verilog to generate an FST dumpfile (instead of a VCD dumpfile) by calling "vvp a.out -fst". This will cause an FST style dumpfile instead of the standard VCD style dumpfile.

You can also transform many different dumpfile formats into an FST style dumpfile with the helper programs that come with the GtkWave waveform viewer.

## 7.3. What is needed for VPI scoring?

After Covered has been configured and built to include the creation of a VPI loadable module or shared object file (see Section 6.3, “Configuring the build” for details), Covered is capable of scoring during a simulation run by using the VPI (Verilog Procedural Interface) access mechanism. This is done by loading the Covered VPI module (or shared object) into the simulator executable prior to running (depending on the simulator being used). The following steps should be taken to create a scored CDD file using this method.

1. Create the Verilog file that will be compiled as a top-level module in the design (alongside the actual top-level(s)).

   This is done by running the score command with the -vpi option. The following example command-line shows how this step is done, creating a file called "covered_vpi.v".

   `> covered score -t top -vpi`

2. Compile the simulator executable, including the previously generated file and the Covered VPI module. See the compile instructions for the Icarus Verilog, Cver or VCS simulators below.

3. Run the simulation. Once simulation is complete, the resulting CDD file will be a completely scored database, ready to be merged with other CDD files from the same design or reported on.

### Compiling for Icarus Verilog

If you are compiling an Icarus Verilog simulation, simply add `-m tool_install_root/libexec/covered.vpi covered_vpi.v` to the command-line.

### Compiling for Cver

If you are compiling a Cver simulation, simply add `+loadvpi=tool_install_root/libexec/covered.cver.so:vpi_compat_bootstrap covered_vpi.v` to the command-line.

### Compiling for VCS

If you are compiling a VCS simulation, simply add `+vpi -load tool_install_root/libexec/covered.vcs.so:covered_register covered_vpi.v` to the command-line.

### Compiling for NC-Verilog

If you are compiling a NC-Verilog simulation, switch to NC-Verilog's irun command to load the covered shared object: `-loadvpi tool_install_root/libexec/covered.ncv.so:covered_register` and enable all access with `-access +rwc`.

You can hardcode the $covered_sim call into your RTL or you can run it dynamically using the CLI, by adding the `-input input.tcl` switch to irun. Where the input.tcl file looks like the following and tb.dut is the coverage instance:

            call -systf {$covered_sim} {"scored.cdd"} tb.dut
            run

Part III. Command-line Usage |  | Chapter 8. Using Covered