Fix some Vivado issues (SystemVerilog support, space in file name, environment variable)

Author: oscargus

docs/conf.py

@@ -30,6 +30,7 @@
 
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
@@ -113,7 +114,7 @@
 # -- InterSphinx --------------------------------------------------------------
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3.8/", None),
+    "python": ("https://docs.python.org/3/", None),
     "pytest": ("https://docs.pytest.org/en/latest/", None),
     "osvb": ("https://umarcor.github.io/osvb", None),
 }

docs/index.rst

@@ -49,6 +49,7 @@ often"* approach through automation. :ref:`Read more <about>`
    py/ui
    hdl_libraries
    examples
+   tool_integration/index
 
 .. toctree::
    :caption: Continuous Integration

docs/tool_integration/index.rst

@@ -0,0 +1,11 @@
+.. _tool_integration:
+
+Tool Integration
+================
+There are additional integration support available for selected tools.
+
+Vivado Integration
+==================
+
+.. automodule:: vunit.vivado
+   :members:

vunit/vivado/__init__.py

@@ -13,3 +13,5 @@
     add_from_compile_order_file,
     create_compile_order_file,
 )
+
+__all__ = ["run_vivado", "add_from_compile_order_file", "create_compile_order_file"]

vunit/vivado/vivado.py

@@ -9,15 +9,21 @@
 """
 
 from subprocess import check_call
-from os import makedirs
+from os import makedirs, environ
 from pathlib import Path
 
 
 def add_from_compile_order_file(
     vunit_obj, compile_order_file, dependency_scan_defaultlib=True, fail_on_non_hdl_files=True
 ):  # pylint: disable=too-many-locals
     """
-    Add Vivado IP:s from a compile order file
+    Add Vivado IP:s from a compile order file.
+
+    :param project_file: :class:`~vunit.ui.VUnit`
+    :param compile_order_file: Compile-order file (from :func:`create_compile_order_file`)
+    :param dependency_scan_defaultlib: Whether to do VUnit scanning of ``xil_defaultlib``.
+    :param fail_on_non_hdl_files: Whether to fail on non-HDL files.
+
     """
     compile_order, libraries, include_dirs = _read_compile_order(compile_order_file, fail_on_non_hdl_files)
 
@@ -30,8 +36,9 @@ def add_from_compile_order_file(
 
     no_dependency_scan = []
     with_dependency_scan = []
+    verilog_file_endings = (".v", ".vp", ".sv")
     for library_name, file_name in compile_order:
-        is_verilog = file_name.endswith(".v") or file_name.endswith(".vp")
+        is_verilog = file_name.endswith(verilog_file_endings)
 
         # Optionally use VUnit dependency scanning for everything in xil_defaultlib, which
         # typically contains unencrypted top levels that instantiate encrypted implementations.
@@ -63,7 +70,13 @@ def add_from_compile_order_file(
 
 def create_compile_order_file(project_file, compile_order_file, vivado_path=None):
     """
-    Create compile file from Vivado project
+    Create compile file from Vivado project.
+
+    :param project_file: Project filename.
+    :param compile_order_file: Filename for to write compile-order file.
+    :param vivado_path: Path to Vivado install directory. If ``None``, the
+        environment variable ``VUNIT_VIVADO_PATH`` is used if set. Otherwise,
+        rely on that ``vivado`` is in the path.
     """
     print(f"Generating Vivado project compile order into {str(Path(compile_order_file).resolve())} ...")
 
@@ -81,18 +94,19 @@ def create_compile_order_file(project_file, compile_order_file, vivado_path=None
 
 def _read_compile_order(file_name, fail_on_non_hdl_files):
     """
-    Read the compile order file and filter out duplicate files
+    Read the compile order file and filter out duplicate files.
     """
     compile_order = []
     unique = set()
     include_dirs = set()
     libraries = set()
 
+    valid_file_types = ("Verilog", "VHDL", "Verilog Header", "SystemVerilog")
     with Path(file_name).open("r", encoding="utf-8") as ifile:
         for line in ifile.readlines():
             library_name, file_type, file_name = line.strip().split(",", 2)
 
-            if file_type not in ("Verilog", "VHDL", "Verilog Header"):
+            if file_type not in valid_file_types:
                 if fail_on_non_hdl_files:
                     raise RuntimeError(f"Unsupported compile order file: {file_name}")
                 print(f"Compile order file ignored: {file_name}")
@@ -119,12 +133,22 @@ def run_vivado(tcl_file_name, tcl_args=None, cwd=None, vivado_path=None):
     """
     Run tcl script in Vivado in batch mode.
 
-    Note: the shell=True is important in windows where Vivado is just a bat file.
+    :param tcl_file_name: Path to tcl file
+    :param tcl_args: tcl arguments passed to Vivado via the ``-tclargs`` switch
+    :param cwd: Passed as ``cwd`` to :func:`subprocess.check_call`
+    :param vivado_path: Path to Vivado install directory. If ``None``, the
+        environment variable ``VUNIT_VIVADO_PATH`` is used if set. Otherwise,
+        rely on that ``vivado`` is in the path.
     """
-    vivado = "vivado" if vivado_path is None else str(Path(vivado_path).resolve() / "bin" / "vivado")
-    cmd = f"{vivado} -nojournal -nolog -notrace -mode batch -source {str(Path(tcl_file_name).resolve())}"
+    vivado = (
+        str(Path(vivado_path).resolve() / "bin" / "vivado")
+        if vivado_path is not None
+        else environ.get("VUNIT_VIVADO_PATH", "vivado")
+    )
+    cmd = f'"{vivado}" -nojournal -nolog -notrace -mode batch -source "{Path(tcl_file_name).resolve()}"'
     if tcl_args is not None:
-        cmd += " -tclargs " + " ".join([str(val) for val in tcl_args])
+        cmd += " -tclargs " + " ".join([f'"{val}"' for val in tcl_args])
 
     print(cmd)
+    # shell=True is important in Windows where Vivado is just a bat file.
     check_call(cmd, cwd=cwd, shell=True)