[src] Integrate DVPlan tool commands

- Integrate DVPlan subcommands. These commands will be run only if:
    - DVPlan tool is available
    - Coverage is enabled
    - A "".vplan" file is found in the cuurent sim_cfg.hjson file
- When the condition are met, at the end the regression/simulation, the
  DVPlan tool will:
    - Check the coverage of the specification
    - Generate a derived vPlan in the simulation directory
    - Perform back-annotation of the vPlan with the coverage data
    - Compute the coverage of the vPlan
    - Generate a report based on obtained annotated vPlan

Signed-off-by: martin-velay <mvelay@lowrisc.org>

Author: martin-velay

src/dvsim/job/deploy.py

@@ -30,9 +30,9 @@
     from dvsim.modes import BuildMode
     from dvsim.sim.flow import SimCfg
 
-
 __all__ = (
     "CompileSim",
+    "CovVPlan",
     "Deploy",
 )
 
@@ -1028,3 +1028,88 @@ def _set_attrs(self) -> None:
         self.qual_name = self.target
         self.full_name = f"{self.sim_cfg.name}{self._variant_suffix}:{self.qual_name}"
         self.input_dirs += [self.cov_merge_db_dir]
+
+
+class CovVPlan(Deploy):
+    """Abstraction for generating a Verification Plan (vPlan) report using DVPlan."""
+
+    target = "cov_vplan"
+    weight = 10
+
+    def __init__(self, cov_report_job, sim_cfg) -> None:
+        self.report_job = cov_report_job
+        super().__init__(sim_cfg)
+        self.dependencies.append(cov_report_job)
+
+    def _define_attrs(self) -> None:
+        super()._define_attrs()
+        self.mandatory_cmd_attrs.update(
+            {
+                "proj_root": False,
+                "vplan": False,
+            }
+        )
+        self.mandatory_misc_attrs.update(
+            {
+                "dut_instance": False,
+            }
+        )
+
+    def _set_attrs(self) -> None:
+        self.cov_vplan_dir = f"{self.sim_cfg.scratch_path}/{self.target}"
+
+        super()._set_attrs()
+        self.qual_name = self.target
+        self.full_name = f"{self.sim_cfg.name}{self._variant_suffix}:{self.qual_name}"
+
+        self.prepare_opts = self.sim_cfg.cov_vplan_prepare_opts
+        self.process_opts = self.sim_cfg.cov_vplan_process_opts
+
+        # Calculate IP root and derive the stem used to name output files.
+        vplan_path = Path(self.vplan)
+        self.ip_root = str(vplan_path.parent.parent)
+        vplan_stem = vplan_path.stem
+
+        # Determine paths for the intermediate HJSON and the final HTML report.
+        # Use the vplan filename stem so the outputs are named after the plan
+        # (e.g. "rv_timer_vplan_annotated.hjson") rather than the sim name.
+        self.annotated_hjson = f"{self.odir}/{vplan_stem}_annotated.hjson"
+        self.gen_html = f"{self.odir}/{vplan_stem}_annotated.html"
+        self.output_dirs = [self.odir]
+
+    def _construct_cmd(self) -> str:
+        """Construct the pure bash shell command, bypassing the base Makefile assumption."""
+        import shlex
+        import shutil
+
+        if shutil.which("dvplan") is None:
+            fallback = (
+                "echo 'WARNING: dvplan tool not installed in PATH. Skipping vPlan generation.'"
+            )
+            return f"/usr/bin/env bash -c {shlex.quote(fallback)}"
+
+        plugin = get_sim_tool_plugin(tool=self.sim_cfg.tool)
+
+        def format_opts(opts):
+            return " ".join(opts) if isinstance(opts, list) else str(opts)
+
+        prepare_opts_str = format_opts(self.prepare_opts)
+        process_opts_str = format_opts(self.process_opts)
+
+        prepare_cmd = f"dvplan prepare_vplan {prepare_opts_str} {self.ip_root} {self.vplan} {self.annotated_hjson}"
+        prepare_cmd = " ".join(prepare_cmd.split())
+
+        vendor_tool = f"{self.sim_cfg.tool}_report"
+        cov_report_txt = getattr(self.report_job, "cov_report_txt", "")
+        report_path = plugin.get_dvplan_report_path(
+            cov_report_dir=self.report_job.cov_report_dir, cov_report_txt=cov_report_txt
+        )
+
+        process_cmd = (
+            f"dvplan process_results {process_opts_str} --coverage {vendor_tool} {report_path} "
+            f"-R {self.gen_html} -s {self.sim_cfg.name} {self.dut_instance} {self.annotated_hjson}"
+        )
+        process_cmd = " ".join(process_cmd.split())
+
+        full_command = f"set -e; mkdir -p {self.odir}; {prepare_cmd} && {process_cmd}"
+        return f"/usr/bin/env bash -c {shlex.quote(full_command)}"

src/dvsim/sim/data.py

@@ -192,6 +192,8 @@ class SimFlowResults(BaseModel):
     """Coverage metrics."""
     cov_report_page: Path | None
     """Optional path linking to the generated coverage report dashboard page."""
