Covered(1)

📦
version 0.7.10 · 2 versions
  • 0.7.10 · debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 0.7.10 · ubuntu jammy
, in debian trixie, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 Covered(1) 🎀

okay so this is the manual page for Covered, and yes the (1) is doing its little section-number thing. it's a Verilog Code Coverage Analyzer and honestly? she's iconic. let's get into it 💅

✨ NAME ✨

Covered — Verilog Code Coverage Analyzer

🌸 SYNTAX 🌸

here's how you actually call her, no cap:

covered [global_options] score [options]
covered [global_options] merge [options] existing_database
database_to_merge+
covered [global_options] report [options] database_file
covered [global_options] rank [options] database_to_rank
database_to_rank+
covered [global_options] exclude [options] exclusion_id+ database_file

💖 DESCRIPTION 💖

so, bestie, Covered is a Verilog code coverage analysis tool. her whole vibe is figuring out how well your diagnostic test suite is actually covering the design under test. like, are your tests pulling their weight or are they just standing there? 🫶

here's the tea on how it flows. Covered reads in your Verilog design files plus a VCD, LXT2 or FST formatted dumpfile from a diagnostic run, and then generates a database file called a Coverage Description Database (CDD) file — that's the score command doing its thing.

but wait, there's more. Covered's score command can also be used to generate a CDD file and a Verilog module, so you can use Covered as a VPI module in a testbench. that lets you grab coverage information in parallel with simulation. iykyk — full details live in USING COVERED AS A VPI MODULE down below.

once you've got that CDD file, you can merge it with other CDD files from the same design to build up accummulated coverage — that's the merge command. ✨

and once a CDD file exists? the world is your oyster, literally:

  • generate various human-readable coverage reports in an ASCII format
  • or open Covered's GUI and interactively poke around your coverage results

both of those are the report command.

if you find uncovered coverage points that you just don't care about and want excluded from coverage, you've got two options: the command-line exclude command, or doing it inside the GUI. easy.

now here's where it gets good. when you've got multiple CDD files from the same design, you can get a coverage ranking of them with the rank command. that tells you an ideal order for regression testing, and also shows you which CDD files can be excluded from regressions entirely because they literally cannot hit any new coverage points. main character energy for your regression suite, honestly.

oh and one more thing — as part of Covered's score command, race condition possibilities get found in the design files. you get to choose how Covered treats them:

  • ignore them
  • flag them as warnings
  • flag them as errors
and yeah — if you set race conditions as errors, Covered doubles as a race condition checker. periodt. 👑

🦋 GLOBAL OPTIONS 🦋

these go immediately after the keyword covered on the command-line. they work for any command — the only exceptions are -v and -h — and they do the same exact thing every single time.

  • -B — Obfuscate. Obfuscates all design-sensitive names before outputting in user-readable format. super useful when you want to share output with the developers of Covered for debugging purposes but you don't wanna leak your design names. 🕵️
  • -D — Debug. Displays information helpful for debugging tool problems. Note: this option is now only available when covered is built with the --enable-debug configuration option.
  • -h — Help. Displays this usage information.
  • -P [filename] — Profiling mode. Turns on the internal source code profiler, which produces a profiling report of the run command to either the specified filename or — if no filename is given — to a file called covered.prof. this one's only available if the --enable-profiling configuration option was specified when Covered was built.
  • -Q — Quiet mode. Causes all output to be suppressed.
  • -T — Terse mode. Causes all output to be suppressed with the exception of warning messages and the Covered header information.
  • -v — Version. Displays the current Covered version.

🌈 COMMANDS 🌈

  • score — Parses Verilog files and VCD/LXT2/FST dumpfiles to create the database file used for merging and reporting.
  • merge — Merges two or more database files into one.
  • report — Generates human-readable coverage reports from a database file, or starts the coverage report GUI.
  • rank — Generates a report that specifies an ideal order to run regressions and specifies CDD files that do not add new coverage information. those ones can therefore be excluded from regressions, if you want.
  • exclude — Allows one or more coverage points (identified with exclusion IDs in a report generated with the -x option) to have their exclusion property toggled — include to exclude, or exclude to include. and if the exclusion property is set to exclude, you can optionally attach a reason for the exclusion to it, stored right there in the specified CDD file. 💜

