Verilator Coverage Import

PyUCIS provides built-in support for importing coverage data from Verilator, enabling seamless integration of Verilator verification results into the UCIS ecosystem.

Overview

The Verilator coverage import feature (vltcov format) supports:

  • Functional Coverage: Covergroups, coverpoints, and bins with hit counts

  • Code Coverage: Line, branch, and toggle coverage

  • File Format: SystemC::Coverage-3 format (.dat files)

  • Output Formats: Convert to XML, SQLite, YAML, or any UCIS format

  • CLI Integration: Works with all PyUCIS commands (convert, merge, report)

Coverage Types Supported

Functional Coverage (Full Support)

  • Covergroups: SystemVerilog covergroups with complete hierarchy

  • Coverpoints: Individual coverage points within covergroups

  • Bins: Coverage bins with hit counts and thresholds

  • Source Locations: File names and line numbers preserved

Code Coverage (Full Support)

  • Line Coverage: Statement execution tracking

  • Branch Coverage: Conditional branch tracking

  • Toggle Coverage: Signal toggle tracking

Quick Start

Command Line Usage

Convert Verilator coverage to UCIS XML:

pyucis convert --input-format vltcov coverage.dat --out output.xml

Convert to SQLite database:

pyucis convert --input-format vltcov --output-format sqlite \
       coverage.dat --out coverage.ucisdb

Merge multiple Verilator runs:

pyucis merge --input-format vltcov run1.dat run2.dat run3.dat --out merged.xml

Generate HTML report:

pyucis convert --input-format vltcov coverage.dat --out temp.xml
pyucis report temp.xml -of html -o report.html

Python API

Import Verilator coverage using the format registry:

from ucis.rgy.format_rgy import FormatRgy

# Get format registry and vltcov interface
rgy = FormatRgy.inst()
desc = rgy.getDatabaseDesc('vltcov')
fmt_if = desc.fmt_if()

# Import Verilator coverage
db = fmt_if.read('coverage.dat')

# Export to XML
db.write('output.xml')
db.close()

Verilator Coverage Format

Verilator generates coverage data in the SystemC::Coverage-3 text format:

  • File Extension: .dat

  • Format: Text-based with compact key-value encoding

  • Delimiters: Uses ASCII control characters (\001 and \002)

  • Location: Generated in simulation output directory

Example Verilator coverage entry:

C '\001t\002funccov\001page\002v_funccov/cg1\001f\002test.v\001l\00219\001bin\002low\001h\002cg1.cp\001' 42

This decodes to:

  • Type: Functional coverage

  • Covergroup: cg1

  • File: test.v, line 19

  • Bin: low

  • Hit count: 42

Generating Verilator Coverage

Enable coverage in your Verilator simulation:

# Enable functional coverage
verilator --coverage --coverage-func --coverage-line -cc design.v

# Run simulation (generates coverage.dat)
make -C obj_dir -f Vdesign.mk
./obj_dir/Vdesign

# Import into PyUCIS
pyucis convert --input-format vltcov coverage.dat --out coverage.xml

Workflow Examples

Basic Workflow

# 1. Run Verilator simulation with coverage
verilator --coverage --coverage-func design.v testbench.cpp
make -C obj_dir -f Vdesign.mk
./obj_dir/Vdesign  # Generates coverage.dat

# 2. Convert to UCIS
pyucis convert --input-format vltcov coverage.dat --out coverage.xml

# 3. Generate report
pyucis report coverage.xml -of html -o report.html

Regression Testing

Merge coverage from multiple test runs:

# Run multiple tests (each generates coverage.dat)
./run_test1.sh  # → test1/coverage.dat
./run_test2.sh  # → test2/coverage.dat
./run_test3.sh  # → test3/coverage.dat

# Merge all coverage
pyucis merge --input-format vltcov \
       test1/coverage.dat test2/coverage.dat test3/coverage.dat \
       --out merged.ucisdb --output-format sqlite

# Analyze merged results
pyucis show summary merged.ucisdb
pyucis show gaps merged.ucisdb

CI/CD Integration

Export Verilator coverage to CI-friendly formats:

# Convert to SQLite for querying
pyucis convert --input-format vltcov coverage.dat \
       --output-format sqlite --out coverage.ucisdb

# Export to LCOV for CI tools
pyucis show code-coverage coverage.ucisdb --output-format lcov > coverage.info

# Export to Cobertura for Jenkins/GitLab
pyucis show code-coverage coverage.ucisdb --output-format cobertura > coverage.xml

Advanced Usage

Selective Import

Filter coverage during import:

from ucis.rgy.format_rgy import FormatRgy
from ucis.vltcov import VltParser

# Parse Verilator file
parser = VltParser()
items = parser.parse_file('coverage.dat')

# Filter to functional coverage only
func_items = [item for item in items if item.is_functional_coverage()]

# Build custom database
# ... (map filtered items to UCIS)

Integration with PyUCIS Features

Use all PyUCIS capabilities with imported Verilator coverage:

# Analyze coverage
pyucis show summary coverage.dat --input-format vltcov
pyucis show gaps coverage.dat --input-format vltcov
pyucis show covergroups coverage.dat --input-format vltcov

# Compare runs
pyucis show compare baseline.dat current.dat --input-format vltcov

# Export to various formats
pyucis show code-coverage coverage.dat --input-format vltcov \
       --output-format jacoco > jacoco.xml

Implementation Details

Architecture

The Verilator import implementation consists of:

  1. VltParser - Parses SystemC::Coverage-3 format

  2. VltCoverageItem - Data structure for coverage entries

  3. VltToUcisMapper - Maps Verilator data to UCIS hierarchy

  4. DbFormatIfVltcov - Format interface for PyUCIS registry

The import process:

Verilator .dat file
       ↓
VltParser (parse format)
       ↓
VltCoverageItem list
       ↓
VltToUcisMapper (build UCIS)
       ↓
UCIS Database (MemUCIS)
       ↓
Export (XML, SQLite, etc.)

Source Code

The implementation is in src/ucis/vltcov/:

  • vlt_parser.py - Format parser

  • vlt_coverage_item.py - Data structures

  • vlt_to_ucis_mapper.py - UCIS mapping

  • db_format_if_vltcov.py - Format interface

Limitations

Current Limitations

  • Read-Only: Import only (no export to Verilator format)

  • Memory: Large coverage files loaded entirely into memory during parsing

These limitations do not affect typical usage and may be addressed in future releases.

Troubleshooting

Common Issues

“Unknown format: vltcov”

Ensure PyUCIS is properly installed: pip install -e .

Import fails with parsing error

Verify the file is a valid Verilator coverage file (should start with 'SystemC::Coverage-3`)

Missing coverage data

Check that Verilator was run with appropriate coverage flags (--coverage, --coverage-func)

Empty output database

Ensure the input .dat file contains coverage data (not just headers)

See Also

References