/usr/share/covered/doc/html/chapter.using.html is in covered-doc 0.7.10-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 8. Using Covered</title><link rel="stylesheet" href="covered.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.71.1"><link rel="start" href="index.html" title="Covered User's Guide - 0.7.9"><link rel="up" href="part.command.line.usage.html" title="Part III. Command-line Usage"><link rel="prev" href="chapter.start.html" title="Chapter 7. Getting Started"><link rel="next" href="chapter.score.html" title="Chapter 9. The score Command"><center><img src="img/banner.jpg"></center><hr></head><body bgcolor="#dfeef8" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Using Covered</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="chapter.start.html"><img src="img/prev.gif" alt="Prev"></a> </td><th width="60%" align="center">Part III. Command-line Usage</th><td width="20%" align="right"> <a accesskey="n" href="chapter.score.html"><img src="img/next.gif" alt="Next"></a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter.using"></a>Chapter 8. Using Covered</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="chapter.using.html#section.using.flow">8.1. Work Flow</a></span></dt><dd><dl><dt><span class="sect2"><a href="chapter.using.html#section.using.flow.score">Scoring the Design</a></span></dt><dt><span class="sect2"><a href="chapter.using.html#section.using.flow.merge">Merging CDDs</a></span></dt><dt><span class="sect2"><a href="chapter.using.html#section.using.flow.report">Creating Coverage Reports</a></span></dt><dt><span class="sect2"><a href="chapter.using.html#section.using.flow.rank">Ranking CDDs</a></span></dt><dt><span class="sect2"><a href="chapter.using.html#section.using.flow.exclude">Excluding CDD Coverage Points</a></span></dt></dl></dd><dt><span class="sect1"><a href="chapter.using.html#section.using.usage">8.2. Covered usage</a></span></dt><dt><span class="sect1"><a href="chapter.using.html#section.using.globalopts">8.3. Covered global options</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section.using.flow"></a>8.1. Work Flow</h2></div></div></div><p>
Covered has four basic commands that it uses for gaining coverage information about a design and displaying
that information to the user.
</p><p>
</p><div class="itemizedlist"><ul type="disc"><li><p>score</p></li><li><p>merge</p></li><li><p>report</p></li><li><p>rank</p></li></ul></div><p>
</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section.using.flow.score"></a>Scoring the Design</h3></div></div></div><p>
To begin using Covered, you will need to create a special database file called a coverage description
database (CDD). Covered uses this file to store coverage-specific information about the DUT. This file is a
text-based file that is written in a specific format (the format of this file is not discussed in this
document but can be found in the developer's document) that Covered understands.
</p><p>
To create the CDD and populate it with the simulation dumpfile results, you must use the score (see
<a href="chapter.score.html" title="Chapter 9. The score Command">Chapter 9, <i>The score Command</i></a> for details) command. This command parses in the DUT files and generates
an initial CDD for the design. This CDD does not contain any coverage details but only the design elements
that Covered needs to gain coverage results.
</p><p>
Once the initial CDD has been created, the score command reads in the specified VCD/LXT2 dumpfile from the
given DUT. If Covered recognizes that the VCD/LXT2 dumpfile does not correspond to the DUT that it parses
(dumpfile was not generated from the DUT specified), an error message is supplied to the user telling them
this. Once the dumpfile has been parsed, Covered generates a new version of the CDD containing a
populated database. This CDD may be merged with another CDD from the same DUT and/or reports may be
generated from this CDD.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section.using.flow.merge"></a>Merging CDDs</h3></div></div></div><p>
When two or more CDDs have been generated from the same DUT. It is often desirable to merge their contents
to see what the total coverage is for both simulation runs. The reasons why merging is desirable is that
often several tests are written to exercise the entire design (not just one). This makes tests easier to
write and maintain. Since, typically, only one test is run per simulation run and that test does not fully
test the DUT, it is necessary to combine the results of the multiple simulations to the see the combined
effect of the tests on the design. This is where merging comes into play.
</p><p>
Merging multiple CDDs from the same design is easy with Covered, and is accomplished with the merge (see
<a href="chapter.merge.html" title="Chapter 10. The merge Command">Chapter 10, <i>The merge Command</i></a> for details) command. This command reads in two or more CDDs, merges their
results and outputs the merged CDD to a different file or replaces the first CDD with the results of the merge.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section.using.flow.report"></a>Creating Coverage Reports</h3></div></div></div><p>
After a CDD is created or merged, the contents of the CDD can be extracted and transformed into human-readable
coverage reports with the report (see <a href="chapter.report.html" title="Chapter 11. The report Command">Chapter 11, <i>The report Command</i></a> for details) command. A summary
report containing the percentage of metrics covered is generated for each module. Additionally, to aid in
understanding what and why something was not covered, a verbose reporting mechanism exists. Verbose
reporting will explicitly point to and describe why something was not fully covered for a specific metric.
</p><p>
Reports are text-based output that by default are directed toward standard output but may, with the use of an
option flag, be output to a specific file for storage purposes.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section.using.flow.rank"></a>Ranking CDDs</h3></div></div></div><p>
After a collection of CDDs have been generated from a single design (most likely due to a regression run),
it is desirable to know which CDDs have an effect on coverage and which CDDs do not add any new coverage
information. The CDDs that do not provide additional coverage may be unnecessary for regression and removing
them may significantly improve a regression runs time (which can help in a projects schedule).
</p><p>
Additionally, it also good to know an order that simulations should be run in to produce the maximum amount
of coverage the quickest. This information can be useful for creating a quick (or "sanity check" or
"confidence") regression that runs in a relatively short period of time and, when run successfully, provides
the engineer a level of confidence that recent changes have not severely broke the functionality of the design.
</p><p>
This is the purpose of the rank (see <a href="chapter.rank.html" title="Chapter 12. The rank Command">Chapter 12, <i>The rank Command</i></a> for details) command. It produces a
report that shows the diagnostics that add to the overall coverage of the suite, the order that those
diagnostics should run, and each diagnostic's overall effect on coverage when it is run.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="section.using.flow.exclude"></a>Excluding CDD Coverage Points</h3></div></div></div><p>
Not all unhit coverage points reported by Covered will be valid for your design. Some coverage points may
be extraneous, some may be due to obsolete logic that is not pulled from the design for various reasons, and
some coverage points may be hit in other verification environments but not in the current environment.
</p><p>
Whatever the reason may be (and some reasons may be much more specific that these suggestions), Covered
allows the user to exclude those coverage points from coverage reporting (they will still be reported but they
will be considered "covered" points instead of "uncovered" points). Additionally, each excluded coverage
point can have an option message attached to it that explains the reason for exclusion. This message is stored
with the coverage information in the CDD file and can be displayed in a standard coverage report or in a
stand-alone exclusion report. This information helps to document the coverage analysis process.
</p><p>
In addition to being able to exclude coverage points, the user can also include previously excluded coverage
points (in the event that a mistake was made or if the design has changed). Coverage exclusion can be
accomplished via the command-line <a href="chapter.exclude.html" title="Chapter 13. The exclude Command">exclude</a> command or within the GUI
coverage analyzer.
</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section.using.usage"></a>8.2. Covered usage</h2></div></div></div><p>
Covered is initiated with the following command:
</p><p>
<code class="code">
covered (-h | -v | [-P [<span class="emphasis"><em>filename</em></span>]] [-B] [-D|-T|-Q]) (score|merge|report|rank) <span class="emphasis"><em>command_options</em></span>)
</code>
</p><p>
The -v command (described below) is mutually exclusive from the rest of the commands and has the highest priority.
If Covered is called with this option and any other options, the version will only be displayed.
</p><p>
The -h command (described below) is mutually exclusive from the rest of the commands and has the second highest
priority. If Covered is called with this option and the -v option is not specified, the usage information will
be displayed to the screen.
</p><p>
The -Q option suppresses all normal user output from standard output. The only output that will not be suppressed
are messages to standard error. This option may be used with any of the Covered commands to achieve this effect.
By default, normal user output is sent to standard output.
</p><p>
The -T option suppresses all normal user output from standard output with the exception of the Covered header banner,
warning messages. This type of output is a bit more informative than output generated with the -Q option but not as
much as running without any output limiters.
</p><p>
The -D option outputs debug information to standard output. Its effect overrides the -Q option. This option may be
used in conjunction with any other Covered command for the purposes of debugging tool failures. By default, debug
mode is turned off and must be enabled in the build of Covered (using the --enable-debug option to configure).
This command should only be used for debugging as it generates an immense amount of output which may hinder
performance.
</p><p>
The -B option obfuscates all design-sensitive signal, module, task, function, instance, file and parameter names
when outputting them to either stdout, stderr or a file (with the exception of CDD file output). This mode is
intended to be used for sharing output information with others (including the developer's of Covered) which is
sensitive information for the purposes of debugging.
</p><p>
The -P option causes Covered to enable internal code profiling and generates a profiling report that is output
to either the given filename or the default filename of "covered.prof". This option is only available if the
--enable-profiling configuration option is specified and will cause performance degradation. This option should
only be used by Covered developers or those interested in finding performance bottlenecks in Covered's code.
It is not recommended that the --enable-profiling configuration option and the -P global option be specified for
normal users of Covered. See <a href="chapter.debug.html#section.profiling" title="15.3. Source Code Profiling">Section 15.3, “Source Code Profiling”</a> for more information on profiling and
understanding the profiling report file.
</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section.using.globalopts"></a>8.3. Covered global options</h2></div></div></div><p>
The following table describes options that Covered will accept apart from its normal commands which are described
in the next several chapters.
</p><div class="table"><a name="table.using.globalopts"></a><p class="title"><b>Table 8.1. Global Options to Covered</b></p><div class="table-contents"><table summary="Global Options to Covered" border="1"><colgroup><col><col></colgroup><thead><tr><th>
Option
</th><th>
Description
</th></tr></thead><tbody><tr><td>
-Q
</td><td>
Quiet mode. Suppresses user output to screen. Use in conjunction with a command.
</td></tr><tr><td>
-T
</td><td>
Terse mode. Causes all output to be suppressed with the exception of warning messages and the Covered header information.
Use in conjunction with a command.
</td></tr><tr><td>
-D
</td><td>
Debug mode. Outputs code debug information to screen. Use in conjunction with commands.
</td></tr><tr><td>
-B
</td><td>
Obfuscate. Obfuscates all design sensitive names before outputting them.
</td></tr><tr><td>
-P [<span class="emphasis"><em>filename</em></span>]
</td><td>
Profiling mode. Outputs profiling report to either the given <span class="emphasis"><em>filename</em></span> or "covered.prof" if no
<span class="emphasis"><em>filename</em></span> was specified.
</td></tr><tr><td>
-h
</td><td>
Generates usage output to standard output.
</td></tr><tr><td>
-v
</td><td>
Outputs current version of Covered.
</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="chapter.start.html"><img src="img/prev.gif" alt="Prev"></a> </td><td width="20%" align="center"><a accesskey="u" href="part.command.line.usage.html"><img src="img/up.gif" alt="Up"></a></td><td width="40%" align="right"> <a accesskey="n" href="chapter.score.html"><img src="img/next.gif" alt="Next"></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Getting Started </td><td width="20%" align="center"><a accesskey="h" href="index.html"><img src="img/home.gif" alt="Home"></a></td><td width="40%" align="right" valign="top"> Chapter 9. The score Command</td></tr></table></div></body></html>
|