User Guide: Merging And Viewing Coverage Results

Modified on Thu, 11 Jul at 11:43 AM

User Guide: Merging And Viewing Coverage Results

Coverage data from any simulation run is saved into a database "metrics.db" in each simulation run directory. This database stores functional, block, toggle, expression and assertion coverage. All coverage types can be merged and viewed.

Merging

The dcmerge utility is used to merge coverage databases. Merging is required if you have more than one test run, and you wish a coverage report over all such runs.

Usage: dcmerge -out_db result.db dir1/metrics.db dir2/metrics.db ...

If the result.db does not exist, it will be created. Otherwise, any previous data will be preserved and added to.

Viewing

The dcreport utility is used to generate a coverage report in HTML format.

Usage: dcreport -out_dir dir metrics.db

dcreport must be provided with a path to a directory into which the report files are to be written. If the directory does not exist then it will be created. The other required argument is a single coverage databage to report on. If you have more than one database then use dcmerge to merge first.

The landing page for the coverage report will be in dir/index.html. This file can be viewed in any modern web browser. From there, hyperlinks permit navigation to the coverage reports for each instance in the hierarchy.

Interpreting Block Coverage

The block coverage report shows which "basic blocks" have been covered. A basic block is a section of code that has one entry point and one exit point. Looping and conditional statements create basic blocks. Time-consuming statements also create new basic blocks, as a time-consuming statement may not complete if the block is disabled or if the simulation ends.

Each basic block is colored to highlight it in the source code listing, and the block type is displayed to the left. A block may stretch over multiple lines of code. Conversely, there may be multiple blocks on a single line. This is especially true for for loops, where the initialization, test, and increment statements are separate blocks.

The following types of blocks are identified:

Block Type	Description
sequence	A sequence of lines, possibly inside `begin-end` that have no other attribute.
loop_body	The body of a loop.
if	The "true" branch of an `if` statement.
elsif	For VHDL, a "true" section of an `elsif` block.
else	The "false" branch of any `if` statement.
implicit_else	For `if` statements with no `else` clause, indicates a count of times where no statements in the block were executed.
blocking	Indicates a continuation of a block through a time-consuming statement that may not complete.
case_item	Indicates a case statement choice.
implicit_case_default	For `case` statements that have no `default`, indicates a count of times where no condition matched.
reconvergence	Indicates the start of a block created by the merging of two control paths. Typically occurs at the end of an `if` statement.
dead	Indicates code in an `if` or `case` statement that cannot be reached because the conditional expression evaluates to a constant.
useless	Indicates tasks or functions that are never called, or `always` blocks that have no effect because no code reads any variables they write.
optimized_out	Indicates continuous assignments that are never directly executed as a result of assignment propagation.

Examples of optimizations impacting block coverage:

module blk(input clk);
parameter DOIT = 1;
reg [7:0] q;
wire clkg;

// This assignment can be removed if we replace all references to "clkg" with "clk".
// Such assignment are marked "optimized_out".
assign clkg = clk;

always @*
   if (DOIT) 
       // This code will always be executed, but will be "dead" if `DOIT` is overridden to 0.
   else
       // This code is dead unless `DOIT` is overridden to 0.

task never_called;
    $display("I am never called.  Not even through a hierarchical reference.");
endtask

// This block is useless if nothing ever reads q.
always @(posedge clkg) q <= q + 1;

endmodule