Introduction

What is PyUCIS?

The Accellera Unified Coverage Interoperability Standard (UCIS) specifies a data model, C API, and XML interchange format for coverage metrics data. The PyUCIS library provides two APIs for creating and accessing coverage data via the UCIS data model:

An object-oriented Python API
A functional C-style Python API that is identical to the API defined in the Accellera standard

The PyUCIS library supports multiple back-ends for storing and accessing coverage data:

In-Memory: Fast transient data model stored in RAM
SQLite: Persistent, queryable storage using SQLite3 databases
XML: Read and write UCIS data in the Accellera-defined interchange format
YAML: Human-readable text format for coverage data
Verilator: Import coverage from Verilator (SystemC::Coverage-3 format)
cocotb-coverage: Import functional coverage from cocotb-coverage (XML/YAML)
AVL: Import functional coverage from AVL - Apheleia Verification Library (JSON)
Library: Call tool-provided implementations of the UCIS C API

SQLite Backend

The SQLite backend is a powerful option for persistent coverage storage:

Persistent Storage - Coverage data saved directly to .ucisdb files
SQL Queries - Direct database access for custom analysis
Large Databases - Efficient handling of very large coverage datasets
Native C Library - High-performance UCIS 1.0 C API implementation

Quick example using SQLite:

from ucis.sqlite import SqliteUCIS
from ucis.scope_type_t import ScopeTypeT
from ucis.source_t import SourceT

# Create or open database
db = SqliteUCIS("coverage.ucisdb")

# Build hierarchy
top = db.createScope("top", None, 1, SourceT.NONE,
                    ScopeTypeT.INSTANCE, 0)

# Create covergroup
cg = top.createCovergroup("addr_cg", None, 1, SourceT.NONE)

# Close database
db.close()

See SQLite Backend API for complete SQLite API documentation.

Object-Oriented API Example

Here is an example using the in-memory backend with the object-oriented Python API:

from ucis.mem import MemFactory
from ucis.history_node_kind import HistoryNodeKind
from ucis.test_status_t import TestStatusT
from ucis.source_t import SourceT
from ucis.source_info import SourceInfo
from ucis.test_data import TestData

# Create in-memory database
db = MemFactory.create()

testnode = db.createHistoryNode(
    None,
    "logicalName",
    "test.sv",
    HistoryNodeKind.TEST)
td = TestData(
    teststatus=TestStatusT.OK,
    toolcategory="UCIS:simulator",
    date="20200202020"
    )
testnode.setTestData(td)

file = db.createFileHandle("dummy.v", os.getcwd())

srcinfo = SourceInfo(file, 0, 0)
du = db.createScope(
    "foo.bar",
    srcinfo,
    1, # weight
    SourceT.VLOG,
    ScopeTypeT.DU_MODULE,
    0  # flags
    )

instance = db.createInstance(
    "dummy",
    None, # sourceinfo
    1, # weight
    SourceT.VLOG,
    ScopeTypeT.INSTANCE,
    du,
    0)  # flags

cg = instance.createCovergroup(
    "cg",
    SourceInfo(file, 3, 0),
    1, # weight
    SourceT.VLOG)

cp = cg.createCoverpoint(
    "t",
    SourceInfo(file, 4, 0),
    1, # weight
    SourceT.VLOG
    )
cp.setComment("Hello There")

cp.createBin(
    "auto[a]",
    SourceInfo(file, 4, 0),
    1,
    4,
    "a")

db.write("output.xml", None, True, -1)
db.close()

Command-Line Tools

PyUCIS includes comprehensive command-line tools for coverage analysis and reporting. The ucis command provides several operations:

Interactive Terminal UI (New!)

Real-time coverage exploration with a keyboard-driven interface:

5 specialized views: Dashboard, Hierarchy, Gaps, Hotspots, Metrics
Color-coded indicators: Quick visual assessment of coverage levels
Smart prioritization: Built-in hotspot analysis for test planning
SSH-friendly: Works perfectly in remote terminal sessions
Fast navigation: Keyboard shortcuts for efficient browsing

See Interactive Terminal UI for complete TUI documentation.

Show Commands (New!)

Extract and analyze coverage data with support for multiple output formats:

12 analysis commands: summary, gaps, covergroups, bins, tests, hierarchy, metrics, compare, hotspots, code-coverage, assertions, toggle
4 export formats: LCOV, Cobertura, JaCoCo, Clover
CI/CD integration: Works with Jenkins, GitLab CI, GitHub Actions, SonarQube, and more
JSON & text output: Machine-readable and human-readable formats

See Show Commands Reference for detailed documentation.

Merge

Combine multiple coverage databases into a single unified database

Convert

Convert between different UCIS database formats (XML, YAML, Verilator, LibUCIS)

Report

Generate coverage reports from UCIS databases in multiple formats:

HTML - Interactive single-file report with charts, bin details, and filtering
JSON - Machine-readable structured data
Text - Human-readable terminal output
XML - Interchange format
Cobertura - XML format for CI/CD tools

See HTML Coverage Report Format for HTML report documentation.

Example:

# Interactive Terminal UI - new!
ucis view coverage.ucis

# Import coverage from various sources
ucis convert --input-format vltcov coverage.dat --out coverage.xml

# Import cocotb or AVL coverage (auto-detected)
python -c "from ucis.format_detection import read_coverage_file; \
           db = read_coverage_file('coverage.xml')"

# Generate interactive HTML report
ucis report coverage.ucis -of html -o report.html

# Analyze coverage
ucis show summary coverage.ucis

# Export to CI/CD formats
ucis show code-coverage coverage.ucis --output-format lcov > coverage.info

# Compare databases
ucis show compare baseline.ucis current.ucis

# Merge databases
ucis merge -o merged.ucis test1.ucis test2.ucis

See Verilator Coverage Import for Verilator import documentation.

See Coverage Import (cocotb and AVL) for cocotb-coverage and AVL import documentation.

MCP Server for AI Integration

PyUCIS includes a Model Context Protocol (MCP) server that enables AI agents and assistants to interact with coverage databases through a standardized API. This allows intelligent analysis, automated reporting, and natural language queries against your verification coverage data.

The MCP server provides 17+ specialized tools for:

Database Operations: Open, close, and manage multiple coverage databases
Coverage Analysis: Get summaries, identify gaps, analyze metrics
Advanced Queries: Covergroups, bins, assertions, toggle coverage
Comparison: Compare databases for regression detection
Export: Generate LCOV, Cobertura, JaCoCo, and Clover reports

See MCP Server for detailed documentation on installation, configuration, and integration with AI platforms like Claude Desktop.

Quick start:

# Install with MCP support
pip install pyucis[dev]

# Start the MCP server
pyucis-mcp-server

Contributors

Matthew Ballance