1Covered(1) Code Analysis Covered(1)
2
6 Covered - Verilog Code Coverage Analyzer
7
9 covered [global_options] score [options]
10 covered [global_options] merge [options] existing_database data‐
11 base_to_merge+
12 covered [global_options] report [options] database_file
13 covered [global_options] rank [options] database_to_rank data‐
14 base_to_rank+
15 covered [global_options] exclude [options] exclusion_id+ database_file
16
18 Covered is a Verilog code coverage analysis tool that can be useful for
19 determining how well a diagnostic test suite is covering the design
20 under test. Covered reads in the Verilog design files and a VCD or LXT2
21 formatted dumpfile from a diagnostic run and generates a database file
22 called a Coverage Description Database (CDD) file, using the score com‐
23 mand. Covered's score command can alternatively be used to generate a
24 CDD file and a Verilog module for using Covered as a VPI module in a
25 testbench which can obtain coverage information in parallel with simu‐
26 lation (see USING COVERED AS A VPI MODULE). The resulting CDD file can
27 be merged with other CDD files from the same design to create accummu‐
28 lated coverage, using the merge command. Once a CDD file is created,
29 the user can use Covered to generate various human-readable coverage
30 reports in an ASCII format or use Covered's GUI to interactively look
31 at coverage results, using the report command. If uncovered coverage
32 points are found that the user wants to exclude from coverage, this can
33 be handled with either the command-line exclude command or within the
34 GUI. When multiple CDD files are created from the same design, the
35 user may obtain a coverage ranking of those CDD files to determine an
36 ideal order for regression testing as well as understand which CDD
37 files can be excluded from regressions due to their inability to hit
38 new coverage points. Additionally, as part of Covered's score command,
39 race condition possibilities are found in the design files and can be
40 either ignored, flagged as warnings or flagged as errors. By specify‐
41 ing race conditions as errors, Covered can also be used as a race con‐
42 dition checker.
43
45 These options are placed immediately after the keyword covered in the
46 command-line. They can be used for any command (with the exception of
47 -v and -h) and have the same effect in each case.
48 -B Obfuscate. Obfuscates all design-sensitive names before out‐
50 putting in user-readable format. This option is useful when
51 sharing output with the developers of Covered for debugging pur‐
52 poses.
53 -D Debug. Display information helpful for debugging tool problems.
55 Note: This option is now only available when covered is built
56 with the --enable-debug configuration option.
57 -h Help. Display this usage information.
59 -P [filename]
61 Profiling mode. Turns on internal source code profiler that
62 will produce a profiling report of the run command to either the
63 specified filename or, if no filename is present, to a file
64 called covered.prof. This option is only available if the
65 --enable-profiling configuration option was specified when Cov‐
66 ered was built.
67 -Q Quiet mode. Causes all output to be suppressed.
69 -v Version. Display current Covered version.
71
73 score Parses Verilog files and VCD/LXT2 dumpfiles to create database
74 file used for merging and reporting.
75 merge Merges two or more database files into one.
77 report Generates human-readable coverage reports from database file or
79 starts the coverage report GUI.
80 rank Generates a report that specifies an ideal order to run regres‐
82 sions and specifies CDD files that do not add new coverage
83 information (and can, therefore, be excluded from regressions,
84 if desired).
85 exclude
87 Allows one or more coverage points (identified with exclusion
88 IDs in a report generated with the -x option) to have their
89 exclusion property toggled (include to exclude or exclude to
90 include) and, if the exclusion property is set to exclude,
91 optionally allow a reason for the exclusion to be associated
92 with it and stored in the specified CDD file.
93
95 The following options are valid for the score command:
96 -A ovl Causes OVL assertions to be used for assertion coverage. This
98 flag must be given to the score command if assertion coverage
99 metrics are needed in the report command.
100 -cdd database
102 Same as the -o option. Useful when CDD file being scored is an
103 input to the score command.
104 -cli [filename]
106 Causes the command-line debugger to be used during VCD/LXT2
107 dumpfile scoring. If filename is specified, this file contains
108 information saved in a previous call to savehist on the CLI and
109 causes the history contained in this file to be replayed prior
110 to the CLI command prompt. If filename is not specified, the
111 CLI prompt will be immediately available at the start of simula‐
112 tion. This option is only available when Covered is configured
113 with the --enable-debug option.
114 -conservative
116 If this option is specified, any logic blocks that contain code
117 that could cause coverage discrepancies leading to potentially
118 inaccurate coverage results are removed from coverage considera‐
119 tion. See User's Guide for more information on what type of
120 code can lead to coverage inaccuracies.
121 -dumpvars [filename]
123 If this option is specified without the -vcd or -lxt options,
124 the design is parsed, a CDD file is created and a top-level Ver‐
125 ilog module file named filename (if this value is specified) or
126 "covered_dump.v" (if filename is not specified) is created.
127 This file is used in the compilation of the simulator to create
128 a dumpfile that is optimized for obtaining coverage for the
129 specified CDD file. If either the -vcd or -lxt options are
130 specified, this option has no effect. See the User's Guide for
131 more information on how to use this option.
132 -D define_name
134 Defines the specified name to 1.
135 -D define_name=value
137 Defines the specified name to the specified value.
138 -e block_name
140 Name of module, task, function or named begin/end block to not
141 score. Causes all subblocks in the Verilog tree under this
142 block to also not be scored.
143 -ea Excludes all always blocks from being considered for coverage.
145 -ec Excludes all continuous assignments from being considered for
147 coverage.
148 -ei Excludes all initial blocks from being considered for coverage.
150 -ef Excludes all final blocks from being considered for coverage.
152 -ep [name]
154 Excludes all code found between '// coverage off' and '// cover‐
155 age on' pragmas embedded within the design. If name is speci‐
156 fied, the keyword in the pragma will be changed to that name
157 instead of the default "coverage", allowing the user to change
158 the look of the pragma if it conflicts with any other tools.
159 -F module_name=[in_expr,]out_expr
161 Indicates to the parser where to find the FSM located in module
162 module_name which has an input state expression called in_expr
163 and output state expression called out_expr. If in_expr is not
164 specified, out_expr is used as both the input and output state
165 expression.
166 -f filename
168 Name of file containing additional arguments to parse.
169 -g [module_name=](1|2|3)
171 Allows the user to limit the parser to a specific generation of
172 the Verilog standard for a specific module or the entire design,
173 where 1=Verilog-1995, 2=Verilog-2001, 3=SystemVerilog. If mod‐
174 ule_name= is specified, the parser uses the specified Verilog
175 standard for that module only, allowing the rest of the design
176 to use the global standard. By default, the global standard is
177 set to the most recent version (3). This option can be speci‐
178 fied more than once for a given call to the score command; how‐
179 ever, if the -g option specifies more than global value (i.e.,
180 without the module= prefix), only the last option value will be
181 used.
182 -h Displays this help information.
184 -I directory
186 Directory to find included Verilog files.
187 -i instance_name
189 Verilog hierarchical reference to the module that is at the top
190 of the tree to be scored. This option is necessary if module to
191 verify coverage is not the top-level module in the design. If
192 not specified, -t value is used.
193 -lxt filename
195 Name of LXT2 dumpfile to score design with. If this or the -vcd
196 option is not used, Covered will only create an initial CDD file
197 from the design and will not attempt to score the design.
198 -m message
200 Allows the user to specify information about this CDD file.
201 This information can be anything (messages with whitespace
202 should be surrounded by double-quotation marks), but may include
203 something about the simulation arguments to more easily link the
204 CDD file to its simulation for purposes of recreating the CDD
205 file.
206 -o database
208 Name of database to write coverage information to. If not spec‐
209 ified, the output database filename will be "cov.cdd".
210 -p filename
212 Overrides default filename used to store intermediate preproces‐
213 sor output.
214 -P parameter_scope=value
216 Performs a defparam on the specified parameter with value.
217 -rS When race condition checks are violated, the offending logic
219 blocks are removed from coverage consideration and all output is
220 suppressed regarding the race condition violation. See user
221 documentation for more information about race condition checking
222 usage.
223 -rW When race condition checks are violated, the offending logic
225 blocks are removed from coverage consideration and the race con‐
226 dition violation is output. This is the default behavior for
227 race condition handling. See user documentation for more infor‐
228 mation about race condition checking usage.
229 -rE When race condition checks are violated, the reason is output
231 and scoring ends immediately. See user documentation for more
232 information about race condition checking usage.
233 -rI[=module name]
235 If module name is not specified, race condition checking is
236 skipped altogether for the entire design. If module name is
237 specified, race condition checking is skipped for the specified
238 module. See user documentation for more information about race
239 condition checking usage.
240 -rP[=name])
242 Uses embedded pragmas for ignoring certain code from race condi‐
243 tion checking consideration (if name is specified it is used as
244 the pragma keyword). See user documentation for more informa‐
245 tion about race condition checking usage.
246 -S Outputs simulation statistics after simulation has completed.
248 This information is currently only useful for the developers of
249 Covered.
250 -t top-level module
252 Specifies the module name of the top-most module that will be
253 measured. Note that this module does not need to be the
254 top-most module in the simulator. This field is required for
255 all calls to the score command.
256 -top_ts timescale
258 This option is only valid when the -vpi or -dumpvars options
259 have been specified. This option allows the user to specify a
260 timescale for the generated Verilog module created with the
261 -vpi/-dumpvars option. If this option is not specified, no
262 timescale will be created for the generated module. The value
263 of timescale is specified as follows:
264 (1|10|100)(s|ms|us|ns|ps|fs)/(1|10|100)(s|ms|us|ns|ps|fs)
266 If whitespace is needed between the various values, place the
268 entire contents of timescale in double quotes.
269 -ts number
271 When scoring occurs, this option allows the user to see how far
272 the simulator has progressed by outputting the current timestep
273 to standard output. The value of number specifies how many
274 timesteps are allowed to be simulated before outputting the cur‐
275 rent timestep (results in less calls to output stream).
276 -T (min|typ|max)
278 Specifies which value to use when encountering a delay expres‐
279 sion in the form: min:typ:max. If this option is not speci‐
280 fied, 'typ' select is used by default.
281 -v filename
283 Name of specific Verilog file to score.
284 -vcd filename
286 Name of VCD dumpfile to score design with. If this or the -lxt
287 option is not used, Covered will only create an initial CDD file
288 from the design and will not attempt to score the design.
289 -vpi [filename]
291 If this option is specified without the -vcd or -lxt options,
292 the design is parsed, a CDD file is created and a top-level Ver‐
293 ilog module file named filename (if this value is specified) or
294 "covered_vpi.v" (if filename is not specified) is created along
295 with a PLI table file called filename.ta b or "covered_vpi.v.ta
296 b". Both of these files are used in the compilation of the sim‐
297 ulator to use Covered as a VPI module. If either the -vcd or
298 -lxt options are specified, this option has no effect.
299 -Wignore
301 Suppress the output of warnings during code parsing and simula‐
302 tion.
303 -y directory
305 Directory to find unspecified Verilog files.
306 +libext+.extension[+.extension]*+
308 Extensions of Verilog files to allow in scoring.
309
311 The following options are valid for the merge command:
312 -d filename
314 Directory to search for CDD files to include. This option is
315 used in conjunction with the -ext option which specifies the
316 file extension to use for determining which files in the direc‐
317 tory are CDD files.
318 -er (first|last|all|new|old)
320 Specifies how to handle exclusion reason resolution. If two or
321 more CDD files being merged have exclusion reasons specified for
322 the same coverage point, the exclusion reason needs to be
323 resolved (unless it is the same string value). If this option
324 is not specified and a conflict is found, Covered will interac‐
325 tively request input for each exclusion as to how to handle it.
326 If this option is specified, it tells Covered how to handle all
327 exclusion reason conflicts. The values are as follows:.br
328 first - CDD file that contained the first exclusion reason is
330 used.
331 last - CDD file that contained the last exclusion reason is
333 used.
334 all - All exclusion reasons are used (concatenated).
336 new - Use the newest exclusion reason specified.
338 old - Use the oldest exclusion reason specified.
340 -ext extension
342 Used in conjunction with the -d option. If no -ext options are
343 specified on the command-line, the default value of '.cdd' is
344 used. Note that a period (.) should be specified.
345 -f filename
347 Name of file containing additional arguments to parse.
348 -h Displays this help information.
350 -m message
352 Allows the user to specify information about this CDD file.
353 This information can be anything (messages with whitespace
354 should be surrounded by double-quotation marks).
355 -o filename
357 File to output new database to. If this argument is not speci‐
358 fied, the existing_database is used as the output database name.
359
361 The following options are valid with the report command:
362 -b If combinational logic verbose output is reported and the
364 expression is a vector operation, this option outputs the cover‐
365 age information on a bitwise basis.
366 -c If -v is specified, displays covered metrics only. Default is
368 to display uncovered information only.
369 -d (s|d|v)
371 Level of detail to provide in coverage report information (s =
372 summary, d = detailed, v = verbose). Default is summary.
373 -e Outputs all excluded coverage points to the report file along
375 with any specified exclusion reasons if the -d d or -d v options
376 are specified.
377 -f filename
379 Name of file containing additional arguments to parse.
380 -h Displays this help information.
382 -i Provides coverage information for instances instead of module.
384 -m [l][t][c][f][r][a][m]
386 Type(s) of metrics to report. l=line, t=toggle, c=combinational
387 logic, f=FSM state and state transition, r=race conditions,
388 a=assertion, m=memory. Default is ltcf.
389 -o filename
391 File to output report information to. Default is standard out‐
392 put.
393 -s Suppresses modules/instances that contain no coverage informa‐
395 tion from being output to the report. Used to help eliminate
396 potentially meaningless information from the report.
397 -v Deprecated. Replaced by '-d d' or '-d v'.
399 -view Starts the GUI interface for interactive coverage reporting.
401 -w (number)
403 Specifies the maximum line width (in characters) that can be
404 used to output Verilog information. If this option is not spec‐
405 ified, all Verilog code in the report will retain the same for‐
406 matting as was specified in the original Verilog code. If this
407 option is specified, Verilog code will be formatted to use as
408 much of the current line as possible, wrapping text when the
409 line reaches the maximum line width. The default maximum line
410 width is 115 characters (this value is used if no number is
411 specified with the -w option). If a number is specified with
412 the -w option, this value is used for the maximum line width.
413 -x Outputs the exclusion IDs of all uncovered and excluded coverage
415 points within parenthesis before the associated verbose output
416 of the coverage point. The exclusion IDs can be used to
417 exclude/include coverage points via the exclude command.
418
420 The following options are valid with the rank command:
421 -d filename
423 Directory to search for CDD files to include. This option is
424 used in conjunction with the -ext option which specifies the
425 file extension to use for determining which files in the direc‐
426 tory are CDD files.
427 -depth number
429 Specifies the minimum number of needed CDD files to hit each
430 coverage point. The value of number should be greater than
431 zero. Default is 1.
432 -ext extension
434 Used in conjunction with the -d option. If no -ext options are
435 specified on the command-line, the default value of '.cdd' is
436 used. Note that a period (.) should be specified.
437 -f filename
439 Name of file containing additional arguments to parse.
440 -h Displays help information for the rank command.
442 -names-only
444 If specified, outputs only the needed CDD filenames that need to
445 be run in the order they need to be run. If this option is not
446 set, a report-style output is provided with additional informa‐
447 tion. This option is meant to be useful in scripts that only
448 want CDD filenames to run as output.
449 -o filename
451 Name of file to output ranking information to. Default is stan‐
452 dard output.
453 -required-cdd filename
455 Name of CDD that should be considered a required CDD to rank
456 (i.e., it cannot be excluded for any reason).
457 -required-list filename
459 Name of a file that contains a list of CDDs that should be con‐
460 sidered required CDDs to rank. The filenames should be sepa‐
461 rated by whitespace or newline characters within the file.
462 -v Causes verbose output to be displayed when the rank command is
464 run. It outputs diagnostic information about each of the dif‐
465 ferent phases of the ranking algorithm including run-time, num‐
466 ber of CDD files included/excluded and number of coverage points
467 hit by ranked CDDs during each phase. This information is meant
468 to be useful for those interested in the ranking algorithm and
469 its performance.
470 -weight-assert number
472 Specifies a relative weighting for assertion coverage used to
473 rank non-unique coverage points. The value of number is rela‐
474 tive to the values used in the -weight-toggle, -weight-memory,
475 -weight-comb, -weight-fsm and -weight-line rank command options.
476 -weight-comb number
478 Specifies a relative weighting for combinational logic coverage
479 used to rank non-unique coverage points. The value of number is
480 relative to the values used in the -weight-toggle, -weight-mem‐
481 ory, -weight-assert, -weight-fsm and -weight-line rank command
482 options.
483 -weight-fsm number
485 Specifies a relative weighting for FSM state and state transi‐
486 tion coverage used to rank non-unique coverage points. The
487 value of number is relative to the values used in the
488 -weight-toggle, -weight-memory, -weight-comb, -weight-assert and
489 -weight-line rank command options.
490 -weight-line number
492 Specifies a relative weighting for line coverage used to rank
493 non-unique coverage points. The value of number is relative to
494 the values used in the -weight-toggle, -weight-memory,
495 -weight-comb, -weight-fsm and -weight-assert rank command
496 options.
497 -weight-memory number
499 Specifies a relative weighting for memory coverage used to rank
500 non-unique coverage points. The value of number is relative to
501 the values used in the -weight-toggle, -weight-line,
502 -weight-comb, -weight-fsm and -weight-assert rank command
503 options.
504 -weight-toggle number
506 Specifies a relative weighting for toggle coverage used to rank
507 non-unique coverage points. The value of number is relative to
508 the values used in the -weight-memory, -weight-line,
509 -weight-comb, -weight-fsm and -weight-assert rank command
510 options.
511
513 The following options are valid with the exclude command:
514 -f filename
516 Specifies the name of a file that contains more options to the
517 exclude command. This option may be specified as many times as
518 necessary for a single call to the exclude command.
519 -h Generates usage information for the exclude command.
521 -m Allows for an exclusion message to be associated with any cover‐
523 age points going from the included state to the excluded state.
524 For each coverage point that meets this requirement, the user
525 will be prompted to input a reason. The reason may be any
526 length and any number of lines; however, all formatting charac‐
527 ters (i.e., newlines, tabs, extra spaces, etc.) will be removed
528 and replaced with a single space when it is later displayed. To
529 end the input of a message, hit a return, enter a single period
530 (.) character and hit return again. The final period character
531 will not be part of the exclusion message.
532 -p Causes all specified coverage points to print their current
534 exclusion status and exclusion reason (if one exists for the
535 excluded coverage point) to standard output. If this option is
536 specified, the -m option will be ignored.
537
540 In addition to using Covered's score command to parse a VCD or LXT2
541 file to abstract coverage information, Covered may also be used as a
542 VPI module within a simulator to extract this information. The advan‐
543 tages to using Covered as a VPI over a dumpfile reader include the fol‐
544 lowing. First, VCD files can be extrememly large, especially for long
545 simulations, using up valuable disk space. Second, if you are using a
546 simulator that dumps files in a different format than VCD or LXT2 and
547 you want to convert these dump file types to one of these versions, the
548 cost of disk space and time can make creating dumpfiles that Covered
549 requires undesirable. Additionally, though using Covered as a VPI mod‐
550 ule will slow down your simulation speed, it is most likely that the
551 total time spent simulating your design and scoring the design in one
552 step will be shorter than doing so in two steps. As a result, Cov‐
553 ered's configure utility can generate VPI-ready libraries for the fol‐
554 lowing free and commercial simulators (Icarus Verilog, CVER and VCS).
555 To automatically build the VPI-ready library files when generating Cov‐
557 ered from source, simply specify one or more of the following when run‐
558 ning the "configure" utility in the base Covered directory:
559 --with-iv=<Icarus Verilog install path>, --with-vcs=<VCS include path>,
560 --with-cver=<CVER include path>. After Covered has been configured,
561 simply type 'make' and 'make install'. This will install the VPI-ready
562 library files in the installation libexec directory (by default this
563 path will be /usr/libexec).
564 Before you are ready to compile the design, you must first create a CDD
566 file, a top-level Verilog file, and a PLI table file (the last file is
567 only needed for the VCS compiler). This is done by specifying the -vpi
568 (filename) option to Covered's score command. If no filename is speci‐
569 fied after -vpi, the files covered_vpi.v and covered_vpi.ta b will be
570 created along with the generated coverage file. Note that this step
571 only needs to be performed once unless the design files change. You
572 are now ready to compile the simulator.
573 If you are compiling an Icarus Verilog simulation, simply add '-m
575 /usr/libexec/covered.vpi covered_vpi.v' to the 'iverilog' command-line.
576 Once compilation is complete, run the generated executable file as you
577 normally would.
578 If you are compiling a CVER simulation, simply add '+load‐
580 vpi=/usr/libexec/covered.cver.so:vpi_compat_bootstrap covered_vpi.v' to
581 the 'cver' command-line.
582 If you are compiling a VCS simulation, simply add '+vpi -load
584 /usr/libexec/covered.vcs.so:covered_register covered_vpi.v' to the
585 'vcs' command-line. Once compilation is complete, run the generated
586 executable file as you normally would.
587 There are two plusargs that can be passed to the generated executable
589 when it is run that Covered will parse. The '+covered_cdd=<filename>'
590 option will cause Covered to output the scored design contents to the
591 CDD file specified by <filename>. This allows multiple runs of the
592 simulator to generate several different CDD files without needed a
593 recompile to occur. The '+covered_debug' option will cause Covered to
594 dump a lot of excessive output about its internal run-time state during
595 simulation. This output will only be generated if Covered was config‐
596 ured with the --enable-debug option. This plusarg option should not be
597 used by regular users as it is primarily intended to aid the developers
598 of Covered in debugging.
599
601 Trevor Williams <phase1geo@gmail.com>
602
604 For more information on how to use the Covered code coverage tool,
605 please consult the User's Guide included with this release at
606 /usr/share/covered/doc/html/index.html.
607Trevor Williams covered-0.7.7 Covered(1)