+    vplan_report_page: Path | None
+    """Optional path linking to the generated verification plan (vPlan) reports."""
 
     failed_jobs: BucketedFailures
     """Bucketed failed job overview."""

src/dvsim/sim/flow.py

@@ -22,6 +22,7 @@
     CovMerge,
     CovReport,
     CovUnr,
+    CovVPlan,
     RunTest,
 )
 from dvsim.job.status import JobStatus
@@ -157,6 +158,13 @@ def __init__(self, flow_cfg_file, hjson_data, args, mk_config) -> None:
         self.cov_report_dir = ""
         self.cov_report_page = ""
 
+        # Options for vPlan processing
+        # dut_instance is the hierarchical testbench path to the DUT (e.g. "tb.dut"),
+        # distinct from `name`/`qual_name` which identify the sim config itself.
+        self.dut_instance = ""
+        self.cov_vplan_prepare_opts = []
+        self.cov_vplan_process_opts = []
+
         # Options from tools - for building and running tests
         self.build_cmd = ""
         self.flist_gen_cmd = ""
@@ -550,6 +558,10 @@ def _create_deploy_objects(self) -> None:
                 self.cov_report_deploy = CovReport(self.cov_merge_deploy, self)
                 self.deploy += [self.cov_merge_deploy, self.cov_report_deploy]
 
+                if getattr(self, "vplan", False):
+                    self.cov_vplan_deploy = CovVPlan(self.cov_report_deploy, self)
+                    self.deploy.append(self.cov_vplan_deploy)
+
     def _cov_analyze(self) -> None:
         """Open GUI tool for coverage analysis.
 
@@ -821,6 +833,13 @@ def make_test_result(tr) -> TestResult | None:
             cov_report_dir = self.cov_report_dir or "cov_report"
             cov_report_page = Path(cov_report_dir, self.cov_report_page)
 
+        vplan_report_page = None
+        if getattr(self, "cov_vplan_deploy", None):
+            vplan_stem = Path(self.vplan).stem
+            vplan_report_page = (
+                Path(self.scratch_path) / CovVPlan.target / f"{vplan_stem}_annotated.html"
+            )
+
         failures = BucketedFailures.from_job_status(results=run_results)
         if failures.buckets:
             self.errors_seen = True
@@ -835,6 +854,7 @@ def make_test_result(tr) -> TestResult | None:
             stages=stages,
             coverage=coverage_model,
             cov_report_page=cov_report_page,
+            vplan_report_page=vplan_report_page,
             failed_jobs=failures,
             passed=total_passed,
             total=total_runs,

src/dvsim/sim/report.py

@@ -329,10 +329,12 @@ def render_coverage_table(self, results: SimFlowResults) -> str:
             for k, v in results.coverage.flattened().items()
             if v is not None
         }
-        if not cov_results and not results.cov_report_page:
+        if not cov_results and not results.cov_report_page and not results.vplan_report_page:
             return ""
 
         report_md = "## Coverage Results"
+        if results.vplan_report_page:
+            report_md += f"\n### [vPlan Dashboard]({results.vplan_report_page})"
         if results.cov_report_page:
             report_md += f"\n### [Coverage Dashboard]({results.cov_report_page})"
         if cov_results:

src/dvsim/sim/tool/base.py

@@ -95,3 +95,17 @@ def set_additional_attrs(deploy: "Deploy") -> None:
 
         """
         ...
+
+    @staticmethod
+    def get_dvplan_report_path(cov_report_dir: str, cov_report_txt: str) -> str:
+        """Return the path to the coverage report required by DVPlan.
+
+        Args:
+            cov_report_dir: Path to the coverage report directory.
+            cov_report_txt: Path to the text-based coverage report.
+
+        Returns:
+            Path to the target coverage report file or directory.
+
+        """
+        ...

src/dvsim/sim/tool/vcs.py

@@ -145,3 +145,17 @@ def set_additional_attrs(deploy: "Deploy") -> None:
             deploy: the deploy object to mutate.
 
         """
+
+    @staticmethod
+    def get_dvplan_report_path(cov_report_dir: str, cov_report_txt: str) -> str:
+        """Return the path to the coverage report required by DVPlan.
+
+        Args:
+            cov_report_dir: Path to the coverage report directory.
+            cov_report_txt: Path to the text-based coverage report.
+
+        Returns:
+            Path to the target coverage report file or directory.
+
+        """
+        return cov_report_dir

src/dvsim/sim/tool/xcelium.py

@@ -170,3 +170,17 @@ def set_additional_attrs(deploy: "Deploy") -> None:
             deploy: the deploy object to mutate.
 
         """
+
+    @staticmethod
+    def get_dvplan_report_path(cov_report_dir: str, cov_report_txt: str) -> str:
+        """Return the path to the coverage report required by DVPlan.
+
+        Args:
+            cov_report_dir: Path to the coverage report directory.
+            cov_report_txt: Path to the text-based coverage report.
+
+        Returns:
+            Path to the target coverage report file or directory.
+
+        """
+        return cov_report_dir