🎯 SCORE COMMAND 🎯

okay bestie, deep breath, this is the big one 💅 the score command has its own whole wardrobe of options, and you're gonna want to know every single one of them. No skipping, no skimming, we go through them all together, fr fr.

these options are only valid for the score command — don't go throwing them at other commands and wondering why the vibe is off 🫶
  • -A ovl — turns on OVL assertions for assertion coverage. And listen, this flag is mandatory if you want assertion coverage metrics to show up later in the report command, so don't forget it. Periodt.
  • -cdd database — literally the same thing as -o. It's here because sometimes the CDD file you're scoring is itself an input to the score command, and this is just the friendlier way to say it. Same energy, different door. 🚪
  • -cli [filename] — brings up the command-line debugger while you're scoring a VCD/LXT2/FST dumpfile. If you hand it a filename, that file holds info saved from a previous savehist call on the CLI, and the history inside gets replayed before the CLI command prompt even shows up. Skip the filename and the CLI prompt is just... immediately there at the start of simulation. 😌 Heads up though: this option only exists if Covered was configured with the --enable-debug option.
  • -conservative — picks up any logic blocks containing code that could cause coverage discrepancies (aka potentially inaccurate coverage results 😬) and yeets them right out of coverage consideration. The User's Guide has the full tea on which kinds of code lead to coverage inaccuracies.
  • -dumpvars [filename] — if you use this without -vcd or -lxt, Covered parses the design, makes a CDD file, and creates a top-level Verilog module file named filename (if you gave it one) or "covered_dump.v" (if you didn't 🙈). That file gets used when compiling the simulator to build a dumpfile that's optimized for pulling coverage out of the specified CDD file. If either -vcd or -lxt is specified, this option does absolutely nothing. User's Guide has more on how to actually use this one.
  • -D define_name — defines that name to 1. Simple as. ✨
  • -D define_name=value — defines that name to the value you specified. Same flag, upgraded fit. 💅
  • -e block_name — name of a module, task, function, or named begin/end block that you do not want scored. And it's thorough about it: every subblock in the Verilog tree underneath this block also gets skipped. 🚫
  • -ea — excludes all always blocks from being considered for coverage.
  • -ec — excludes all continuous assignments from being considered for coverage.
  • -ei — excludes all initial blocks from being considered for coverage.
  • -ef — excludes all final blocks from being considered for coverage.
  • -ep [name] — excludes every bit of code sitting between '// coverage off' and '// coverage on' pragmas buried in the design. If you pass a name, the keyword in the pragma becomes that name instead of the default "coverage" — super handy if your pragma is beefing with some other tool and you want it to look different. 🏷️
  • -F module_name=[in_expr,]out_expr — tells the parser where to find the FSM living in module module_name, which has an input state expression called in_expr and an output state expression called out_expr. If you don't give it in_expr, then out_expr gets used as both the input and the output state expression. Two jobs, one icon. 👑
  • -f filename — name of the file holding extra arguments to parse.
  • -fst filename — name of the FST dumpfile to score the design with. And here's the plot twist: if -vcd, -lxt, or this option isn't used, Covered will only create an initial CDD file from the design and won't even try to score it. 😭
  • -g [module_name=](1|2|3) — lets you pin the parser to a specific generation of the Verilog standard, either for one specific module or for the whole entire design, where 1=Verilog-1995, 2=Verilog-2001, 3=SystemVerilog. Pass module_name= and the parser uses that standard just for that module, letting the rest of the design roll with the global standard. By default the global standard is set to the most recent version, which is 3. You can specify this option more than once in a single score call — but if -g specifies more than one global value (i.e., without the module= prefix), only the last option value survives. Only the last one. That's the rule. 🫡
  • -h — displays this help information. The classic. 💖
  • -I directory — directory to go find included Verilog files in.
  • -i instance_name — a Verilog hierarchical reference to the module at the top of the tree you're scoring. This one is necessary if the module you want to verify coverage on isn't the top-level module of the design. If you don't specify it, the -t value gets used instead.
  • -lxt filename — name of the LXT2 dumpfile to score the design with. If -vcd, -fst, or this option isn't used, Covered only creates an initial CDD file from the design and does not attempt to score it. Same tragic ending as before. 🙈
  • -m message — lets you drop info about this CDD file. It can be anything at all (if your message has whitespace, wrap it in double-quotation marks, bestie), but a great use is jotting down the simulation arguments so you can easily link the CDD file back to its simulation when you need to recreate it. Receipts for your future self. 🧾
  • -o database — name of the database to write coverage information to. Don't specify it and the output database filename defaults to "cov.cdd".
  • -p filename — overrides the default filename used to store intermediate preprocessor output.
  • -P parameter_scope=value — performs a defparam on the specified parameter with value.
  • -rS — when race condition checks get violated, the offending logic blocks are removed from coverage consideration and all output regarding the race condition violation is suppressed. User documentation has more on race condition checking usage.
  • -rW — when race condition checks get violated, the offending logic blocks are removed from coverage consideration and the race condition violation is output. This is the default behavior for race condition handling. User documentation has more on race condition checking usage.
  • -rE — when race condition checks get violated, the reason gets output and scoring ends immediately. Dramatic? Yes. Intentional? Also yes. User documentation has more on race condition checking usage.
  • -rI[=module name] — if module name isn't specified, race condition checking is skipped entirely for the whole design. If module name is specified, race condition checking is skipped for that module only. User documentation has more on race condition checking usage.
  • -rP[=name]) — uses embedded pragmas to ignore certain code from race condition checking consideration (and if name is specified, it becomes the pragma keyword). User documentation has more on race condition checking usage.
  • -S — outputs simulation statistics once simulation has completed. ngl, this info is currently only useful for the developers of Covered. 👩‍💻
  • -t top-level module — specifies the module name of the top-most module that will be measured. Note that this module does not need to be the top-most module in the simulator. This field is required for every single call to the score command. Every one. No exceptions. ⚠️
  • -top_ts timescale — only valid when the -vpi or -dumpvars options have been specified. It lets you set a timescale for the generated Verilog module created by -vpi/-dumpvars. Skip it and no timescale gets created for the generated module. The value of timescale looks like this:
(1|10|100)(s|ms|us|ns|ps|fs)/(1|10|100)(s|ms|us|ns|ps|fs)

If you need whitespace between the various values, wrap the entire contents of timescale in double quotes. 🎀

  • -ts number — during scoring, this lets you watch how far the simulator has progressed by outputting the current timestep to standard output. The number value says how many timesteps are allowed to be simulated before it outputs the current timestep (which means fewer calls to the output stream). Progress bar energy, but make it text. 📈
  • -T (min|typ|max) — specifies which value to use when the parser runs into a delay expression shaped like min:typ:max. Don't specify it and 'typ' is selected by default.
  • -v filename — name of the specific Verilog file to score.
  • -vcd filename — name of the VCD dumpfile to score the design with. If -lxt, -fst, or this option isn't used, Covered will only create an initial CDD file from the design and will not attempt to score the design. You know the drill by now. 🫠
  • -vpi [filename] — if you use this without the -vcd, -lxt, or -fst options, the design gets parsed, a CDD file is created, and a top-level Verilog module file named filename (if you gave one) or "covered_vpi.v" (if you didn't) is created — plus a PLI table file called filename.ta b or "covered_vpi.v.ta b". Both of these files get used when compiling the simulator so Covered can run as a VPI module. If either -vcd, -lxt, or -fst is specified, this option has no effect. ✨
  • -Wignore — suppresses the output of warnings during code parsing and simulation. Peace and quiet, finally. 🤫
  • -y directory — directory to go find unspecified Verilog files in.
  • +libext+.extension[+.extension]*+ — the extensions of Verilog files to allow in scoring.

✨ MERGE COMMAND ✨

okay bestie, these are the options that actually do something for the merge command:

  • -d filename — the directory we're gonna dig through looking for CDD files to pull in. this one is a duo with -ext, which tells us what file extension counts as a CDD file so we know which ones in that directory are the real deal.
  • -er (first|last|all|new|old) — this one sets how we handle exclusion reason resolution. here's the tea: if two or more CDD files being merged both have exclusion reasons for the same coverage point, somebody's gotta settle that conflict (unless the strings are literally identical, in which case, no drama). if you don't specify this option and a conflict pops up, Covered will stop and interactively ask you what to do for each and every exclusion, one by one 😭. but if you do specify it, you're telling Covered how to handle all of those conflicts at once. the values are:
    • first — the CDD file that had the first exclusion reason wins.
    • last — the CDD file that had the last exclusion reason wins.
    • all — every exclusion reason gets used, all concatenated together.
    • new — use the newest exclusion reason specified.
    • old — use the oldest exclusion reason specified.
  • -ext extension — works together with -d. if you don't hand it any -ext options on the command line, it defaults to '.cdd'. heads up: you gotta include the period (.) in there, bestie.
  • -f filename — name of a file that has extra arguments in it for us to parse.
  • -h — shows this help info. the classic.
  • -m message — lets you drop info about this CDD file. it can be literally anything, but if your message has whitespace in it you gotta wrap it in double-quotation marks.
  • -o filename — the file to output the new database to. if you don't pass this, the existing_database gets used as the output database name instead.

🌸 REPORT COMMAND 🌸

these options are the valid ones for the report command:

  • -b — if combinational logic verbose output is being reported and the expression is a vector operation, this option gives you the coverage info on a bitwise basis. one bit at a time, slay.
  • -c — if -v is specified, this shows covered metrics only. default behaviour is to show uncovered info only.
  • -d (s|d|v) — how much detail you want in the coverage report info (s = summary, d = detailed, v = verbose). default is summary.
  • -e — outputs all excluded coverage points into the report file, along with any specified exclusion reasons — but only if -d d or -d v is specified.
  • -f filename — name of a file containing additional arguments to parse.
  • -h — displays this help information.
  • -i — gives you coverage information for instances instead of module. switch up the vibe ✨
  • -m [l][t][c][f][r][a][m] — which type(s) of metrics to report: l=line, t=toggle, c=combinational logic, f=FSM state and state transition, r=race conditions, a=assertion, m=memory. default is ltcf.
  • -o filename — the file to output report information to. default is standard output.
  • -s — suppresses modules/instances that have zero coverage information so they don't get output to the report. this is the "please stop showing me meaningless stuff" option, and honestly? valid.
  • -v — deprecated. it's been replaced by '-d d' or '-d v'. do not use it, bestie, it's giving old news.
  • -view — starts up the GUI interface for interactive coverage reporting. pretty ✨
  • -w (number) — sets the maximum line width (in characters) that can be used when outputting Verilog information. if you don't specify this, all Verilog code in the report keeps the exact same formatting it had in the original Verilog code. if you do specify it, Verilog code gets formatted to use as much of the current line as possible, wrapping text once the line hits the max width. the default maximum line width is 115 characters — and yes, that default kicks in if you pass -w with no number. if you do give it a number, that number becomes the max line width.
  • -x — outputs the exclusion IDs of all uncovered and excluded coverage points, inside parenthesis, right before the associated verbose output of the coverage point. those exclusion IDs are what you use to exclude/include coverage points through the exclude command. very handy, iykyk 💅

👑 RANK COMMAND 👑

these options are valid with the rank command:

  • -d filename — directory to search for CDD files to include. pairs up with -ext, which says which file extension to use to figure out which files in that directory are CDD files.
  • -depth number — the minimum number of needed CDD files to hit each coverage point. number should be greater than zero. default is 1.
  • -ext extension — used together with -d. if no -ext options are given on the command line, the default value '.cdd' is used. reminder: include the period (.)!
  • -f filename — name of a file containing additional arguments to parse.
  • -h — displays help information for the rank command.
  • -names-only — if set, outputs only the needed CDD filenames that need to be run, in the order they need to be run. if it's not set, you get a report-style output with extra info instead. this option exists so scripts that just want CDD filenames to run as output can have exactly that. iconic for automation 🫶
  • -o filename — name of the file to output ranking information to. default is standard output.
  • -required-cdd filename — name of a CDD that should be treated as a required CDD to rank, meaning it cannot be excluded for any reason. no take-backs.
  • -required-list filename — name of a file holding a list of CDDs that should be treated as required CDDs to rank. the filenames inside that file should be separated by whitespace or newline characters.
  • -v — makes verbose output show up when the rank command runs. it spits out diagnostic info about each of the different phases of the ranking algorithm, including run-time, number of CDD files included/excluded, and number of coverage points hit by ranked CDDs during each phase. this is for the algorithm girlies who care about the ranking algorithm and how it performs 💜
  • -weight-assert number — a relative weighting for assertion coverage, used to rank non-unique coverage points. number is relative to the values used in the -weight-toggle, -weight-memory, -weight-comb, -weight-fsm and -weight-line rank command options.
  • -weight-comb number — a relative weighting for combinational logic coverage, used to rank non-unique coverage points. number is relative to the values used in the -weight-toggle, -weight-memory, -weight-assert, -weight-fsm and -weight-line rank command options.
  • -weight-fsm number — a relative weighting for FSM state and state transition coverage, used to rank non-unique coverage points. number is relative to the values used in the -weight-toggle, -weight-memory, -weight-comb, -weight-assert and -weight-line rank command options.
  • -weight-line number — a relative weighting for line coverage, used to rank non-unique coverage points. number is relative to the values used in the -weight-toggle, -weight-memory, -weight-comb, -weight-fsm and -weight-assert rank command options.
  • -weight-memory number — a relative weighting for memory coverage, used to rank non-unique coverage points. number is relative to the values used in the -weight-toggle, -weight-line, -weight-comb, -weight-fsm and -weight-assert rank command options.
  • -weight-toggle number — a relative weighting for toggle coverage, used to rank non-unique coverage points. number is relative to the values used in the -weight-memory, -weight-line, -weight-comb, -weight-fsm and -weight-assert rank command options.

🎀 EXCLUDE COMMAND 🎀

these are the options valid with the exclude command:

  • -f filename — name of a file that contains more options for the exclude command. you can pass this one as many times as you need within a single call to the exclude command. go off.
  • -h — generates usage information for the exclude command.
  • -m — lets you attach an exclusion message to any coverage points going from the included state to the excluded state. for each coverage point that meets that requirement, you'll be prompted to type in a reason. the reason can be any length and any number of lines — BUT, important: all formatting characters (newlines, tabs, extra spaces, etc.) get stripped out and replaced with a single space when it's later displayed. to end your message input, hit return, type a single period (.) character, and hit return again. that final period does not become part of the exclusion message.
  • -p — causes all specified coverage points to print their current exclusion status and exclusion reason (if one exists for that excluded coverage point) to standard output. if you specify this option, the -m option gets ignored. sorry -m, it's not your moment.

🦋 USING COVERED AS A VPI MODULE 🦋

Okay bestie, so listen — this is the glow-up mode. 💅 Normally you let Covered's score command chew through a VCD, LXT2 or FST file and pull the coverage tea out of it that way. But plot twist: Covered can also slide in as a VPI module inside your simulator and grab all that info live. Living rent-free in the simulator, iconic behaviour honestly. 👑

So why would you even do that? Reasons, bestie, reasons:

  • VCD files can get extremely large, especially for long simulations, and they will eat your disk space for breakfast. 😭
  • If your simulator dumps files in a format that isn't VCD, LXT2 or FST, and you wanna convert those dump file types into one of those versions, the disk space and time cost can make creating the dumpfiles that Covered needs just… not it. 🚫
  • And yeah, using Covered as a VPI module will slow down your simulation speed — that part's real — but the total time spent simulating your design and scoring it in one single step will most likely be shorter than doing it in two separate steps. Math is mathing. ✨

So as a result, Covered's configure utility can generate VPI-ready libraries for these free and commercial simulators:

  • Icarus Verilog
  • CVER
  • VCS

🎀 Building the VPI-ready libraries 🎀

Wanna build these library files automatically when you're generating Covered from source? Say less. Just specify one or more of the following when you run the configure utility in the base Covered directory:

  • --with-iv=<Icarus Verilog install path> — point at your Icarus Verilog install path
  • --with-vcs=<VCS include path> — point at your VCS include path
  • --with-cver=<CVER include path> — point at your CVER include path

Then, once Covered has been configured, you literally just type:

make
make install

That installs the VPI-ready library files into the installation libexec directory — and by default that path is /usr/local/libexec. Slay.

🧚 Before you compile the design 🧚

Before you're ready to compile the design, you gotta create three things first:

  1. a CDD file
  2. a top-level Verilog file
  3. a PLI table file — ngl this one is only needed for the VCS compiler

And how do you make them? By passing the -vpi (filename) option to Covered's score command. If you don't specify a filename after -vpi, then covered_vpi.v and covered_vpi.tab get created alongside the generated coverage file. 🫶

Heads up bestie: this step only needs to be performed once unless your design files change. Then you're ready to compile the simulator. Periodt.

🌈 Compiling per simulator 🌈

Icarus Verilog

If you're compiling an Icarus Verilog simulation, simply add this to the iverilog command-line:

-m /usr/local/libexec/covered.vpi covered_vpi.v

Once compilation is complete, run the generated executable file as you normally would. Easy. 💖

CVER

If you're compiling a CVER simulation, simply add this to the cver command-line:

+loadvpi=/usr/local/libexec/covered.cver.so:vpi_compat_bootstrap covered_vpi.v

VCS

If you're compiling a VCS simulation, simply add this to the vcs command-line:

+vpi -load /usr/local/libexec/covered.vcs.so:covered_register covered_vpi.v

Once compilation is complete, run the generated executable file as you normally would. 💅

NC-Verilog

If you're compiling an NC-Verilog simulation, switch to NC-Verilog's irun command to load the covered shared object:

-loadvpi /usr/local/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

👑 The two plusargs 👑

There are two plusargs you can pass to the generated executable when it's run, and Covered will parse them:

  • +covered_cdd=<filename> — this makes Covered output the scored design contents to the CDD file you named in <filename>. This is the whole point, bestie: it lets multiple runs of the simulator generate several different CDD files without needing a recompile to occur. Chef's kiss. 😘
  • +covered_debug — this makes Covered dump a lot of excessive output about its internal run-time state during simulation. This output will only be generated if Covered was configured with the --enable-debug option.
🚨 Real talk: the +covered_debug plusarg should not be used by regular users, because it's primarily intended to aid the developers of Covered in debugging. It's giving backstage pass, not main character energy for you. 🙈

💜 AUTHORS 💜

  • Trevor Williams <phase1geo@gmail.com>

🌸 SEE ALSO 🌸

For more information on how to use the Covered code coverage tool, please consult the User's Guide included with this release at /usr/local/share/covered/doc/html/index.html. 📖

And that's a wrap on the whole page, bestie!! 🎉 This was written by Trevor Williams, it's for covered-0.7.10, and the man page is dated for the Covered(1) release. Go get that coverage, you absolute icon. 🦋💖✨

📦 where this page comes from