Make covergroupgen a first-class package with better error messages

Author: jordancarlin

Makefile

@@ -117,7 +117,7 @@ clean: clean-tests
 .PHONY: covergroupgen
 covergroupgen: $(STAMP_DIR)/covergroupgen.stamp
 $(STAMP_DIR)/covergroupgen.stamp: $(COVERGROUPGEN_DEPS) $(TESTPLANS) Makefile | $(STAMP_DIR)
-	$(UV_RUN) generators/coverage/covergroupgen.py
+	$(UV_RUN) covergroupgen testplans $(if $(EXTENSIONS),--extensions $(EXTENSIONS)) $(if $(EXCLUDE_EXTENSIONS),--exclude $(EXCLUDE_EXTENSIONS))
 	@touch $@
 
 .PHONY: testgen
@@ -149,7 +149,8 @@ tests: covergroupgen testgen privheaders
 .PHONY: clean-tests
 clean-tests:
 	rm -rf $(SRCDIR64) $(SRCDIR32) $(SRCDIR64E) $(SRCDIR32E) $(PRIVHEADERSDIR)
-	rm -rf fcov/unpriv/*
+	rm -rf coverpoints/unpriv/*
+	rm -rf coverpoints/coverage/*
 	rm -rf $(STAMP_DIR)
 
 $(PRIVHEADERSDIR) $(STAMP_DIR):

generators/coverage/pyproject.toml

@@ -0,0 +1,19 @@
+# pyproject.toml
+# covergroupgen python project configuration file for riscv-arch-test
+# SPDX-License-Identifier: Apache-2.0
+
+[project]
+name = "covergroupgen"
+version = "0.1.0"
+description = "RISC-V Architectural Certification Covergroup Generator"
+authors = [{ name = "Jordan Carlin", email = "jcarlin@hmc.edu" }]
+requires-python = ">=3.12"
+dependencies = ["typer>=0.20.0", "rich>=13.0.0"]
+
+[project.scripts]
+covergroupgen = "covergroupgen.cli:main"
+
+##### BUILD #####
+[build-system]
+requires = ["uv_build>=0.9.4,<0.10.0"]
+build-backend = "uv_build"

generators/coverage/src/covergroupgen/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# Deliberately empty file. Necessary for Python package recognition.

generators/coverage/src/covergroupgen/cli.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+
+##################################
+# cli.py
+#
+# Command-line interface for covergroup generation.
+# jcarlin@hmc.edu March 2026
+# SPDX-License-Identifier: Apache-2.0
+##################################
+
+"""Top-level command-line interface for covergroup generation."""
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from covergroupgen.generate import generate_covergroups
+
+# CLI interface setup
+covergroupgen_app = typer.Typer(context_settings={"help_option_names": ["-h", "--help"]}, add_completion=False)
+
+
+@covergroupgen_app.command()
+def run(
+    testplan_dir: Annotated[
+        Path, typer.Argument(exists=True, file_okay=False, help="Directory containing testplan CSV files")
+    ],
+    *,
+    output_dir: Annotated[
+        Path, typer.Option("-o", "--output", file_okay=False, help="Output directory for covergroups")
+    ] = Path("coverpoints"),
+    extensions: Annotated[
+        str, typer.Option("--extensions", "-e", help="Comma-separated list of extensions to generate covergroups for")
+    ] = "all",
+    exclude: Annotated[
+        str,
+        typer.Option(
+            "--exclude", "-x", help="Comma-separated list of extensions to exclude from covergroup generation"
+        ),
+    ] = "",
+) -> None:
+    """Generate functional covergroups for RISC-V instructions from CSV testplans."""
+    generate_covergroups(testplan_dir, output_dir, extensions, exclude)
+
+
+def main() -> None:
+    covergroupgen_app()
+
+
+if __name__ == "__main__":
+    main()

generators/coverage/covergroupgen.py …s/coverage/src/covergroupgen/generate.pygenerators/coverage/covergroupgen.py renamed to generators/coverage/src/covergroupgen/generate.py generators/coverage/covergroupgen.py renamed to generators/coverage/src/covergroupgen/generate.py

@@ -1,6 +1,5 @@
-#!/usr/bin/env python3
 ##################################
-# covergroupgen.py
+# generate.py
 #
 # David_Harris@hmc.edu 15 August 2025
 # SPDX-License-Identifier: Apache-2.0
@@ -9,11 +8,15 @@
 ##################################
 
 import csv
+import importlib.resources
 import math
 import re
+from difflib import get_close_matches
 from pathlib import Path
 from typing import TextIO
 
+from rich.progress import track
+
 ##################################
 # Functions
 ##################################
@@ -25,21 +28,38 @@
 # the value being a list of covergroups for that instruction
 
 
-def read_testplans(testplans_dir: Path) -> tuple[dict[str, dict[tuple[str, str], list[str]]], dict[str, str]]:
+def read_testplans(
+    testplan_dir: Path,
+    extensions: str = "all",
+    exclude: str = "",
+) -> tuple[dict[str, dict[tuple[str, str], list[str]]], dict[str, str]]:
     """
     Iterates over all of the CSV testplan files in the provided directory. It populates a dictionary of dictionaries with
     the top level key being the architecture/extension (e.g. RV64I), the second level key being a tuple of
     (instruction mnemonic, type) to allow duplicate instructions with different types, and the value being a list
     of coverpoints for that instruction.
     """
+    # Parse extension filter lists
+    include_set: set[str] | None = None
+    if extensions != "all":
+        include_set = {ext.strip() for ext in extensions.split(",") if ext.strip()}
+    exclude_set: set[str] = set()
+    if exclude:
+        exclude_set = {ext.strip() for ext in exclude.split(",") if ext.strip()}
+
     testplans: dict[str, dict[tuple[str, str], list[str]]] = {}
     arch_sources: dict[str, str] = {}
-    coverplan_dirs = [(testplans_dir, "unpriv")]
+    coverplan_dirs = [(testplan_dir, "unpriv")]
     for coverplan_dir, source in coverplan_dirs:
         if not coverplan_dir.exists():
             continue  # Skip missing directories
         for file in coverplan_dir.rglob("*.csv"):
             arch = file.stem
+            # Filter by extension name
+            if include_set is not None and arch not in include_set:
+                continue
+            if arch in exclude_set:
+                continue
             with file.open() as csvfile:
                 reader = csv.DictReader(csvfile)
                 tp: dict[tuple[str, str], list[str]] = {}
@@ -83,19 +103,28 @@ def read_testplans(testplans_dir: Path) -> tuple[dict[str, dict[tuple[str, str],
     return testplans, arch_sources
 
 
-def read_covergroup_templates(template_dir: Path) -> dict[str, str]:
-    """Read the covergroup templates from the templates directory."""
-    covergroupTemplates: dict[str, str] = {}
-    for file in template_dir.rglob("*.sv"):
-        cg = file.stem
-        covergroupTemplates[cg] = file.read_text()
-    return covergroupTemplates
+def read_covergroup_templates(package: str = "covergroupgen.templates") -> dict[str, str]:
+    """Recursively read all .sv covergroup templates from the given package and its sub-packages."""
+    templates: dict[str, str] = {}
+    for item in importlib.resources.files(package).iterdir():
+        if item.is_file() and item.name.endswith(".sv"):
+            templates[item.name.removesuffix(".sv")] = item.read_text()
+        elif item.is_dir() and not item.name.startswith("__"):
+            templates.update(read_covergroup_templates(f"{package}.{item.name}"))
+    return templates
 
 
 def customize_template(covergroup_templates: dict[str, str], name: str, arch: str, instr: str, effew: str = "") -> str:
     """Customize the covergroup template with the given parameters and pick from RV32/RV64 as necessary."""
     if name not in covergroup_templates:
-        raise ValueError(f"No template found for '{name}'. Check if there are spaces before or after coverpoint name.")
+        available = list(covergroup_templates.keys())
+        similar = get_close_matches(name, available, n=5, cutoff=0.4)
+        msg = f"No template found for '{name}'. "
+        if similar:
+            msg += f"Similar templates: {', '.join(similar)}. "
+        templates_dir = importlib.resources.files("covergroupgen.templates")
+        msg += f"To add support, create a new .sv template in '{templates_dir}'."
+        raise ValueError(msg)
     template = covergroup_templates[name]
     instr_nodot = instr.replace(".", "_")
     template = (
@@ -305,14 +334,13 @@ def write_covergroups(
 
     with (coverageHeaderDir / "RISCV_instruction_sample.svh").open("w") as fsample:
         fsample.write(customize_template(covergroup_templates, "instruction_sample_header", "NA", "NA"))
-        for arch, tp in test_plans.items():
+        for arch, tp in track(test_plans.items(), description="[cyan]Generating covergroups...", total=len(test_plans)):
             covergroupSubDir = arch_sources.get(arch, "unpriv")
             covergroup_out_dir = covergroup_dir / covergroupSubDir
             covergroup_out_dir.mkdir(parents=True, exist_ok=True)
 
             file = arch + "_coverage.svh"
             initfile = arch + "_coverage_init.svh"
-            print("***** Writing " + file)
 
             vector = arch.startswith(("Vx", "Zv", "Vls", "Vf"))
             effew = get_effew(arch) if vector else ""
@@ -386,15 +414,7 @@ def write_covergroups(
 ##################################
 # Main Python Script
 ##################################
-
-
-def main(testplan_dir: Path, output_dir: Path) -> None:
-    test_plans, arch_sources = read_testplans(testplan_dir)
-    covergroup_templates = read_covergroup_templates(Path(__file__).parent / "templates")
+def generate_covergroups(testplan_dir: Path, output_dir: Path, extensions: str = "all", exclude: str = "") -> None:
+    test_plans, arch_sources = read_testplans(testplan_dir, extensions, exclude)
+    covergroup_templates = read_covergroup_templates()
     write_covergroups(test_plans, covergroup_templates, arch_sources, output_dir)
-
-
-if __name__ == "__main__":
-    test_plan_dir = (Path(__file__).parent / "../../testplans").resolve()
-    output_dir = (Path(__file__).parent / "../../coverpoints").resolve()
-    main(test_plan_dir, output_dir)

generators/testgen/src/testgen/__init__.py

@@ -1 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
 # Deliberately empty file. Necessary for Python package recognition.

pyproject.toml

@@ -4,7 +4,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 [tool.uv.workspace]
-members = ["framework", "generators/testgen"]
+members = ["framework", "generators/testgen", "generators/coverage"]
 
 [dependency-groups]
 dev = [