.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "VERILATOR_COVERAGE 1"
.TH VERILATOR_COVERAGE 1 "2020-08-27" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
verilator_coverage \- Verilator coverage analyzer
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    verilator_coverage \-\-help
\&    verilator_coverage \-\-version
\&
\&    verilator_coverage \-\-annotate <obj>
\&
\&    verilator_coverage  \-write merged.dat \-read <datafiles>...
\&
\&    verilator_coverage  \-write\-info merged.info \-read <datafiles>...
.Ve
.PP
Verilator_coverage processes Verilator coverage reports.
.PP
With \-\-anotate, it reads the specified data file and generates annotated
source code with coverage metrics annotated.  If multiple coverage points
exist on the same line, additional lines will be inserted to report the
additional points.
.PP
Additional Verilog-standard arguments specify the search paths necessary to
find the source code that the coverage analysis was performed on.
.PP
To get correct coverage percentages, you may wish to read logs/coverage.dat
into Emacs and do a M\-x keep-lines to include only those statistics of
interest.
.PP
For Verilog conditions that should never occur, you should add a \f(CW$stop\fR
statement.  This will remove the coverage during the next build.
.SH "ARGUMENTS"
.IX Header "ARGUMENTS"
.IP "\fIfilename\fR" 4
.IX Item "filename"
Specify input data file, may be repeated to read multiple inputs.  If no
data file is specified, by default coverage.dat is read.
.IP "\-\-annotate \fIoutput_directory\fR" 4
.IX Item "--annotate output_directory"
Sprcifies the directory name that source files with annotated coverage data
should be written to.
.IP "\-\-annotate\-all" 4
.IX Item "--annotate-all"
Specifies all files should be shown.  By default, only those source files
which have low coverage are written to the output directory.
.IP "\-\-annotate\-min \fIcount\fR" 4
.IX Item "--annotate-min count"
Specifies the minimum occurrence count that should be flagged if the
coverage point does not include a specified threshold.  Defaults to 10.
.IP "\-\-help" 4
.IX Item "--help"
Displays this message and program version and exits.
.IP "\-\-rank" 4
.IX Item "--rank"
Print an experimental report listing the relative importance of each test
in covering all of the coverage points.  The report shows \*(L"Covered\*(R" which
indicates the number of points that test covers; a test is considered to
cover a point if it has a bucket count of at least 1. The \*(L"rank\*(R" column has
a higher number t indicate the test is more important, and rank 0 means the
test does not need to be run to cover the points.  \*(L"RankPts\*(R" indicates the
number of coverage points this test will contribute to overall coverage if
all tests are run in the order of highest to lowest rank.
.IP "\-\-unlink" 4
.IX Item "--unlink"
When using \-\-write to combine coverage data, unlink all input files after
the output has been created.
.IP "\-\-version" 4
.IX Item "--version"
Displays program version and exits.
.IP "\-\-write \fIfilename\fR" 4
.IX Item "--write filename"
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in verilator_coverage data format.
This is useful in scripts to combine many sequential runs into one master
coverage file.
.IP "\-\-write\-info \fIfilename.info\fR" 4
.IX Item "--write-info filename.info"
Specifies the aggregate coverage results, summed across all the files,
should be written to the given filename in \f(CW\*(C`lcov\*(C'\fR .info format.
This may be used to use \f(CW\*(C`lcov\*(C'\fR to aggregate or generate reports.
.Sp
The info format loses data compared to the Verilator coverage data format;
the info will all forms of coverage converted to line style coverage, and
if there are multiple coverage points on a single line, the minimum
coverage across those points will be used to report coverage of the line.
.SH "VERILOG ARGUMENTS"
.IX Header "VERILOG ARGUMENTS"
The following arguments are compatible with \s-1GCC, VCS\s0 and most Verilog
programs.
.IP "+libext+\fIext\fR+\fIext\fR..." 4
.IX Item "+libext+ext+ext..."
Defines the extensions for Verilog files.
.IP "+define+\fIvar\fR+\fIvalue\fR =item \-D\fIvar\fR=\fIvalue\fR" 4
.IX Item "+define+var+value =item -Dvar=value"
Defines the given variable.
.IP "+incdir+\fIdir\fR =item \-I\fIdir\fR" 4
.IX Item "+incdir+dir =item -Idir"
Specifies a directory for finding include files.
.IP "\-f \fIfile\fR" 4
.IX Item "-f file"
Specifies a file containing additional command line arguments.
.IP "\-y \fIdir\fR" 4
.IX Item "-y dir"
Specifies a module search directory.
.SH "DISTRIBUTION"
.IX Header "DISTRIBUTION"
The latest version is available from <https://verilator.org>.
.PP
Copyright 2003\-2020 by Wilson Snyder. This program is free software; you
can redistribute it and/or modify the Verilator internals under the terms
of either the \s-1GNU\s0 Lesser General Public License Version 3 or the Perl
Artistic License Version 2.0.
.PP
SPDX-License-Identifier: \s-1LGPL\-3\s0.0\-only \s-1OR\s0 Artistic\-2.0
.SH "AUTHORS"
.IX Header "AUTHORS"
Wilson Snyder <wsnyder@wsnyder.org>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CW\*(C`verilator\*(C'\fR, \f(CW\*(C`lcov\*(C'\fR
.PP
\&\*(L"verilator_coverage \-\-help\*(R" which is the source for this document.