Public entry point for riviera_sim_test.
Rules
riviera_sim_test
load("@rules_riviera//riviera:riviera_sim_test.bzl", "riviera_sim_test")
riviera_sim_test(name, deps, data, asim_opts, env, exec_requirements, extra_tops, generics, jobs,
link_libraries, post_processor, pre_processor, top)
Elaborate + simulate a Riviera library under vsimsa as a Bazel test.
Takes one or more deps — each a riviera_library — and a fully-qualified
top (e.g. "my_lib.my_tb") that asim elaborates. Every library a
dep's library.cfg declares is vmapped by absolute path before
elaboration, so cross-library instantiation works out of the box.
asim_opts and env support Bazel's location templates
($(location ...), $(rlocationpath ...), execpath / rootpath and
their plural forms) against targets in data. Each template is
runfiles-resolved to an absolute path at test time, in place, so
-f $(location :f) or +define+HEX=$(rlocationpath :rom) work as
written.
Coverage kicks in automatically under bazel coverage: the launcher
adds Riviera's ACDB coverage flags, renders html + text reports into
$TEST_UNDECLARED_OUTPUTS_DIR, and converts the text report to lcov
via acdb2lcov for $COVERAGE_OUTPUT_FILE.
Seeding — RIVIERA_SEED carries the simulation seed in both
directions. Set it (--test_env=RIVIERA_SEED=42, or from a
pre_processor env fragment) to pin the run; leave it unset and the
launcher picks a fresh value per run. Either way the resolved seed
is passed to asim as -random_seed/-sv_seed, printed to the test
log as riviera_sim_test seed: <n>, and re-exported as
RIVIERA_SEED so the simulation and anything it spawns can read it.
No other seed variable is set — a harness wanting its framework's own
variable should set it alongside RIVIERA_SEED from a single value in
its pre_processor.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| deps | riviera_library targets holding the design under test, including top. | List of labels | required | |
| data | Runtime data (memory init files, .f lists, VPI shared libs, ...) staged into runfiles. Targets referenced from asim_opts / env templates must appear here. | List of labels | optional | [] |
| asim_opts | Extra arguments forwarded to asim. Location templates expand against data (see the rule doc). | List of strings | optional | [] |
| env | Extra environment variables for the test. Location templates expand against data (see the rule doc). | Dictionary: String -> String | optional | {} |
| exec_requirements | Extra execution_requirements merged over the toolchain's (resources:<name> for each of its resources, plus requires-network when it sets it). | Dictionary: String -> String | optional | {} |
| extra_tops | Additional fully-qualified top-level units appended to top on the asim command line. asim instantiates each at simulator root — use for co-elaborating helper modules like Xilinx xil_defaultlib.glbl whose internal signals (glbl.GSR, glbl.GTS) must exist for hierarchical references from user HDL (xpm_cdc, xpm_fifo, …) to resolve at elaboration. | List of strings | optional | [] |
| generics | Elaboration-time parameters / generics, bound by name at every level of the hierarchy (mapped to -G<name>=<value>). | Dictionary: String -> String | optional | {} |
| jobs | CPU slots to request from Bazel's scheduler. -1 inherits the toolchain's jobs; N > 0 adds cpu:N; anything else is no hint. Simulator parallelism flags go in asim_opts. | Integer | optional | -1 |
| link_libraries | RivieraLibraryInfo targets for pre-built libraries the design references but doesn't own (Xilinx simlibs, precompiled IP). Vmapped before deps, so a deps library wins any name collision. | List of labels | optional | [] |
| post_processor | Optional executable invoked after a successful simulation, before the test returns. Runs in the test's working directory — the runfiles root, like any other Bazel executable — so relative paths reach data deps the usual way. Everything the simulation produced is reachable through the environment rather than the CWD: vsimsa runs with its CWD set to $TEST_TMPDIR, so coverage.acdb, coverage.txt, coverage_html/, and anything the testbench itself wrote all land there. $COVERAGE_OUTPUT_FILE and $TEST_UNDECLARED_OUTPUTS_DIR are set as usual, alongside any env from the rule.A non-zero exit fails the test. | Label | optional | None |
| pre_processor | Optional executable target invoked before vsimsa, in $TEST_TMPDIR with the test's runfiles + env. Any executable label works (py_binary, sh_binary, py_venv_binary, custom rules setting DefaultInfo(executable = ...), etc.).Env-fragment contract: the launcher exports RIVIERA_PRE_PROCESSOR_ENV_FILE=<path> when invoking the pre_processor. If the pre_processor writes K=V\n-per-line contents to that file, the launcher parses each line and setenvs it before spawning vsimsa. Blank lines and lines starting with # are skipped; malformed lines fail the test loudly. This is the intended channel for pre_processor-computed values (venv paths, per-run tmpdirs, etc.) that the sim needs in env.A non-zero exit fails the test. | Label | optional | None |
| top | Fully-qualified HDL top-level unit passed to asim, e.g. "my_lib.my_tb". | String | required |