Port xsim_test from https://github.com/CruxML/rules_xilinx.

xsim_test is defined in vivado/defs.bzl. This can run and generate
a waveform. Manually tested waveform generation, passing and failing
conditions.

Author: Stephen Tridgell

vivado/BUILD

@@ -6,4 +6,5 @@ exports_files([
     "place_optimize.tcl.template",
     "route.tcl.template",
     "write_bitstream.tcl.template",
+    "xsim_test.tcl.template",
 ])

vivado/README.md

@@ -158,3 +158,34 @@ write_bitstream(
 ```
 
 It has the optional argument `_write_bitstream_tcl_template` which by default loads [write_bitstream.tcl.template](write_bitstream.tcl.template). This can be modified.
+
+## xsim_test
+
+Executes a test bench using the vivado simulator, xsim.
+
+Example from `vivado/tests`:
+```
+xsim_test(
+    name = "xsim_smoke_test",
+    module = ":xsim_smoke_tb",
+    module_top = "xsim_smoke_tb",
+    part_number = "xczu28dr-ffvg1517-2-e",
+    xilinx_env = ":xilinx_env.sh",
+    with_waveform = True,
+    tags = ["manual"],
+)
+```
+
+It has the optional argument `_xsim_test_template` which by default loads [_xsim_test_template.tcl.template](_xsim_test_template.tcl.template). This can be modified.
+
+It is tagged as `manual` so it is not run by CI tools. They do not have vivado installed.
+
+To get a waveform, do not use `bazel test`, use `bazel run` instead. For example
+`bazel run //vivado/tests:xsim_smoke_test` will then generate something like `bazel-out/k8-fastbuild/bin/vivado/tests/xsim_smoke_test.wdb`.
+
+To open this waveform in vivado:
+
+```
+current_fileset
+open_wave_database bazel-out/k8-fastbuild/bin/vivado/tests/xsim_smoke_test.wdb
+```

vivado/defs.bzl

@@ -43,32 +43,26 @@ def run_tcl_template(ctx, template, substitutions, xilinx_env, input_files, outp
 
     return [
         DefaultInfo(files = depset(outputs)),
+        vivado_log,
+        vivado_journal,
     ]
 
-def create_and_synth(
-        ctx,
-        with_synth,
-        synth_checkpoint = None,
-        timing_summary_report = None,
-        util_report = None,
-        synth_strategy = None):
-    """Create a project and optionally synthesize.
+def generate_file_load_tcl(module):
+    """Generate the strings needed for tcl.
 
-    Due to IP issues, it makes sense to do synthesis in project mode.
-    This function can also be used to generate a vivado project from the input sources.
+    Look at all the sources for a verilog module and make the needed commands
+    to get xilinx tools to load all the files needed.
 
     Args:
-        ctx: Context from a rule
-        with_synth: A flag indicating if synthesis should be run too.
-        synth_checkpoint: Optionally define the output synthesis checkpoint. Not used when creating a project only.
-        timing_summary_report: Optionally define the timing summary report output. Not used when creating a project only.
-        util_report: Optionally define the utilization report output. Not used when creating a project only.
-        synth_strategy: Optionally define the synthesis strategy to use. Not used when creating a project only.
+      module: The top level verilog module
 
     Returns:
-        DefaultInfo - Files generated by the project.
+      all_files: All file objects that the module depends on.
+      hdl_source_content: A string to load any hdl files in xilinx tools.
+      constraints_content: A string to load any constraints in xilinx tools.
+      tcl_content: A string to load any other tcl in xilinx tools.
     """
-    transitive_srcs = depset([], transitive = [ctx.attr.module[VerilogInfo].dag])
+    transitive_srcs = depset([], transitive = [module[VerilogInfo].dag])
     all_srcs = [verilog_info_struct.srcs for verilog_info_struct in transitive_srcs.to_list()]
     all_files = [src for sub_tuple in all_srcs for src in sub_tuple]
 
@@ -92,6 +86,38 @@ def create_and_synth(
         else:
             fail("Unknown file type: " + file.path)
 
+    return [
+        all_files,
+        hdl_source_content,
+        constraints_content,
+        tcl_content,
+    ]
+
+def create_and_synth(
+        ctx,
+        with_synth,
+        synth_checkpoint = None,
+        timing_summary_report = None,
+        util_report = None,
+        synth_strategy = None):
+    """Create a project and optionally synthesize.
+
+    Due to IP issues, it makes sense to do synthesis in project mode.
+    This function can also be used to generate a vivado project from the input sources.
+
+    Args:
+        ctx: Context from a rule
+        with_synth: A flag indicating if synthesis should be run too.
+        synth_checkpoint: Optionally define the output synthesis checkpoint. Not used when creating a project only.
+        timing_summary_report: Optionally define the timing summary report output. Not used when creating a project only.
+        util_report: Optionally define the utilization report output. Not used when creating a project only.
+        synth_strategy: Optionally define the synthesis strategy to use. Not used when creating a project only.
+
+    Returns:
+        DefaultInfo - Files generated by the project.
+    """
+    all_files, hdl_source_content, constraints_content, tcl_content = generate_file_load_tcl(ctx.attr.module)
+
     project_dir = ctx.actions.declare_directory(ctx.label.name)
 
     if with_synth:
@@ -134,7 +160,8 @@ def create_and_synth(
     )
 
 def _vivado_create_project_impl(ctx):
-    return create_and_synth(ctx, 0)
+    default_info = create_and_synth(ctx, 0)
+    return [default_info[0]]
 
 vivado_create_project = rule(
     implementation = _vivado_create_project_impl,
@@ -145,7 +172,7 @@ vivado_create_project = rule(
             mandatory = True,
         ),
         "module_top": attr.string(
-            doc = "The name of the verilog module to verilate.",
+            doc = "The name of the top level verilog module.",
             mandatory = True,
         ),
         "part_number": attr.string(
@@ -160,7 +187,7 @@ vivado_create_project = rule(
         ),
         "jobs": attr.int(
             doc = "Jobs to pass to vivado which defines the amount of parallelism.",
-            default = 4
+            default = 4,
         ),
         "_create_project_tcl_template": attr.label(
             doc = "The create project tcl template",
@@ -198,7 +225,7 @@ vivado_synthesize = rule(
             mandatory = True,
         ),
         "module_top": attr.string(
-            doc = "The name of the verilog module to verilate.",
+            doc = "The name of the top level verilog module.",
             mandatory = True,
         ),
         "part_number": attr.string(
@@ -217,7 +244,7 @@ vivado_synthesize = rule(
         ),
         "jobs": attr.int(
             doc = "Jobs to pass to vivado which defines the amount of parallelism.",
-            default = 4
+            default = 4,
         ),
         "_create_project_tcl_template": attr.label(
             doc = "The create project tcl template",
@@ -285,7 +312,7 @@ vivado_synthesis_optimize = rule(
         ),
         "threads": attr.int(
             doc = "Threads to pass to vivado which defines the amount of parallelism.",
-            default = 8
+            default = 8,
         ),
         "_synthesis_optimize_template": attr.label(
             doc = "The synthesis optimzation tcl template",
@@ -351,7 +378,7 @@ vivado_placement = rule(
         ),
         "threads": attr.int(
             doc = "Threads to pass to vivado which defines the amount of parallelism.",
-            default = 8
+            default = 8,
         ),
         "_placement_template": attr.label(
             doc = "The placement tcl template",
@@ -417,7 +444,7 @@ vivado_place_optimize = rule(
         ),
         "threads": attr.int(
             doc = "Threads to pass to vivado which defines the amount of parallelism.",
-            default = 8
+            default = 8,
         ),
         "_place_optimize_template": attr.label(
             doc = "The placement tcl template",
@@ -499,7 +526,7 @@ vivado_routing = rule(
         ),
         "threads": attr.int(
             doc = "Threads to pass to vivado which defines the amount of parallelism.",
-            default = 8
+            default = 8,
         ),
         "_route_template": attr.label(
             doc = "The placement tcl template",
@@ -526,14 +553,15 @@ def _vivado_write_bitstream_impl(ctx):
 
     outputs = [bitstream]
 
-    return run_tcl_template(
+    default_info = run_tcl_template(
         ctx,
         ctx.file._write_bitstream_template,
         substitutions,
         ctx.file.xilinx_env,
         [checkpoint_in],
         outputs,
     )
+    return [default_info[0]]
 
 vivado_write_bitstream = rule(
     implementation = _vivado_write_bitstream_impl,
@@ -618,3 +646,97 @@ def vivado_flow(name, module, module_top, part_number, xilinx_env, tags = []):
         xilinx_env = xilinx_env,
         tags = tags,
     )
+
+def _xsim_test_impl(ctx):
+    all_files, hdl_source_content, constraints_content, tcl_content = generate_file_load_tcl(ctx.attr.module)
+
+    project_dir = ctx.actions.declare_directory("{}_prj".format(ctx.label.name))
+    if (ctx.attr.with_waveform):
+        with_waveform_str = "1"
+        wave_db = ctx.actions.declare_file("{}.wdb".format(ctx.label.name))
+        wave_db_path = wave_db.path
+        outputs = [project_dir, wave_db]
+    else:
+        with_waveform_str = "0"
+        wave_db_path = ""
+        outputs = [project_dir]
+
+    substitutions = {
+        "{{PART_NUMBER}}": ctx.attr.part_number,
+        "{{HDL_SOURCE_CONTENT}}": hdl_source_content,
+        "{{TCL_CONTENT}}": tcl_content,
+        "{{CONSTRAINTS_CONTENT}}": constraints_content,
+        "{{MODULE_TOP}}": ctx.attr.module_top,
+        "{{PROJECT_DIR}}": project_dir.path,
+        "{{WITH_WAVEFORM}}": with_waveform_str,
+        "{{WAVE_DB}}": wave_db_path,
+    }
+
+    _, vivado_log, vivado_journal = run_tcl_template(
+        ctx,
+        ctx.file._xsim_test_template,
+        substitutions,
+        ctx.file.xilinx_env,
+        all_files,
+        outputs,
+    )
+
+    outputs.append(vivado_log)
+    outputs.append(vivado_journal)
+
+    log_runfiles = ctx.runfiles(files = [vivado_log])
+
+    error_parser = "if grep -q Error {}; then\n".format(vivado_log.short_path)
+    error_parser += "cat {}\n".format(vivado_log.short_path)
+    error_parser += "exit 64\n"
+    error_parser += "fi"
+
+    ctx.actions.write(
+        output = ctx.outputs.executable,
+        content = error_parser,
+        is_executable = True,
+    )
+
+    return [
+        DefaultInfo(
+            files = depset(outputs),
+            runfiles = log_runfiles,
+            executable = ctx.outputs.executable,
+        ),
+    ]
+
+xsim_test = rule(
+    implementation = _xsim_test_impl,
+    doc = "Use the vivado tool xsim to test.",
+    test = True,
+    attrs = {
+        "module": attr.label(
+            doc = "The top level build.",
+            providers = [VerilogInfo],
+            mandatory = True,
+        ),
+        "module_top": attr.string(
+            doc = "The name of the top level verilog module.",
+            mandatory = True,
+        ),
+        "part_number": attr.string(
+            doc = "The targeted xilinx part.",
+            mandatory = True,
+        ),
+        "with_waveform": attr.bool(
+            doc = "Generate with a waveform",
+            default = False,
+        ),
+        "xilinx_env": attr.label(
+            doc = "A shell script to source the vivado environment and " +
+                  "point to license server",
+            mandatory = True,
+            allow_single_file = [".sh"],
+        ),
+        "_xsim_test_template": attr.label(
+            doc = "The tcl template to run on vivado.",
+            default = "@rules_hdl//vivado:xsim_test.tcl.template",
+            allow_single_file = [".template"],
+        ),
+    },
+)

vivado/tests/BUILD

@@ -3,6 +3,7 @@ load("//verilator:defs.bzl", "verilator_cc_library")
 load(
     "//vivado:defs.bzl",
     "vivado_flow",
+    "xsim_test",
 )
 
 verilog_library(
@@ -27,6 +28,21 @@ cc_test(
     ],
 )
 
+verilog_library(
+    name = "xsim_smoke_tb",
+    srcs = ["xsim_smoke_tb.sv"],
+)
+
+xsim_test(
+    name = "xsim_smoke_test",
+    module = ":xsim_smoke_tb",
+    module_top = "xsim_smoke_tb",
+    part_number = "xczu28dr-ffvg1517-2-e",
+    tags = ["manual"],
+    with_waveform = True,
+    xilinx_env = ":xilinx_env.sh",
+)
+
 verilog_library(
     name = "johnson_counter_top",
     srcs = [

vivado/tests/xsim_smoke_tb.sv

@@ -0,0 +1,15 @@
+
+module xsim_smoke_tb ();
+
+  logic clk = 0;
+  always #5ns clk = !clk;
+
+  initial begin
+    repeat (100) @(posedge clk);
+    assert (1)
+    else $error("A message about failed assertion");
+    repeat (100) @(posedge clk);
+    $finish();
+  end
+
+endmodule