Tunnel dvsim Integration

Simscope can be integrated into dvsim (aka dvsim.py), so that Regression and Job results will be automatically published into your Simscope instance, via the Tunnel.

This is a sample dvsim run with coverage enabled, published into Simscope:

dvsim checkout

To integrate with Simscope, this requires a dvsim source release from 2022 or newer (SHA a886c7eb7 or newer).

Integration

This describes how to integrate Simscope publishing into dvsim.

Copy simscope_publisher.py to util/dvsim directory.
Edit simscope_publisher.py and change the following lines:

# NOTE: change these variables for your Simscope environment
DEFAULT_TUNNEL_PATH    = '/path/bin/simscope-tunnel'
DEFAULT_TUNNEL_CONFIG  = '/path/config/simscope-tunnel.config' # Set to your tunnel default path

DEFAULT_TUNNEL_OPTIONS = '--retry-attempts=2'

DEFAULT_SIMSCOPE_PROJECT_NAME = '' # Set to your Simscope project name

INTEGRATED_BRANCHES = set(['main', 'master']) # Set to your integrated (mainline) branches

# Map from DVSim [target] => Simscope Job [category]
# > See https://admin-docs.simscope.com/server/simscope-config.html
# Change these based on your simscope configuration
# > Note: this must match categories in your simscope.config file
SIMSCOPE_CATEGORY_MAP = {
    'build':      'compile',
    'cov_merge':  'compile',
    'cov_report': 'compile',
    'run':        'sim',
}

Edit util/dvsim/dvsim.py

--- util/dvsim/dvsim.py    2022-10-21 13:27:20.000000000 -0500
+++ util/dvsim/dvsim.py    2022-10-21 13:27:46.000000000 -0500
@@ -728,13 +728,10 @@
         results = cfg.deploy_objects()

         # Generate results.
         cfg.gen_results(results)

+        import simscope_publisher
+        simscope_publisher.regr_finish()
+
         # Publish results
         if args.publish:
             cfg.publish_results()

Edit util/dvsim/Launcher.py

--- util/dvsim/Launcher.py        2022-10-21 13:30:50.000000000 -0500
+++ util/dvsim/Launcher.py        2022-10-21 19:16:20.000000000 -0500
@@ -10,10 +10,12 @@
 import sys
 from pathlib import Path

 from utils import VERBOSE, clean_odirs, mk_symlink, rm_path

+import simscope_publisher
+
 class LauncherError(Exception):

     def __init__(self, msg):
         self.msg = msg

@@ -136,10 +138,11 @@

         # One-time preparation of the workspace.
         if not Launcher.workspace_prepared:
             self.prepare_workspace(cfg.project, cfg.proj_root, cfg.args)
             Launcher.workspace_prepared = True
+            simscope_publisher.regr_start(cfg)

         # One-time preparation of the workspace, specific to the cfg.
         if cfg not in Launcher.workspace_prepared_for_cfg:
             self.prepare_workspace_for_cfg(cfg)
             Launcher.workspace_prepared_for_cfg.add(cfg)
@@ -351,5 +354,7 @@
         self.status = status
         if self.status != "P":
             assert err_msg and isinstance(err_msg, ErrorMessage)
             self.fail_msg = err_msg
             log.log(VERBOSE, err_msg.message)
+
+        simscope_publisher.job_finish(self)

Runtime: Environment variable

By default, results will not be published at runtime to Simscope. To enable publishing, set the SIMSCOPE_PUBLISH environment variable to a non-blank value.

For example:

$ SIMSCOPE_PUBLISH=1 ./util/dvsim/dvsim.py ./hw/ip/uart/dv/uart_sim_cfg.hjson --dry-run

Or alternatively you can set the environment variable permanently:

$ export SIMSCOPE_PUBLISH=1
$ ./util/dvsim/dvsim.py ./hw/ip/uart/dv/uart_sim_cfg.hjson

For debugging JSON:

$ SIMSCOPE_PUBLISH=debug ./util/dvsim/dvsim.py ./hw/ip/uart/dv/uart_sim_cfg.hjson --dry-run

Optional: Runtime environment reference

This table contains all environment variables supported, to allow runtime configuration of Simscope publishing, without needing to edit the Python source code.

To use, set any of the environment variables from your operating system shell.

ENV	Example value	Description
`$SIMSCOPE_PUBLISH`	`1`	`1` — Enable publish `debug` — Print JSON to `stderr` (skip publish) any other value — Publish disabled
`$SIMSCOPE_PROJECT`	`RocketChip`	Simscope project name
`$SIMSCOPE_REGRESSION`	`hello_smoke/12345`	Optional: if you want to override the regression name
`$TUNNEL_PATH`	`/path/simscope-tunnel`	Path to simscope tunnel executable
`$TUNNEL_CONFIG`	`/path/tunnel.config`	Path to tunnel config file
`$TUNNEL_OPTIONS`	`--retry-attempts=2`	Set tunnel command-line options

Note: you can also override $RABBIT_URL or $ROUTING_KEY (to override your tunnel.config)

Coverage

Simscope can capture line/functional coverage results from dvsim, if you have enabled coverage (ie using the --cov option).

Notes:

Coverage integration with dvsim is supported for most simulators (VCS, NCSim/Incisive/Xcelium, Questa, DSim).
Most of the coverage integration source is located at:
- hw/dv/tools/dvsim/SIMULATOR.hjson
- util/dvsim/sim_utils.py
- util/dvsim/Deploy.py
- util/dvsim/SimCfg.py

Version

The latest version of simscope_publisher is 0.97

Simscope Administration Guide